Enable SAML

With SAML enabled, access to the Edge management API continues to use OAuth2 access tokens. These tokens are generated by the Edge SSO which now accepts SAML assertions returned by 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.

To enable SAML:

  1. Contact Apigee Support and let them know you want to enable SAML.
  2. Provide the following information to Apigee:
    • 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

    Apigee configures the identity zone to interact with your SAML identity provider and returns information that you then use to configure your identity provider.

  3. Add existing organization users to the SAML identity provider, as described in Registering new Edge UI users with SAML. All users require an email address that is returned to the Edge UI as part of the SAML authentication process.

    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.

  4. Configure your identity provider with the following information from Apigee:
    • 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
    • The EntityID, in the form:
      zoneName.apigee-saml-login
    • Name ID format, in the form:
      urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    • Assertion Consumer Service (ACS) URL, in the form:
      https://zoneName.login.apigee.com/saml/SSO/alias/zoneName.apigee-saml-login
  5. You can now access the UI or the management API with SAML. For more information, see Using SAML to access the management API.
  6. Update any scripts that use Basic Authentication to now use SAML assertions, as described in Remove Basic Auth.

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 Prerequisites for enabling SAML for more.

Remove Basic Auth

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.

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

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

You can 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

Registering new Edge UI users with SAML authentication

After you enable SAML for an organization, you need to register any new SAML users that are not already registered with your organization by performing the following steps:

  1. The user registers with the SAML identity provider.
  2. An organization administrator adds the user to the Edge UI as described in Adding 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. Click Save.
  3. The user logs in to the Edge UI.

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.

Disable 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 and coordinate the disabling of SAML.
  • Once SAML is disabled, users must select the Reset password link on the Edge UI login page to set a new password.
  • If you choose to enable SAML again in the future, Apigee might require you to re-enter your details.