Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Using OAuth2 security with the Apigee Edge management API

This topic explains how to make secure management API calls with OAuth2 tokens.

What is this?

The Apigee Edge management server for Edge Cloud now supports OAuth2 for user authentication. 

For now, you have the option of using OAuth2 or Basic Authentication.

In the future, Apigee will deprecate Basic Authentication as a means of authenticating to the management server.

Apigee recommends that you enable 2-factor authentication for your Apigee account. For details, see the article Two-Factor Authentication Using One-Time Passwords" on the Apigee Community.

About OAuth2

With OAuth2, you exchange your Edge credentials for an access token and a refresh token that you can then use to make secure calls to the management API. Once you obtain a token, you do not need to exchange your credentials again until the token expires. The refresh token allows you to keep your "session" with the server alive for a longer period without providing your credentials. This scheme is particularly useful when using two-factor authentication.

You can use OAuth2 tokens to access Apigee management server URLs. The default identity provider is at https://login.apigee.com.

If you'd like to read more about OAuth, see Introduction to OAuth 2.0 in the Apigee docs. For a deeper dive, see the OAuth 2.0 Authorization Framework specification.

How to get OAuth2 tokens

To make OAuth2-secure management API calls, you need to obtain OAuth2 access and refresh tokens from Apigee. The UI already does this. If you’re using command line tools against the management API, Apigee provides a set of utility scripts that you can easily install and use to get tokens and make API calls. Installation instructions are provided below in this topic.

Here is a brief description of the scripts.

  • acurl - A utility that makes it simpler to use your existing curl-based scripts with OAuth2. The acurl script is a wrapper around curl that automatically retrieves an access token from Apigee Edge and then makes a curl call with the proper Authorization header with the token. When the access token expires, acurl gets a new one using the refresh token.
  • get_token - A utility that makes it easy to get an access token. get_token exchanges your Apigee credentials for an OAuth2 access and refresh token for accessing the management APIs. The get_token script accepts your credentials and prints a valid access token. If a token can be refreshed, the script will refresh it and print it out. If the refresh token expires, the script will prompt for user credentials. The script stores the tokens on disk, ready for use when required, and it always prints a valid access token to stdout. From there, you can use Postman or embed get_token in an environment variable for use in curl.

Installing acurl and get_token utilities

Apigee provides a ZIP file containing the acurl and get_token utilities and an install script.

  1. Create a directory for the installation ZIP file.
  2. Download the ZIP file from Apigee. You can use the following API to download it:
    curl https://login.apigee.com/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"
  3. Unzip the file.
  4. Run the install script:
    sudo ./install -b /usr/local/bin

Using acurl

  1. Test the installation by printing command-line help for acurl
    acurl -h
  2. Call a management API:
    acurl https://api.enterprise.apigee.com/v1/o/<orgname> -u <username> -m <Your one-time password if you have two-factor auth enabled>

    例:
    acurl https://api.enterprise.apigee.com/v1/o/docs -u jdoe@apigee.com -m 567123

A successful call returns information about the organization.

How does acurl work?

acurl exchanges your user credentials for OAuth2 access and refresh tokens. It then stores these tokens in your home directory. It uses the refresh token to get new access tokens. When the refresh token expires, acurl will fail and prompt you for your Apigee credentials. If you have a valid access token, acurl wraps a standard curl command that includes the access token in an Authorization header, like this:

curl -H "Authorization: Bearer <the access token>" ...

When you execute acurl the first time, an access token is returned and stored locally in ~/.sso-cli, and acurl uses it for subsequent calls. Also, you can grab the token and use it to make calls with a REST tool like Postman.

Using get_token to obtain OAuth2 tokens

The get_token utility lets you exchange your Apigee credentials for an access and refresh token that you can then use to access Apigee management APIs.

The get_token utility will put the token files in a directory at ~/.sso-cli. If you don't have such a directory yet, create one before running the utility.

  1. Test the installation by printing command-line help for get_token:
    get_token -h
  2. Get a token:
    get_token

If you are getting the token for the first time or if the refresh token has expired the get_token will prompt for your username, password and the six digit MFA code (you can press ENTER if you have not enabled MFA). If the username is not entered within 30 seconds, the script times out and exits with a non-zero error. A successful call prints a valid access token to stdout.

You can also use get_token in the following way:

get_token -u <Apigee email> -m <Your one-time password if you have two-factor auth enabled>

例:

get_token -u <jdoe@apigee.com> -m 567123

Here's a way to embed get_token directly in a curl call:

header=`get_token` && curl -H "Authorization: Bearer $header" -v https://api.enterprise.apigee.com/v1/o/<your organization> 

Using get_token to obtain OAuth tokens from SAML assertions

Edge supports Security Assertion Markup Language (SAML) 2.0 as the authentication mechanism. SAML provides support for a single sign-on (SSO) environment. By using SAML with Edge, you can support SSO for the Edge UI and API in addition to any other of your services that support SAML.

After you enable SAML, Basic Auth is disabled for the Edge management API. You must update any API calls and scripts that use Basic Auth to use OAuth2 bearer tokens instead. To do so, use get_token to exchange your SAML assertion for an OAuth2 bearer token usable by the Edge management API. You then pass that access token as the Bearer header to make Edge management API calls. For example:

> curl -H "Authorization: Bearer <access_token>" https://api.enterprise.apigee.com/v1/organization/orgName

For more information on generating and using tokens for Edge SSO, including using tokens with the Edge UI and API, see Enabling SAML Authentication for Edge.

Using the API

You can get access and refresh tokens using the API, as explained in this section.

(POST) Get a new access token

Use this API to get a new access token. In the output, you will receive both an access token and a refresh token. If you save the refresh token, you can make subsequent API calls to obtain new access tokens (see "Refresh an access token" below). 

Request URL

https://login.apigee.com/oauth/token

Header parameters

Parameter
Content-Type application/x-www-form-urlencoded
Accept application/json;charset=utf-8
Authorization Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0

Form parameters (x-www-form-urlencoded)

Parameter
username <YOUR APIGEE ACCOUNT EMAIL ADDRESS>
password <YOUR APIGEE ACCOUNT PASSWORD>
grant_type password
mfa_token A valid multi-factor auth token for your account. Required only if you have multi-factor auth (MFA) enabled on your Apigee account. See also Enable two-factor auth for your Apigee account.


Example using MFA token

Use the exact Authorization header shown in the example.

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://login.apigee.com/oauth/token?mfa_token=<6 Digit token> -d 'username=jdoe@example.com&password=abc123&grant_type=password'

Output

On success, you will get back an access token, refresh token, and related information. For example:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOimYyD8IP2IyYS1jNmNiLTQ4NTgtYjZkMS1mZjkyNGFkYTk1YWUiLCJzdWIiOiI0X0KLSNjZlNjM0ZC0zZjlhLTRiNYmFjNi1kYjE2M2M5OGEzOGYiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwicGFzc3dvcmQud3JpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsImNpZCI6ImVkZ2VjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjQ2NmU2MzRkLTNmOWEtNGI0MS1iYWM2LWRiMTYzYzk4YTM4ZiIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoid3dpdG1hbkBhcGlnZWUuY29tIiwiZW1haWwiOiJ3d2l0bWFuQGFwaWdlZS5jb20iLCJhdXRoX3RpbWUiOjE0NzMyNjU4NzcsImFsIjoyLCJyZXZfc2lnIjoiZTc0ZGY0M2QiLCJpYXQiOjE0NzMyNjU4NzcsImV4cCI6MTQ3MzI2NzY3NywiaXNzIjoiaHR0cHM6Ly9sb2dpbi5hcGlnZWUuY29tL29hdXRoL3Rva2VuIiwiemlkIjoidWFhIiwiYXVkIjpbImVkZ2VjbGkiLCJzY2ltIiwib3BlbmlkIiwicGFzc3dvcmQiLCJhcHByb3ZhbHMiLCJvYXV0aCJdfQ.AFuevkeGGUGSPED8leyEKaT-xg1xk_VEiKJLEpipVvQBXIqEc9wqcpm-ZuoatA9DhjASRuFSRaHH8Fasx_vBxEBsUNhRY-GTMw7_8fv4yRMOb2AO3WUl_NWwPkC8XRSI1zCMbAZicojsJ1n3OSP487Mu9dl9ByX5A_QfHV2_cj4l9-SD7u6vOdfdbBxbNMAQkfZLrVIEU8myF2dhKnNeMiuoHSHANsQFcx0_BFA1HnSUnVi4RYj1FlTs9SbcPnS1d7t7eVdxWz_q2OFVXNIBMELAvvM0WhXPYTW3Osve3UvvUs6ekGs-K-RCPSok-4-NJbdCDpZQQTgqHsrf77NTsw",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmZTIIMZWI0ZS00YzFmLTRjOTEtYmY5Mi1mMzZLEMzNjZhMDctciIsInN1YiI6IjQ2NmU2MzRkLTNmOWEtNGI0MS1iY17LLWRiMTYzYzk4YTM4ZiIsInNjb3BlIjpbInNjaW0ubWUiLCJvcGVuaWQiLCJwYXNzd29yZC53cml0ZSIsImFwcHJvdmFscy5tZSIsIm9hdXRoLmFwcHJvdmFscyJdLCJpYXQiOjE0NzMyNjU4NzcsImV4cCI6MTQ3MzM1MDQ3NywiY2lkIjoiZWRnZWNsaSIsImNsaWVudF9pZCI6ImVkZ2VjbGkiLCJpc3MiOiJodHRwczovL2xvZ2luLmFwaWdlZS5jb20vb2F1dGgvdG9rZW4iLCJ6aWQiOiJ1YWEiLCJncmFudF90eXBlIjoicGFzc3dvcmQiLCJ1c2VyX25hbWUiOiJ3d2l0bWFuQGFwaWdlZS5jb20iLCJvcmlnaW4iOiJ1c2VyZ3JpZCIsInVzZXJfaWQiOiI0NjZlNjM0ZC0zZjlhLTRiNDEtYmFjNi1kYjE2M2M5OGEzOGYiLCJhbCI6MiwicmV2X3NpZyI6ImU3NGRmNDNkIiwiYXVkIjpbImVkZ2VjbGkiLCJzY2ltIiwib3BlbmlkIiwicGFzc3dvcmQiLCJhcHByb3ZhbHMiLCJvYXV0aCJdfQ.kBP5AkbRS7Tnp-5VAfTLVfkUbUer4gFEU6A7g202KTKiXbqTwPSmOIGFTK12XevVPQYmAaSMFAnempWKfY7sjaY7HC7q3mGl53_A18cnkKhtNq15wCnyMom_bX_MYLW1RQPFytJ6akSJ-JkoPFU0x_FQg1JIvub1A8eqQxcR0KP-QRCxYAS4HTjH80vDIxHNt1tg7clmpa3RlHri0dlPVVsSpTXXhkpXRg5QbiWMrpkACSV22c0x0KiNu7GiJ9t5B1S1cxwvx5A520VOCO7hQ7IzmVIcSWcRqI97L7WdCjH_q4105bs2qmW73670MC0UqpUEd-NAuCsY8SVn6eWzbA",
  "expires_in": 1799,
  "scope": "scim.me openid password.write approvals.me oauth.approvals",
  "jti": "9bf2cb2a-c6cb-4858-b6d1-ff924ada95ae"
}

(POST) Refresh an access token

Use this API to get a access token with a refresh token. You'll get back a new access token and refresh token. Save the refresh token to make subequent calls to get a new access token. 

Request URL

https://login.apigee.com/oauth/token

Header parameters

Parameter
Content-Type application/x-www-form-urlencoded
Accept application/json;charset=utf-8
Authorization Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0

Form parameters (x-www-form-urlencoded)

Parameter
refresh_token <YOUR REFRESH TOKEN>
grant_type refresh_token

Use the exact Authorization header shown in the example.

curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" -H "Accept: application/json;charset=utf-8" -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" https://login.apigee.com/oauth/token -d 'grant_type=refresh_token&refresh_token=<YOUR REFRESH_TOKEN>'

Output

On success, you will get back a new access token, refresh token, and related information. For example:

Note: Save the refresh token to make subsequent calls to get a new access token. 

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOimYyD8IP2IyYS1jNmNiLTQ4NTgtYjZkMS1mZjkyNGFkYTk1YWUiLCJzdWIiOiI0X0KLSNjZlNjM0ZC0zZjlhLTRiNYmFjNi1kYjE2M2M5OGEzOGYiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwicGFzc3dvcmQud3JpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsImNpZCI6ImVkZ2VjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjQ2NmU2MzRkLTNmOWEtNGI0MS1iYWM2LWRiMTYzYzk4YTM4ZiIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoid3dpdG1hbkBhcGlnZWUuY29tIiwiZW1haWwiOiJ3d2l0bWFuQGFwaWdlZS5jb20iLCJhdXRoX3RpbWUiOjE0NzMyNjU4NzcsImFsIjoyLCJyZXZfc2lnIjoiZTc0ZGY0M2QiLCJpYXQiOjE0NzMyNjU4NzcsImV4cCI6MTQ3MzI2NzY3NywiaXNzIjoiaHR0cHM6Ly9sb2dpbi5hcGlnZWUuY29tL29hdXRoL3Rva2VuIiwiemlkIjoidWFhIiwiYXVkIjpbImVkZ2VjbGkiLCJzY2ltIiwib3BlbmlkIiwicGFzc3dvcmQiLCJhcHByb3ZhbHMiLCJvYXV0aCJdfQ.AFuevkeGGUGSPED8leyEKaT-xg1xk_VEiKJLEpipVvQBXIqEc9wqcpm-ZuoatA9DhjASRuFSRaHH8Fasx_vBxEBsUNhRY-GTMw7_8fv4yRMOb2AO3WUl_NWwPkC8XRSI1zCMbAZicojsJ1n3OSP487Mu9dl9ByX5A_QfHV2_cj4l9-SD7u6vOdfdbBxbNMAQkfZLrVIEU8myF2dhKnNeMiuoHSHANsQFcx0_BFA1HnSUnVi4RYj1FlTs9SbcPnS1d7t7eVdxWz_q2OFVXNIBMELAvvM0WhXPYTW3Osve3UvvUs6ekGs-K-RCPSok-4-NJbdCDpZQQTgqHsrf77NTsw",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmZTIIMZWI0ZS00YzFmLTRjOTEtYmY5Mi1mMzZLEMzNjZhMDctciIsInN1YiI6IjQ2NmU2MzRkLTNmOWEtNGI0MS1iY17LLWRiMTYzYzk4YTM4ZiIsInNjb3BlIjpbInNjaW0ubWUiLCJvcGVuaWQiLCJwYXNzd29yZC53cml0ZSIsImFwcHJvdmFscy5tZSIsIm9hdXRoLmFwcHJvdmFscyJdLCJpYXQiOjE0NzMyNjU4NzcsImV4cCI6MTQ3MzM1MDQ3NywiY2lkIjoiZWRnZWNsaSIsImNsaWVudF9pZCI6ImVkZ2VjbGkiLCJpc3MiOiJodHRwczovL2xvZ2luLmFwaWdlZS5jb20vb2F1dGgvdG9rZW4iLCJ6aWQiOiJ1YWEiLCJncmFudF90eXBlIjoicGFzc3dvcmQiLCJ1c2VyX25hbWUiOiJ3d2l0bWFuQGFwaWdlZS5jb20iLCJvcmlnaW4iOiJ1c2VyZ3JpZCIsInVzZXJfaWQiOiI0NjZlNjM0ZC0zZjlhLTRiNDEtYmFjNi1kYjE2M2M5OGEzOGYiLCJhbCI6MiwicmV2X3NpZyI6ImU3NGRmNDNkIiwiYXVkIjpbImVkZ2VjbGkiLCJzY2ltIiwib3BlbmlkIiwicGFzc3dvcmQiLCJhcHByb3ZhbHMiLCJvYXV0aCJdfQ.kBP5AkbRS7Tnp-5VAfTLVfkUbUer4gFEU6A7g202KTKiXbqTwPSmOIGFTK12XevVPQYmAaSMFAnempWKfY7sjaY7HC7q3mGl53_A18cnkKhtNq15wCnyMom_bX_MYLW1RQPFytJ6akSJ-JkoPFU0x_FQg1JIvub1A8eqQxcR0KP-QRCxYAS4HTjH80vDIxHNt1tg7clmpa3RlHri0dlPVVsSpTXXhkpXRg5QbiWMrpkACSV22c0x0KiNu7GiJ9t5B1S1cxwvx5A520VOCO7hQ7IzmVIcSWcRqI97L7WdCjH_q4105bs2qmW73670MC0UqpUEd-NAuCsY8SVn6eWzbA",
  "expires_in": 1799,
  "scope": "scim.me openid password.write approvals.me oauth.approvals",
  "jti": "9bf2cb2a-c6cb-4858-b6d1-ff924ada95ae"
}

Usage notes

Both acurl and get_token scripts hit the SSO endpoint specified in the SSO_LOGIN_URL environment variable. The default endpoint is https://login.apigee.com. The expires_in attribute is in seconds.

Enabling 2-factor security

You can optionally enable 2-factor security for your Apigee Edge account. When 2-factor security is enabled, you provide a randomly generated number along with your user credentials when logging into your Apigee account. See also Enable two-factor auth for your Apigee account. At this time, you can use acurl to make calls whether or not you have 2-factor security enabled.

Help or comments?