Access the Edge API with SAML

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

SAML supports 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 services that you provide and that also support SAML.

Prerequisite: You must enable SAML for at least one organization before you can use it to access the Edge API.

Differences between SAML and OAuth2

Once SAML is set up, using it is very similar to using OAuth2 to access the Edge API. When you call the Edge API, you include an OAuth2 access token in your request.

The key difference between SAML and OAuth2 when accessing the Edge API is in the way you get tokens. With SAML, you must include the following when getting your token pair:

Zones: Edge for Public Cloud users must reference their zone name when getting tokens.
Passcode: Include a one-time passcode when requesting an access/refresh token pair.

SAML uses the same endpoints on the Edge OAuth2 service, with the addition of the appropriate zone name.

To get access tokens with SAML, you can use one of the following methods, described in this section:

get_token utility
Edge OAuth2 service

In addition, you can automate the token generation process for machine users, as described in Automate the token generation process.

Get access tokens with get_token

You can use the get_token utility to exchange your credentials for OAuth2 access and refresh tokens that you use with SAML.

NOTE

The examples in this section use curl to make API requests. You should consider using acurl, Apigee's utility that acts as a convenience wrapper around curl. acurl passes in the access tokens and refreshes them for you when the tokens expire.

To get an access token with get_token:

Set the SSO_LOGIN_URL environment variable to your login URL. The login URL has the following form:
```
https://zoneName.login.apigee.com
```
For example, for a zone named "acme", set SSO_LOGIN_URL to "https://acme.login.apigee.com", as the following example shows:
```
export SSO_LOGIN_URL=https://acme.login.apigee.com
```
Call get_token to obtain the OAuth2 access token:
```
get_token -u me@example.com
```
You are prompted to visit the URL displayed to obtain a one-time passcode:
```
Get passcode from https://acme.login.apigee.com/passcode
[Note:  Passcode can be used only time time and expires] Input passcode (no spaces) and then press ENTER:
```
If you have not recently signed in through your identity provider, you will be prompted to sign in.

This URL returns a one-time passcode that remains valid until you refresh that URL to obtain a new passcode, or you use the passcode with get_token to generate an access token. For example:
Enter the passcode. The get_token utility obtains the OAuth2 tokens, prints the access token to stdout, and writes the access and refresh tokens to ~/.sso-cli.
Call the Edge API and pass the access token in the Authorization: Bearer header, as the following example shows:
```
curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
```
The value of the access token can be copied from stdout.

This example gets details about the given organization. For a complete list of management API endpoints, see Apigee Edge API Reference.

When your access token expires, you can call get_token again to get a new access token. For example:

get_token -u me@example.com

You will not be prompted for a new passcode until the refresh token expires.

When the refresh token expires, get_token prompts you for a new passcode. You must generate a new passcode before you can generate a new OAuth2 access token.

Get access tokens with the Edge OAuth2 service

You can use the Edge OAuth2 service to get access tokens that you use with SAML. To authenticate yourself with the Edge API, you use a passcode on your initial request to get an access/refresh token pair, and again to get a fresh token pair.

To get a token pair with the Edge API:

In a browser, navigate to the following URL to obtain a one-time passcode:
```
https://zoneName.login.apigee.com/passcode
```
For example, for a zone named "acme", go to the following URL:
```
https://acme.login.apigee.com/passcode
```
If you have not recently signed in through your identity provider, you will be prompted to sign in.

This URL returns a one-time passcode that acts as your credentials to get tokens and remains valid until you refresh the URL to obtain a new passcode, or you can use the passcode with get_token to generate an access token. For example:
Send a request to the Edge API, as the following example shows:
```
curl https://zoneName.login.apigee.com/oauth/token \
      -s \
      -H "Accept: application/json" \
      -d 'grant_type=password&response_type=token&passcode=passcode'
```
The passcode acts as your credentials for authorization.

Where:
- The Authorization header is "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (use this exact value).
- The request type is POST.
- The body of the request contains the following:
  - grant_type is "password".
  - response_type is "token".
  - passcode where passcode is the passcode that was returned in the previous step.
The call prints the access and refresh tokens to the screen.

To refresh your access token:

Submit a request to https://zoneName.login.apigee.com/oauth/token, as the following example shows:

curl https://zoneName.login.apigee.com/oauth/token \
      -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

Where:

The body of the request contains the following:
- grant_type is "refresh_token".
- refresh_token is the value of the refresh token.
The Authorization header is "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (use this exact value).
The request type is POST.

Access the Edge API with SAML

You can use tools such as curl or the Apigee convenience utility acurl to access the Edge API.

With curl, you call the Edge API and pass the access token in the Authorization: Bearer header, as the following example shows:

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

With acurl, you do not need to specify the Authorization header. For example:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

These examples call a Edge API endpoint that gets details about the given organization. For a complete list of Edge API endpoints, see Apigee Edge API Reference.

For additional methods of calling the API, including ways to ensure that your token remains fresh, see Access the Edge API with OAuth2.

Machine users in SAML zones

You can use the acurl and get_token utilities to script automated access to the Edge APIs for machine users in SAML zones. The following example shows how to use get_token to request an access token and then add the token value to a curl call:

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '' --force-basic-auth)
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

In the example above, setting the value of -m to an empty string will prevent a machine user from being prompted for an MFA code. Using the --force-basic-auth flag will override the standard prompt for a passcode triggered by requests with SAML zones.

Alternatively, you can combine the token request and curl call using the acurl utility. For example:

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' --force-basic-auth 'https://api.enterprise.apigee.com/v1/organizations/...'