Configure your SAML IDP

The SAML specification defines three entities:

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

When SAML is enabled, the principal (a New Edge UI user) requests access to the service provider (the Apigee SSO). The Apigee SSO (in its role as a Federated Identity Broker) then requests and obtains an identity assertion from the SAML IDP and uses that assertion to generate the OIDC and OAuth2 tokens required to access the New Edge UI. The user is then redirected back to the New Edge UI.

This process is as follows:

SAML Authentication Flow

In this diagram:

  1. The user attempts to access the New Edge UI by making a request to the login URL for the Edge UI. For example: https://edge_management_ui_IP_DNS:3001
  2. Unauthenticated requests are redirected to the Apigee SSO.
  3. The SSO redirects the request to the SAML IDP. For example, https://idp.customer.com.
  4. If the user is not logged in to the identity provider, they are prompted to log in.
  5. The user logs in.
  6. The user is authenticated by the SAML IDP, which generates a SAML 2.0 assertion and returns it to the Apigee SSO.
  7. The Apigee SSO validates the assertion, extracts the user identity from the assertion, generates the OIDC/OAuth2 authentication tokens for the New Edge UI, and redirects the user to the main New Edge UI page at the following URL: 
    https://edge_management_ui_IP_DNS:3001/edge

Edge supports many IDPs, including Okta and the Microsoft Active Directory Federation Services (ADFS). For Okta, see the following section.

To configure your SAML IDP, Edge requires an email address to identify the user. Therefore, the identity provider must return an email address as part of the identity assertion.

In addition, you will need to configure your IDP with the following information to ensure it can communicate with the Apigee SSO:

Setting Description
Assertion Consumer Service URL (Single Sign On URL)

This is the redirect URL back to the Apigee SSO after the user enters their IDP credentials. It takes the form:

protocol://apigee_sso_IP_DNS:port/callback

For example:

http://1.2.3.4:9099/callback
The SP entity ID (or Audience URI)

By default, the Apigee SSO expects the SP Entity ID to be apigee-saml-login-opdk.

If you override this default by setting the lib_settings_saml_entity_issuer property in your configuration, specify your custom Entity ID here instead.

Configuring Okta

To configure Okta:

  1. Log in to Okta.
  2. Select Applications and then select your SAML application.
  3. Select the Assignments tab to add any users to the application. These users will be able to log in to the New Edge UI and make Edge API calls. However, you must first add each user to an Edge organization and specify the user's role. See Register new Edge users for more.
  4. Select the Sign on tab to obtain the Identity Provider metadata URL. You will need this to configure the SAML settings in your /opt/apigee/customer/application/openldap.properties file.
  5. Select the General tab to configure the Okta application, as shown in the following table:
    Setting Description
    Single sign on URL

    Specifies the redirect URL back to the SSO for use after the user enters their Okta credentials. This URL is in the form:

    http://apigee_sso_IP_DNS:9099/callback

    If the Apigee SSO terminates TLS:

    https://apigee_sso_IP_DNS:9443/callback

    If a load balancer terminates TLS:

    https://load_balancer_IP_or_DNS:443/callback
    Use this for Recipient URL and Destination URL Set this checkbox.
    Audience URI (SP Entity ID) Set this to apigee-saml-login-opdk. This is the default Edge SP Entity ID. If you override this value using the lib_settings_saml_entity_issuer property in your configuration, specify your custom Entity ID here instead.
    Default RelayState Leave blank.
    Name ID format Specify EmailAddress.
    Application username Specify Okta username.
    Attribute Statements Specify the attributes that map to the SAML_USERNAME_ATTR, SAML_EMAIL_ATTR, and SAML_GROUPS_ATTR properties in your configuration. Typically, you should map name, email, and groups.

Once configured, Okta will successfully pass the SAML assertion back to the Apigee SSO during login.