Access the management API with SAML

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 management API.

Differences between SAML and OAuth2

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

The key differences between SAML and OAuth2 when accessing the management API are in the way you get tokens. With SAML, you must include the following when getting your passcode and tokens:

  1. Zones: Reference your zone name when getting your tokens
  2. Initial passcode: Include a one-time passcode (when generating the initial access token)

The endpoints for the management API calls are the same for both SAML and OAuth2.

To get access tokens with SAML, you can either use the get_token utility or the management API. Each of these approaches is described in the sections that follow.

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.

To get an access token with get_token:

  1. 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.net", as the following example shows:

    export SSO_LOGIN_URL=https://acme.login.apigee.com
  2. In a browser, go 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 are not currently logged in by your identity provider, you will be prompted to log 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.

  3. Invoke get_token to obtain the OAuth2 access token:
    get_token

    You are prompted to enter the one-time passcode that you obtained in the previous step:

    One Time Code ( Get one at https://acme.login.apigee.com/passcode )
    Enter the passcode if SAML is enabled or press ENTER:

    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.

  4. Call the management API and pass the access token in the Authorization: Bearer header, as the following example shows:
    curl -H "Authorization: Bearer ACCESS_TOKEN"
      https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    You got the value of the access token from ~/.sso-cli.

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

When your access token expires, you can call get_token again to get a new access token. 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 OAuth access token.

Get access tokens with the management API

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

To get an access token with the management API:

  1. In a browser, go 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

    The passcode essentially acts as your credentials to get your tokens.

    If you are not currently logged in by your identity provider, you will be prompted to log 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.

  2. Send a request to the management API, as the following example shows:
    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://zoneName.login.apigee.com/oauth/token -s \
          -d 'grant_type=password&response_type=token&passcode=passcode'

    The passcode acts as your credentials for authorization.

    Where:

    • The body of the request contains the following:
      • grant_type is "password"
      • response_type is "token"
    • passcode is the passcode you got in the previous step
    • The Authorization header is "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (use this exact value)
    • The request type is POST

    The call prints the access and refresh tokens to the screen.

To refresh your access token:

  1. In a browser, go 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

    The passcode essentially acts as your credentials to get your tokens.

  2. Submit a request to https://zoneName.login.apigee.com/oauth/token, as the following example shows:
    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://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 (if you used get_token, then the refresh token is in ~/.sso-cli
    • The Authorization header is "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (use this exact value)
    • The request type is POST

Access the management API with SAML

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

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

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

With acurl, you do not need to specify the Authorization header once you have called get_token and saved the tokens locally. For example:

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

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

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