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.

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 API.

Create a machine user for SAML organizations

On request, Apigee creates a machine user for you for a SAML organization.

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. For authorization, pass the reserved OAuth2 client credential, ZWRnZWNsaTplZGdlY2xpc2VjcmV0, in the Authorization header.

    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 the reserved OAuth2 client credential, ZWRnZWNsaTplZGdlY2xpc2VjcmV0, 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'