Automate the token generation process

When using SAML with the Edge API, the process that you use to obtain OAuth2 access and refresh tokens from the SAML assertion is called the passcode flow. With the passcode flow, you use a browser to obtain a one-time passcode that you then use to obtain OAuth2 tokens.

However, your environment might support automation for common development tasks, such as test automation or Continuous Integration/Continuous Deployment (CI/CD). To automate these tasks when SAML is enabled, you need a way to obtain and refresh OAuth2 tokens without having to copy/paste a passcode from a browser.

Overview

Edge supports automated token generation in two ways. You can decide which way is better for your environment:

  • Machine users:

    Edge supports machine users in your Edge SAML zone. A machine user can obtain OAuth2 tokens without having to specify a passcode. That means you can completely automate the process of obtaining and refreshing OAuth2 tokens by using the Edge management API.

  • Long tokens:

    Long OAuth2 access tokens are valid for one hour, just like regular access tokens, but the refresh tokens are valid for 30 days instead of 12 hours.

    Long tokens use a different OAuth client type than regular tokens. That means you must configure get_token to use the long token client before you use it to obtain and refresh OAuth2 tokens. Typically, you do that configuration only on the machines running automated tasks so that normal users cannot create long tokens.

Machine users

On request, Apigee creates a machine user for you. You can have Apigee create a single machine user used by all of your organizations, or create a separate machine user for each organization.

The machine user is created and stored in the Edge datastore, not in your SAML identity provider. Therefore, you are not responsible for maintaining the machine user. If you later want to add other machine users or delete an existing machine user, you must contact Apigee Support.

When Apigee creates a new machine user, Apigee assigns it an email address and a default password. The email address of the machine user is in the form:

  • machine_orgname@yourdomain.com if you create a machine user for a specific organization.
  • machine_zonename@yourdomain.com if you create a single machine user for your entire zone.

Machine user email addresses are arbitrary and are not used for email activity. There's nothing special or programmatic about the addresses. The naming scheme is simply to help you know the scopes of your machine users.

Reset the machine user's password

After Apigee creates a machine user for you, you must reset the default password. You can then obtain OAuth2 tokens for the machine user.

To reset the machine user's password:

  1. Send a request to Apigee Support to create a machine user for a specific organization or zone.

    Apigee will send you the email address and password of the machine user.

  2. Update the access privileges of the machine user:
    1. Log in to the Edge UI.
    2. Add the machine user to your organizations.
    3. Assign the machine user to the necessary role.

    See Adding global users for more.

  3. Get a JSON Web Token (JWT) for the machine user by calling the SAML token endpoint, as the following example shows:
    curl -s -X POST https://zoneName.login.apigee.com/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "accept: application/json;charset=utf-8" \
    -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" \
    -d "grant_type=password&username=machine_user_email&password=machine_user_password"

    Where zoneName is your SAML zone and machine_user_email and machine_user_password are the machine user's email address and password that you received from Apigee.

    The JWT token returned by the SAML token endpoint includes an OAuth2 access token and is in the following form:

    {
      "access_token":"eyJhbGc...Au91CzslYg",
      "expires_in":43199,
      "scope":"scim.emails.read scim.me openid password.write approvals.me scim.ids.read oauth.approvals",
      "jti":"6f27ffac-3cde-4eb9-8341-5855333bbbf9"
    }
  4. Decode the JWT token to obtain the user_id of the machine user. There are many utilities that you can use to perform the decode. For example, you can install jwt from https://www.npmjs.com/package/jwt-cli.
  5. Use the following API call to change the machine user's password:
    curl -s -X PUT https://zoneName.login.apigee.com/Users/user_id/password \
      -H "Content-Type:application/json" \
      -H "Accept:application/json" \
      -H "Authorization: Bearer ACCESS_TOKEN_FROM_JWT" \
      -d '{ "oldPassword" : "old_password", "password" : "new_password"}'

    Where user_ID_from_JWT is the ID that you extracted from the JWT token, and ACCESS_TOKEN_FROM_JWT is the access token that you extracted from the JWT.

    This call returns a message in the following form:

    {
    "status":"ok",
    "message":"password updated"
    }

After you change the machine user's password, you can then use the Edge API to obtain and refresh OAuth2 tokens by passing the machine user's credentials instead of a passcode.

Get the machine user's OAuth2 tokens

To get the machine user's OAuth2 tokens:

  1. Generate the initial access and refresh tokens by calling the SAML token endpoint, as the following example shows:
    curl -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
      -H "accept: application/json;charset=utf-8" \
      -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" -X POST \
      https://zoneName.login.apigee.com/oauth/token -s \
      -d 'grant_type=password&username=machine_user_email&password=new_password'

    For authorization, pass a reserved OAuth2 client credential in the Authorization header. The call prints the access and refresh tokens to stdout.

  2. Pass the access token to an Edge management API call as the Bearer header:
    curl -H "Authorization: Bearer ACCESS_TOKEN" \
      https://api.enterprise.apigee.com/v1/organizations/orgName
  3. When the access token expires, you can refresh it by sending the refresh token to the SAML token endpoint, as the following example shows:
    curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" \
      -H "Accept: application/json;charset=utf-8" \
      -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" -X POST \
      https://zoneName.login.apigee.com/oauth/token \
      -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

Long tokens

When you create a long OAuth2 token from a SAML assertion, the OAuth2 access token is valid for one hour, but the refresh token is valid for 30 days, instead of the usual 12 hours.

Enable long tokens for your account

Before you can use long tokens, you must enable them for your account.

To enable long tokens:

  1. Contact Apigee Support to enable long tokens for your account.

    Apigee will send you an OAuth2 client ID and secret, in the following form:

    clientcli:clientclisecret
  2. Base64 encode clientcli:clientclisecret. You can do this with a utlity such as base64.
  3. Use the Base64-encoded clientcli:clientclisecret to generate long tokens.

Use a long refresh token

The process that you use to create and refresh your access tokens is the same as you use to create tokens for the Edge management API, as shown above, with the following differences:

  • If you use get_token to get your access and refresh tokens, you must set the CLIENT_AUTH environment variable for the long token client:
    export CLIENT_AUTH=Base64EncodedClientIDAndSecret
  • If you use the management API to get access and refresh tokens, you must pass the Base64-encoded client ID and secret as the Basic auth header when generating or refreshing OAuth2 tokens:
    -H "Authorization: Basic Base64EncodedClientIDAndSecret"

To get and use a long refresh token with get_token:

  1. Base64 encode the client ID and secret that you received from Apigee.
  2. Set the SSO_LOGIN_URL used by get_token:
    export SSO_LOGIN_URL=https://zoneName.login.apigee.com
  3. Set the CLIENT_AUTH environment variable to the Base64 encoded client ID and secret:
    export CLIENT_AUTH=amVua4guc2NsaTpqZW5raW5zY2xpc2VjcmV0
  4. In a browser, go to the following URL to obtain a one-time passcode:
    https://zoneName.login.apigee.com/passcode
  5. Invoke get_token to obtain the OAuth2 access token:
    get_token

    You are prompted to enter the one-time passcode that you obtained in previous step.

  6. Enter the passcode.

    The get_token utility gets the OAuth2 access token, prints it to stdout, and writes it and the long refresh token to ~/.sso-cli.

  7. Pass the access token to an Edge management API call as the Bearer header; for example:
    curl -H "Authorization: Bearer ACCESS_TOKEN" \
      https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

You can use the following API call to generate the initial access and refresh tokens:

curl -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "accept: application/json;charset=utf-8" \
  -H "Authorization: Basic amVua4guc2NsaTpqZW5raW5zY2xpc2VjcmV0" -X POST \
  https://zoneName.login.apigee.com/oauth/token -s \
  -d 'grant_type=password&response_type=token&passcode=passcode'

Pass the Base64 encoded string for the client ID and secret as the Basic header. The call prints the access and refresh tokens to stdout.

To later refresh the access token, use the following call that includes the refresh token generated from the previous call:

curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" \
  -H "Accept: application/json;charset=utf-8" \
  -H "Authorization: Basic amVua4guc2NsaTpqZW5raW5zY2xpc2VjcmV0" -X POST \
  https://zoneName.login.apigee.com/oauth/token \
  -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'