Using Edge admin utilities and APIs after enabling Apigee SSO

This section describes how to run Edge system admin tools and commands after enabling Apigee SSO. Many tasks on Edge require system administration credentials, such as:

  • Creating organizations and environments
  • Adding and removing Edge components
  • Running apigee-adminapi.sh commands

However, after you enable SSO on Edge you typically disable Basic Auth so that the only way to authenticate is through the OIDC/SAML IDP. Therefore, you must make sure that you have added the system admin account to your IDP, or created a local Machine User for automation.

Calling Edge management APIs as the system administrator

Many Edge API calls require you to pass system administrator credentials. Using SAML with the Edge management API contains instructions on how to obtain and refresh tokens using the get_token utility when making Edge management API calls.

Using the apigee-adminapi.sh utility with Apigee SSO

Use the apigee-adminapi.sh utility to perform the same Edge configuration tasks that you perform by making calls to the Edge management API. The advantage to the apigee-adminapi.sh utility is that it:

  • Uses a simple command-line interface
  • Implements tab-based command completion
  • Provides help and usage information
  • Can display the corresponding API call if you decide to try the API

After you enable Apigee SSO, you have two primary ways to pass credentials to the apigee-adminapi.sh utility, depending on whether you are a human administrator or an automated script.

You can see all of the options for any apigee-adminapi.sh command, including the options for specifying SSO credentials, by using the -h option to the command. For example:

apigee-adminapi.sh orgs list -h

Passing a bearer token (for human administrators)

Because the modernized Apigee SSO does not support the legacy /passcode copy-paste flow, human administrators must use the get_token utility to complete the OAuth 2.0 Device Code flow, and then pass the resulting token to the script.

First, obtain a token:

/opt/apigee/apigee-openldap/bin/get_token -u adminEmail

Then, use the token when calling the command:

apigee-adminapi.sh orgs list --sso-url http://edge_sso_IP_DNS:9099 --oauth-flow passcode \
  --admin adminEmail --oauth-token token_string

Where:

  • oauth-flow specifies passcode (this signals to the legacy script that a token is being provided).
  • oauth-token contains the raw JWT string obtained from get_token.

Passing a password (for machine users only)

If you are automating infrastructure deployments, you can pass credentials directly using the password_grant flow. However, if SAML/OIDC federation is enabled, human shadow users are blocked from password login to prevent MFA bypass. You must provision an explicit Machine User in OpenLDAP first.

apigee-adminapi.sh orgs list --sso-url http://edge_sso_IP_DNS:9099 --oauth-flow password_grant \
  --admin machineUserEmail --oauth-password machineUserPassword

Where:

  • The sso-url option specifies the URL of the Apigee SSO. Modify the port or protocol if you have changed them from 9099 and HTTP.
  • oauth-flow specifies password_grant.
  • machineUserEmail is the email address of the automated Machine User.
  • oauth-password specifies the Machine User's password.

Using Edge utilities with Apigee SSO

Many Edge utilities require system admin credentials, such as:

  • apigee-provision used to create organizations, environments, and virtual hosts
  • setup.sh used to add nodes to an existing system
  • Any other utility where you have to specify the system admin credentials in a configuration file

These utilities take as input a configuration file that specifies the system admin's credentials. Before SSO is enabled, this is done by using the properties:

ADMIN_EMAIL="adminEmail"
APIGEE_ADMINPW="adminPWord"

After you enable Apigee SSO, you must use different properties to specify the sys admin's credentials.

Using a bearer token (for human administrators)

For interactive deployments by human administrators, acquire a token using the get_token utility and supply it via the OAUTH_BEARER_TOKEN property:

ADMIN_EMAIL="adminEmail"
SSO_LOGIN_URL="http://edge_sso_IP_DNS:9099"
OAUTH_FLOW="passcode"
OAUTH_BEARER_TOKEN="token_string"

Where:

  • OAUTH_FLOW specifies passcode (signaling that a token is provided).
  • OAUTH_BEARER_TOKEN contains the raw JWT string obtained from get_token.

Using a password (for machine users only)

For fully automated deployments, supply the credentials of an explicitly provisioned Machine User using the password_grant flow:

ADMIN_EMAIL="machineUserEmail"
SSO_LOGIN_URL="http://edge_sso_IP_DNS:9099"
OAUTH_FLOW="password_grant"
OAUTH_ADMIN_PASSWORD="machineUserPassword"

Where:

  • SSO_LOGIN_URL specifies the URL of the Apigee SSO.
  • OAUTH_FLOW specifies password_grant.
  • OAUTH_ADMIN_PASSWORD specifies the Machine User's password.