SAML Overview

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

SAML allows specific administrators to control how all organization members authenticate when using Apigee Edge by delegating to a single sign-on (SSO) server. 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.

To enable SSO using SAML for integrated portals, see Configure the SAML identity provider.

Understand identity zone management in Edge

An identity zone is an authentication realm that defines the identity providers used for authentication and custom configuration of the user registration and sign-in experience. Only when users authenticate with the identity provider can they access the entities that are scoped to the identity zone.

Apigee Edge supports the authentication types described in the following table.

Authentication type Description
Default Create an Apigee Edge account and sign in to the Edge UI using a username and password. Using the Edge API, you use those same credentials with HTTP basic authentication to authorize calls.
SAML Security assertion markup language (SAML) is a standard protocol for single sign-on (SSO) environments. SSO authentication using SAML enables you to sign in to Apigee Edge using your existing credentials, without having to create new accounts.

To support SAML authentication, you create a new identity zone and configure a SAML identity provider, as described in Enable SAML.

Advantages of SAML authentication

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

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

Considerations

Before you decide to use SAML, you should consider the following requirements:

  • Existing users: You must add all existing organization users to the SAML identity provider.
  • Portal: If you are using a Drupal-based developer portal, the portal uses OAuth to access Edge and may need to be reconfigured before you can use it.
  • Basic Auth will be disabled: You will need to replace Basic Auth with OAuth for all of your scripts.
  • OAuth and SAML must be kept separate: If you use both OAuth 2.0 and SAML, you must use separate terminal sessions for your OAuth 2.0 flow and SAML flow.

How SAML works with Edge

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 its 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 OAuth 2.0 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.example.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.0 authentication token for the Edge UI, and redirects the user to the main Edge UI page at: 
    https://zonename.apigee.com/platform/orgName

    Where orgName is the name of an Edge organization.

See also Access the Edge API with SAML.

Get started!

See how to enable SAML