Automate tasks with machine users

When using an external IDP with the Edge API, the standard process to obtain OIDC/OAuth2 access tokens from the CLI is the OAuth 2.0 Device Code flow. With this flow, you use the get_token utility, which prompts you to visit a URL in a browser to authenticate via your IDP, and then automatically unblocks your terminal.

However, your development environment might support automation for common development tasks, such as test automation or CI/CD pipelines. To automate these tasks when an external IDP is enabled, you need a way to obtain and refresh OAuth2 tokens headlessly, without requiring browser interaction.

Edge supports automated token generation through the use of headless machine users. A machine user can obtain OIDC/OAuth2 tokens via standard password grants without requiring a browser. That means you can completely automate the process of obtaining and refreshing tokens for your scripts.

Note: In OPDK 4.54.00, the legacy apigee-ssoadminapi.sh utility and the UAA /Users Management API have been removed. Machine users must now be created directly in OpenLDAP using the apigee-machineuser.sh utility.

Create a machine user

You can create a machine user that is used by all of your organizations, or create a separate machine user for each organization.

The machine user is created and stored directly in the local OpenLDAP directory and explicitly tagged as a machine user (employeeType: machineuser). This allows the Apigee SSO to securely authenticate the machine user via a password grant even when federated SAML/OIDC is strictly enforced for human users.

For detailed instructions on creating, listing, and managing machine users, see Manage machine users with apigee-machineuser.sh.

Obtain and refresh machine user tokens

You can use the get_token and acurl utilities provided in /opt/apigee/apigee-openldap/bin/, or standard curl, to obtain tokens for machine users.

Using Apigee Utilities: The get_token and acurl wrappers automatically handle token caching, payload generation, and auto-refreshing. For detailed instructions and examples on using these tools, see Using the get_token and acurl utilities.
Using standard curl: If your automation scripts do not have access to the Apigee wrappers, you can interact directly with the Apigee SSO using the following standard curl commands:

To obtain and refresh tokens using standard curl:

Use the following API call to generate the initial access and refresh tokens directly from the Apigee SSO:

curl -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "accept: application/json;charset=utf-8" \
  -X POST http://Edge_SSO_IP_DNS:9099/token -s \
    -d 'grant_type=password&username=machineUserEmail&password=machineUserPassword&client_id=edgecli&client_secret=edgeclisecret&scope=openid%20profile%20email%20offline_access'

Note: The client_id and client_secret used above are the default values for the machine users and are implicitly configured in Apigee SSO.

Pass the access token to an Edge management API call in the Authorization: Bearer header:

curl -H "Authorization: Bearer access_token" \
  http://MS_IP_DNS:8080/v1/organizations/org_name

To later refresh the access token natively, use the following call that includes the refresh token:

curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" \
  -H "Accept: application/json;charset=utf-8" \
  -X POST http://Edge_SSO_IP_DNS:9099/token \
  -d 'grant_type=refresh_token&refresh_token=refreshToken&client_id=edgecli&client_secret=edgeclisecret'