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.

Enabling SAML Authentication for Edge

The Edge UI and Edge management API operate by making requests to the Edge Management Server, where the Management Server supports the following types of authentication:

  • Basic Auth and Basic Auth with two-factor authentication
    Log in to the Edge UI or make requests to the Edge management API by passing your username and password. If two-factor authentication is enabled, you also pass a six digit Multi-Factor Authentication (MFA) code when logging in to the Edge UI. 
  • OAuth2 
    Exchange your Edge Basic Auth credentials for an OAuth2 access token and refresh token.  Make calls to the Edge management API by passing the OAuth2 access token in the Bearer header of an API call. 

    See Using OAuth2 security with the Apigee Edge management API for more. 

Edge also supports Security Assertion Markup Language (SAML) 2.0 as the authentication mechanism. With SAML enabled, access to the Edge UI and Edge management API still uses OAuth2 access tokens. However, now you can generate these tokens from SAML assertions returned by an identity provider. 

SAML is supported as the authentication mechanism only for the Cloud version of Edge. It is not supported for Edge for the Private Cloud.

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.

SAML authentication offers several advantages. By using SAML you can:

  • Take full control of user management. When users leave your organization and are deprovisioned centrally, they are automatically denied access to Edge.. 
  • Control how users authenticate to access Edge. You can choose different authentication types for different Edge organizations.
  • Control authentication policies. Your SAML provider may support authentication policies that are more in line with your enterprise standards.
  • You can monitor logins, logouts, unsuccessful login attempts and high risk activities on your Edge deployment.

Note that SAML is only used for authentication by the Edge UI and Edge management API. Authorization is still controlled by Edge user roles. See Assigning roles for more.

Using SAML with Edge

With SAML enabled, access to the Edge UI and Edge management API continues to use OAuth2 access tokens. These tokens are generated by the Edge SSO which now accepts  SAML assertions returned by the your identity provider. The Edge SSO is configured as a SAML service provider to your SAML2 compliant identity provider.

You enable SAML at the organization level through Edge identity zones. That means every organization that you want to support SAML authentication must be added to an Edge identity zone.

About Edge identity zones

An Edge identity zone is an authentication realm that defines a SAML identity provider used for authentication. Only when a user authenticates with the identity provider can they access the Edge organizations and resources scoped to the zone.

To enable SAML, you first specify the name of an identity zone and identify the Edge organizations that are in the zone. Apigee then configures the identity zone to interact with your SAML identity provider.

You only have to inform Apigee of your zone name and the names of the Edge organizations that you want to include in the zone. Apigee then creates the zone on Edge, and adds your Edge organizations to the zone. See Information required by Apigee to enable SAML below for more.

Using an identity zone to access your organization

The URL that you use to access the Edge UI is defined by the name of your identity zone:

https://zoneName.enterprise.apigee.com 

For example, Acme Inc. wants to use SAML and chooses “acme” as its zone name. Acme Inc. customers then access the Edge UI with the following URL:

https://acme.enterprise.apigee.com   

The zone identifies the Edge organizations that support SAML. For example, Acme Inc. has three orgs: OrgA, OrgB and OrgC. Acme can decide to add all organizations to the SAML zone, or only a subset. The remaining organizations continue to use Basic Auth or OAuth2 tokens generated from Basic Auth credentials.

After successful authentication through SAML, the Edge UI user is redirected to an Edge organization:

https://zoneName.enterprise.apigee.com/platform/orgName

For example:

https://acme.enterprise.apigee.com/platform/OrgA

One option is to define multiple identity zones. All zones can then be configured to use the same identity provider.

For example, Acme might want to define a production zone, "acme-prod", containing OrgAProd and OrgBProd, and a test zone, "acme-test", containing OrgATest, OrgBTest, OrgADev, and OrgBDev.   

You then use the following URLs to access the different zones:

https://acme-prod.enterprise.apigee.com 
https://acme-test.enterprise.apigee.com 

Using SAML with the Edge UI

The SAML specification defines three entities: 

  • Principal (Edge UI user)
  • Service provider (Edge SSO) 
  • Identity provider (returns SAML assertion)

When SAML is enabled, the principal (an Edge UI user) requests access to the service provider (Edge SSO). Edge SSO (in it’s role as a SAML service provider) then requests and obtains an identity assertion from the SAML identity provider and uses that assertion to create the OAuth2 token required to access the Edge UI. The user is then redirected to the Edge UI.

This process is shown below:

In this diagram:

  1. User attempts to access the Edge UI by making a request to the login domain for the Edge SSO, which includes the zone name:
    For example: https://zoneName.login.apigee.com
  2. Unauthenticated requests to https://zoneName.login.apigee.com are redirected to the customer’s SAML identity provider. For example, https://idp.customer.com.
  3. If customer is not logged in to the identity provider, the customer is prompted to log in.
  4. The user is authenticated by the SAML identity provider. The SAML identity provider generates and returns a SAML 2.0 assertion to the Edge SSO.
  5. Edge SSO validates the assertion, extracts the user identity from the assertion, generates the OAuth 2 authentication token for the Edge UI, and redirects the user to the main Edge UI page at:
    https://zoneName.enterprise.apigee.com/platform/orgName

    where orgName is the name of an Edge organization.

Using SAML with the Edge management API

Basic Auth is one way to authenticate when making calls to the Edge management API. For example, you can make the following cURL request to the Edge management API to access information about your organization:

curl -u userName:pWord https://api.enterprise.apigee.com/v1/organization/orgName

In this example, you use the cURL -u option to pass Basic Auth credentials. Alternatively, you can pass an OAuth2 token in 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

After you enable SAML, Basic Auth is disabled for the Edge management API. That means all scripts (Maven scripts, shell scripts, apigeetool, etc.) that rely on Edge management API calls supporting Basic Auth no longer work. 

You must update any API calls and scripts that use Basic Auth to pass OAuth2 access tokens in the Bearer header. To do so, first use the get_token utility, provided with Edge, to exchange your SAML assertion for an OAuth2 access token. See Using OAuth2 security with the Apigee Edge management API for more on get_token.

The URL for the Edge management API is not affected by enabling SAML authentication. You still access the management API at:

https://api.enterprise.apigee.com/vi  

The process that you use to obtain the OAuth2 access token from the SAML assertion is called the passcode flow. This procedure returns:

  • An access token stored locally at ~/.sso-cli/valid_token.dat. Pass this access token as the Bearer header to a request to an Edge management API call. This tokenis valid for one hour.
  • A refresh token stored locally at ~/.sso-cli/access_token.dat. You can use the refresh token to refresh the access token for 12 hours. After 12 hours, the refresh token expires. You must then obtain a new passcode and regenerate the access token and refresh token.

The following procedure describes how to obtain an OAuth2 access token to make Edge management API calls:

  1. Install the get_token utility. See Using OAuth2 security with the Apigee Edge management API for installation instructions.
  2. Set the SSO_LOGIN_URL environment variable to your login URL. The login URL has the form:
    https://zoneName.login.apigee.com 

    For example, for a zone named "acme", set SSO_LOGIN_URL as:
    export SSO_LOGIN_URL=https://acme.login.apigee.com
  3. 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 URL:
    https://acme.login.apigee.com/passcode

    Note: 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.
  4. Invoke get_token to obtain the OAuth2 access token:
    > get_token

    You are prompted to enter the one-time passcode that you obtained in step 3:
    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 access token, prints it to the screen, and writes it and the refresh token to ~/.sso-cli.
  5. Pass the access token to an Edge management API call as the Bearer header:
    > curl -H "Authorization: Bearer <access_token>" https://api.enterprise.apigee.com/v1/organization/orgName

    After you obtain a new access token for the first time, you can obtain the access token and pass it to an API call in a single command, as shown below:
    > header=`get_token` && curl -H "Authorization: Bearer $header" https://api.enterprise.apigee.com/v1/o/orgName

    With this form of the command, if the access token has expired, it is automatically refreshed until the refresh token expires.

After the refresh token expires, get_token prompts you for a new passcode. You must go to the URL shown above in Step 3 and generate a new passcode before you can generate a new OAuth access token  

Using the management API to get and refresh tokens

The Using the API section of Using OAuth2 security with the Apigee Edge management API contains instructions that show how to use the Edge management API to obtain and refresh tokens. You can also use Edge API calls to for tokens generated from SAML assertions.

The only difference between the API calls documented in the Using the API section is that the URL of the call must reference your zone name. In addition, for generating the initial access token, you must include the passcode, as shown in step 3 of the procedure above.

For example, use the following API call to generate the initial access and refresh tokens: 

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=UKB3Wn'  

For authorization, pass a reserved OAuth2 client credential in the authorization header. The call prints the access and refresh tokens to the screen.

To later refresh the access token, use the following call that includes the refresh token: 

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=refreshToken'  

Using SAML with automated tasks

When using SAML with the Edge API, the process that you use to obtain OAuth2 access and refresh tokens from the SAML assertion is called the passcode flow. With the passcode flow, you use a browser to obtain a one-time passcode that you then use to obtain OAuth2 tokens.

However, your development environment might support automation for common development tasks, such as test automation or Continuous Integration/Continuous Deployment (CI/CD). To automate these tasks when SAML is enabled, you need a way to obtain and refresh OAuth2 tokens without having to copy/paste a passcode from a browser.  

Edge supports automated token generation in two ways. You can decide which way is better for your environment:

  • Edge supports machine users in your Edge SAML zone. A machine user can obtain OAuth2 tokens without having to specify a passcode. That means you can completely automate the process of obtaining and refreshing OAuth2 tokens by using the Edge management API. 
  • Edge supports long OAuth2 tokens. A long OAuth2 access token is valid for one hour, just like a regular access token, but the refresh token is valid for 30 days instead of 12 hours.

    Long tokens use a different OAuth client type than regular tokens. That means you must configure get_token to use the long token client before you use it to obtain and refresh OAuth2 tokens. Typically, you do that configuration only on the machines running automated tasks so that normal users cannot create long tokens.

Create a machine user

On request, Apigee creates a machine user for you. You can have Apigee create a single machine user used by all of your organizations, or create a separate machine user for each organization. 

The machine user is created and stored in the Edge datastore, not in your SAML identity provider. Therefore, you are not responsible for maintaining the machine user. If you later want to add other machine users, or delete an existing machine user, you must contact Apigee Support.

When Apigee creates the machine user, Apigee assigns it an email address and a default password. The email address of the machine user is in the form:

  • machine_orgname@apigee.com if you create a machine user for a specific organization.
  • machine_zonename@apigee.com if you create a single machine user for your entire zone. 

Your first action is to reset the default password. You can then obtain OAuth2 tokens for the machine user. The following procedure describes how to change the machine user's password:    

  1. Make a request to Apigee Support to create a machine user for a specific organization or zone.  
  2. Apigee returns to you the email address and password of the machine user. 
  3. Log in to the Edge UI and add the machine user to your organizations, and assign the machine user to the necessary role. See Creating global users for more.
  4. Change the password of the machine user:
    1. Use the following API call to obtain the JSON Web Token (JWT) for the machine user: 
      curl -s -X POST https://zoneName.login.apigee.com/oauth/token /
      -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" /
      -H "accept: application/json;charset=utf-8" /
      -H "authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0"/
      -d "grant_type=password&username=uName&password=Password"


      where zoneName is your SAML zone, and uName/Password are the machine user's email address and password that you received from Apigee.

      The returned token includes an OAuth2 access token and is in the form: 
      {"access_token":"eyJhbGc...Au91CzslYg","expires_in":43199,"scope":"scim.emails.read scim.me openid password.write approvals.me scim.ids.read oauth.approvals","jti":"6f27ffac-3cde-4eb9-8341-5855333bbbf9"}
    2. Decode the JWT token to obtain the user_id of the machine user. There are many utilities that you can use to perform the decode. For example, you can install jwt from https://www.npmjs.com/package/jwt-cli.
    3. Use the following API call to change the machine user's password:
      curl -s -X PUT /
      https://zoneName.login.apigee.com/Users/user_id/password /
      -H "Content-Type:application/json" /
      -H "Accept:application/json" /
      -H "Authorization: Bearer ACCESS_TOKEN_FROM_STEP_4a" /
      -d '{ "oldPassword" : "OldPassword", "password" : "NewPassword"}' 


      where user_id is the ID you obtained from the JWT token, and ACCESS_TOKEN_FROM_STEP_4a is the access_token from step 4a. 

      This call returns a message in the form:
      {"status":"ok","message":"password updated"}

After you change the machine user's password, you can then use the Edge API to obtain and refresh OAuth2 tokens by passing the machine user's credentials, instead of a passcode. 

The following procedure describes how to obtain OAuth2 tokens:

  1. Use the following API call to generate the initial access and refresh tokens: 
    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&username=uName&password=NewPassword'
     

    For authorization, pass a reserved OAuth2 client credential in the authorization header. The call prints the access and refresh tokens to the screen.
  2. Pass the access token to an Edge management API call as the Bearer header:
    > curl -H "Authentication: Bearer access_token" https://api.enterprise.apigee.com/v1/organization/orgName
  3. To later refresh the access token, use the following call that includes the refresh token: 
    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=refreshToken'  

Create a long token

When you create a long OAuth2 token from a SAML assertion, the OAuth2 access token is valid for one hour, but the long refresh token is valid for 30 days, instead of the usual 12 hours.

Make a request to Apigee Support to enable long tokens. Apigee then returns to you an OAuth client id and secret, in the form clientcli:clientclisecret. You must then:

  • Base64 encode clientcli:clientclisecret.
  • Use the Base64 encoded clientcli:clientclisecret to generate long tokens. 

Only use this client id and secret on machines running automated tasks. It should not be given to normal users, otherwise those users will be able to generate long tokens. 

The process that you use to create and refresh tokens is the same as you use to create tokens for the Edge management API, as shown above. The only difference are:

  • If you use get_token to manage tokens, then you have to set the CLIENT_AUTH environment variable for the long token client:

    export CLIENT_AUTH=Base64EncodedClientIDAndSecret

    Note: Only make this change on your machines running automated tasks. 
  • If you use the Edge API  to manage tokens, then you have to pass the Base64 encoded client id and secret as the Basic auth header when generating or refreshing OAuth2 tokens:

    -H "authorization: Basic Base64EncodedClientIDAndSecret"

For example, when using get_token:

  1. Base64 encode the client id and secret you received from Apigee.
  2. Set the SSO_LOGIN_URL used by get_token:
    > export SSO_LOGIN_URL=https://zoneName.login.apigee.com
  3. Set CLIENT_AUTH used by get_token to the Base64 encoded client id and secret:
    > export CLIENT_AUTH=amVua4guc2NsaTpqZW5raW5zY2xpc2VjcmV0
  4. In a browser, go to the following URL to obtain a one-time passcode: 
    https://zoneName.login.apigee.com/passcode
  5. Invoke get_token to obtain the OAuth2 access token:
    > get_token

    You are prompted to enter the one-time passcode that you obtained in step 3. 
  6. Enter the passcode. The get_token utility obtains the OAuth2 access token, prints it to the screen, and writes it and the refresh token to ~/.sso-cli.
  7. Pass the access token to an Edge management API call as the Bearer header:
    > curl -H "Authentication: Bearer access_token" https://api.enterprise.apigee.com/v1/organization/orgName
  8. After you obtain a new access token for the first time, you can obtain the access token and pass it to an API call in a single command, as shown below:
    > header=`get_token` && curl -H "Authorization: Bearer $header" https://api.enterprise.apigee.com/v1/organization/orgName

    With this form of the command, if the access token has expired, it is automatically refreshed until the refresh token expires.

Or use the following API call to generate the initial access and refresh tokens: 

curl -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" /
-H "accept: application/json;charset=utf-8" /
-H "authorization: Basic amVua4guc2NsaTpqZW5raW5zY2xpc2VjcmV0" -X POST /
https://zoneName.login.apigee.com/oauth/token -s /
-d 'grant_type=password&response_type=token&passcode=passcode'  

Pass the Base64 encoded string for the client id and secret as the Basic header. The call prints the access and refresh tokens to the screen.

To later refresh the access token, use the following call that includes the refresh token generated from the previous call: 

curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" /
-H "Accept: application/json;charset=utf-8" /
-H "Authorization: Basic amVua4guc2NsaTpqZW5raW5zY2xpc2VjcmV0" -X POST /
https://zoneName.login.apigee.com/oauth/token /
-d 'grant_type=refresh_token&refresh_token=refreshToken'  

Considerations before you enable SAML

Before you request SAML activation, you should consider the following:

  • Add existing organization users to the SAML identity provider
  • If you are using a Developer Services portal, the portal uses OAuth to access Edge
  • Use the Classic Edge UI with SAML
  • Make sure your scripts do not use Basic Auth

These issues are described in detail below.

Add existing organization users to the SAML identity provider

Before you convert an Edge organization to use SAML, you should have already added all existing organization users to your SAML identity provider. After you enable SAML, existing users will not be able to log in to the Edge UI until they are added to the SAML identity provider.

All users require an email address that is returned to the Edge UI as part of the SAML authentication process. 

For information on adding new users to Edge after enabling SAML, see Registering new Edge UI users with SAML below.

Configure the Developer Services portal for SAML

The Developer Services portal acts as a client for Edge. That means the portal does not function as a stand-alone system. Instead, much of the information used by the portal is actually stored on Edge. When necessary, the portal makes a request to retrieve information from Edge or to send information to Edge.

See Communicating between the portal and Edge for more information on how the portal communicates with Edge.

By default the connection between the portal and Edge uses Basic Auth. If you enable SAML authentication on Edge, then the portal must be updated to use SAML authentication to connect to Edge. 

After you enable SAML on the portal, the portal connects to Edge by using SAML authentication. However, portal developers, meaning the developers building apps by using your APIs, continue to log in to the portal using Basic Auth as defined by the portal. 

To enable SAML on the portal, you must coordinate with Apigee Support:

  1. Contact Apigee Support to enable SAML as described below in Enabling SAML for Edge.
    Note: If you customized any Drupal modules used by the portal, such as the edge-php-sdk and the Apigee Profile Installation module. the process of enabling SAML may take additional time. Inform Apigee Support if you modified any Drupal modules when requesting SAML.  
  2. Apigee Support will request that you update your portal in Pantheon to install the Drupal modules required to support SAML.
  3. After you update your portal, Apigee Support configures the portal to connect to Edge using SAML authentication. You can see the new fields added to the portal for SAML configuration by going to the Configuration > Dev Portal menu item in Drupal:

    These fields are set by Apigee and are read-only. Contact Apigee Support if you require the credentials to be updated.

Use the Classic Edge UI with SAML

Apigee recommends that you use the classic Edge UI with SAML, and not the new Edge UI. Certain features in the new Edge UI do not support SAML.

Make sure your scripts do not use Basic Auth

After you enable SAML, Basic Auth is disabled for the Edge management API. Also, any scripts (Maven scripts, shell scripts, apigeetool, etc.) that rely on Edge API calls supporting Basic Auth no longer work. 

You must update any API calls and scripts to use OAuth2 bearer tokens. See Use SAML with the Edge management API above. 

Enabling SAML for Edge 

You must work with Apigee Support to enable SAML.

Information required by Apigee to enable SAML 

Existing customers should open a ticket with Apigee Support requesting SAML support for one or more organizations. New customers can request SAML access during the Edge onboarding process.

Information required to enable SAML:

  • A zone name (all lowercase, no special characters)
  • The list of organizations for which you want to enable SAML
  • The metadata URL of the SAML identity provider 
  • List of developer portals and the Edge organizations that are associated with the portals
  • Any modification you made to Drupal modules as part of customizing the portals

Information returned to you by Apigee

After SAML support is enabled, Apigee returns to you the following information that you need to use to configure your identity provider:

  1. The service provider metadata URL for you to add to your identity provider. The URL contains your zone name, in the form:
    https://zoneName.login.apigee.com/saml/metadata/alias/zoneName.apigee-saml-login
  2. The EntityID, in the form:
    zoneName.apigee-saml-login
  3. Name ID format, in the form:
    urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

    Note: Edge requires an email address to identify the user. Therefore, the identity provider must return an email address.
  4. Assertion Consumer Service (ACS) URL, in the form:
    https://zoneName.login.apigee.com/saml/SSO/alias/zoneName.apigee-saml-login

Disabling SAML

You might later decide to disable SAML and return to Basic Auth. If you decide to disable SAML:

  • Open a ticket with Apigee Support
  • Users must select the Reset password link on the Edge UI login page to set a new password.
  • If the customer chooses to sign up again in the future, Apigee might require them to re-enter their details.

Registering new Edge UI users with SAML authentication

After you enable SAML for an organization, the process of adding new users to the Edge UI is:

  1. The user registers with the SAML identity provider.
  2. An organization administrator adds the user to the Edge UI as described in Creating global users.
    1. Select Admin > Organization Users in the Edge UI
    2. Select +User.
    3. Enter the user’s email address.
    4. Enter the user’s role.
    5. Select Save.
  3. The user logs in to the Edge UI. 
 

Help or comments?