Using Edge admin utilities and APIs after enabling SAML

Edge for Private Cloud v4.18.05

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

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

However, after you enable SAML on Edge you typically disable Basic Auth so that the only way to authenticate is through the SAML IDP. Therefore, you must make sure that you have added the system admin account to your SAML IDP.

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 when making Edge management API calls.

Using the apigee-adminapi.sh utility with SAML authentication

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:

  • Use 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

For more, see Using apigee-ssoadminapi.sh.

After you enable SAML authentication, you have several ways to pass the system admin credentials to the apigee-adminapi.sh utility.

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

apigee-adminapi.sh orgs list -h

For example, you can pass the system admin credentials:

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

Where:

  • The sso-url option specifies the URL of the Edge SSO module. Modify the port or protocol if you have changed them from 9099 and HTTP.
  • oauth-flow specifies either passcode or password_grant. In this example, you specify password_grant.
  • adminEmail is the email address of the sys admin.
  • oauth-password specifies the sys admin's password.

Alternatively, you can use a passcode when calling the command:

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

Where:

  • oauth-flow specifies passcode.
  • oauth-passcode specifies the passcode obtained from http://edge_sso_IP_DNS:9099/passcode.

Finally, you can use a 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

Where:

  • oauth-flow specifies either passcode or password_grant, depending on how you originally got the token. In this example, you specify passcode because you originally got the token by using get_token. See Using SAML with the Edge management API.
  • oauh_token contains the token.

Using Edge utilities with SAML authentication

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 by using the properties:

ADMIN_EMAIL="adminEmail"
APIGEE_ADMINPW=adminPWord

If you omit the password, then you are prompted for it.

After you enable SAML you use different properties to specify the sys admin's credentials. For example, you can pass the system admin credentials:

ADMIN_EMAIL="adminEmail"
SSO_LOGIN_URL=http://edge_sso_IP_DNS:9099
OAUTH_FLOW=password_grant
OAUTH_ADMIN_PASSWORD=adminPWord

Where:

  • SSO_LOGIN_URL specifies the URL of the Edge SSO module. Modify the port or protocol if you have changed them from 9099 and HTTP.
  • OAUTH_FLOW specifies either passcode or password_grant. In this example, you specify password_grant because you are passing the sys admin's password.
  • OAUTH_ADMIN_PASSWORD specifies the sys admin's password.

Alternatively, you can use the following properties to specify the credentials as part of a passcode flow:

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

Where:

  • OAUTH_FLOW specifies passcode.
  • OAUTH_ADMIN_PASSCODE specifies the passcode obtained from http://edge_sso_IP_DNS:9099/passcode.

Finally, you can use a token

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

Where:

  • OAUTH_FLOW specifies either passcode or password_grant, depending on how you originally got the token. In this example, you specify passcode because you originally got the token by using get_token. See Using SAML with the Edge management API.
  • OAUTH_BEARER_TOKEN contains the token.