Configuring the identity provider

When you create a new portal, the built-in identity provider is configured and enabled. The built-in identity provider prompts users for account credentials (username and password) to access the developer portal. In addition, you can configure and enable a SAML identity provider.

Configure the built-in and SAML (Beta) identity providers, as described in the following sections.

Configuring the built-in identity provider

Configure the built-in identity provider, as described in the following sections.

Accessing the Built-in Identity Provider page

To access the built-in identity provider:

  1. Select Publish > Developer Programs in the left navigation bar to access the Developer Programs page.
  2. Click the row of the developer program for which you want to configure the identity provider.
  3. Click the Configuration tab.
  4. In the Identity providers section, click the Built-in provider type.
  5. Configure the built-in identity provider, as described in the following sections:

Enabling the built-in identity provider

To enable the built-in identity provider:

  1. Access the Built-in Identity Provider page.
  2. Click in the Provider Configuration section.
  3. Select the Enabled checkbox to enable the identity provider.

    To disable the built-in identity provider, deselect the checkbox.

    Note: At least one identity provider must be enabled to allow users to sign in.

  4. Click Save.

Restricting portal registration by email address or domain

Restrict portal registration by identifying the individual email addresses (developer@some-company.com) or email domains (some-company.com, without the leading @) that can create accounts on your portal.

To match all nested subdomains, prepend the *. wildcard string to a domain or subdomain. For example, *.example.com will match test@example.com, test@dev.example.com, and so on.

If left blank, any email address can be used to register on the portal.

To restrict portal registration by email address or domain:

  1. Access the Built-in Identity Provider page.
  2. Click in the Provider Configuration section.
  3. In the Account restrictions section, enter an email address or email domain that you want to allow to register and sign in to the portal in the text box and click +.
  4. Add additional entries, as required.
  5. To delete an entry, click x adjacent to the entry.
  6. Click Save.

Configuring email notifications

Note: Apigee recommends that you configure the SMTP server for the email notifications originating from the portal. See Configure an SMTP server.

For the built-in provider, you can enable and configure the following email notifications:

Email notification Recipient Trigger Description
Account NotifyAPI providerPortal user creates a new accountIf you configured your portal to require manual activation of developer accounts, you need to manually activate the developer account before the portal user can sign in.

NOTES:

  • Ensure that you Configure notifications for new developer account registration for the developer program.
  • For the Beta release, the portal user is given no indication that their account must be manually activated before they can sign in. It is recommended that if you configure manual activation, you expedite the activation of new developer accounts.
Account VerifyPortal userPortal user creates a new accountProvides a secure link to verify account creation. The link expires in 10 minutes.

When configuring the email notifications:

  • Use HTML tags to format the text. Be sure to send a test email to validate the formatting appears as expected.
  • You can insert one or more of the following variables which will be substituted when the email notification is sent.

    Variable Description
    {{firstName}} First name
    {{lastName}} Last name
    {{email}} Email address
    {{siteurl}} Link to the live portal
    {{verifylink}} Link used for account verification

To configure email notifications:

  1. Access the Built-in Identity Provider page.
  2. To configure email notifications sent to:

    • API providers for new developer account activation, click in Account Notify section.
    • Portal users to verify their identity, click in Account Verify section.
  3. Edit the Subject and Body fields.

  4. Click Send Test Email to send a test email to your email address.

  5. Click Save.

Configuring the SAML identity provider (Beta)

Configure the SAML identity provider, as described in the following sections.

Accessing the SAML Identity Provider page

To access the SAML identity provider:

  1. Select Publish > Developer Programs in the left navigation bar to access the Developer Programs page.
  2. Click the row of the developer program for which you want to configure the identity provider.
  3. Click the Configuration tab.
  4. In the Identity providers section, click the SAML provider type.
  5. Configure the SAML identity provider, as described in the following sections:

Enabling the SAML identity provider

To enable the SAML identity provider:

  1. Access the SAML Identity Provider page.
  2. Click in the Provider Configuration section.
  3. Select the Enabled checkbox to enable the identity provider.

    To disable the SAML identity provider, deselect the checkbox.

    Note: At least one identity provider must be enabled to allow users to sign in.

  4. Click Save.

  5. If you have configured a custom domain, see Use a custom domain with the SAML identity provider.

Configuring SAML settings

To configure the SAML settings:

  1. Access the SAML Identity Provider page.
  2. In the SAML Settings section, click .
  3. Click Copy adjacent to the SP metadata URL.

    Note: The SAML identity provider must be enabled in order for the SP metadata URL to be populated.

  4. Configure your SAML identity provider using the information in the service provider (SP) metadata file.

    For some SAML identity providers, you will be prompted only for the metadata URL. For others, you will need to extract specific information from the metadata file and enter it into a form.

    In the latter case, paste the URL into a browser to download the SP metadata file and extract the required information. For example, the entity ID or sign-in URL can be extracted from the following elements in the SP metadata file:

    Note: In the SP metadata file, the sign-in URL is referred to as the AssertionConsumerService (ACS) URL.

    • <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="diyyaumzqchrbui-a5vnmu1sp8qzekbd.apigee-saml-login" entityID="diyyaumzqchrbui-a5vnmu1sp8qzekbd.apigee-saml-login">
    • <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://diyyaumzqchrbui-a5vnmu1sp8qzekbd.portal-login.apigee.com/saml/SSO/alias/diyyaumzqchrbui-a5vnmu1sp8qzekbd.apigee-saml-login" index="0" isDefault="true"/>
  5. Configure the SAML settings for the identity provider.

    In the SAML Settings section, edit the following values obtained from your SAML identity provider metadata file:

    SAML settingDescription
    Sign-in URLURL to which users are redirected to sign-in to the SAML identity provider.
    For example: https://dev-431871.oktapreview.com/app/googledev431871_devportalsaml_1/exkhgdyponHIp97po0h7/sso/saml
    Sign-out URLURL to which users are redirected to sign-out of the SAML identity provider.
    Note: If your SAML identity provider does not provide a sign-out URL or you do not want users to be signed out of your SAML identity provider when they sign out of the integrated portal, leave this field blank.
    IDP entity IDUnique ID for the SAML identity provider.
    For example: http://www.okta.com/exkhgdyponHIp97po0h7
  6. Click Save.

Configuring custom user attributes for the SAML identity provider

To ensure proper mapping between the SAML identity provider and portal developer accounts, it is recommended that you create and configure the custom user attributes defined in the following table for your SAML identity provider. Set the value of each custom attribute to the corresponding user attribute defined by your SAML identity provider (for example, Okta).

Custom attribute Example (Okta)
first_name user.firstName
last_name user.lastName
email user.email

The following shows how to configure custom user attributes and the NameID attribute using Okta as your third-party SAML identity provider.

Using a custom domain with the SAML identity provider

After you configure and enable the SAML identity provider, you can configure a custom domain (such as, developers.example.com), as described in Customize your domain.

It is important to keep the configuration settings in sync between the custom domain and SAML identity provider. If the configuration settings get out of sync, you may experience issues during authorization. For example, the authorization request sent to the SAML identity provider may have an AssertionConsumerServiceURL that is not defined using the custom domain.

To keep the configuration settings in sync between the custom domain and SAML identity provider:

  • If you configure or update the custom domain after you enable and configure the SAML identity provider, save the custom domain configuration and ensure it is enabled. Then reset the custom domain (described below) and re-configure your SAML identity provider using the updated information in the service provider (SP) metadata file, as described in Configure SAML settings.

  • If you configure or update the custom domain after you enable and configure the SAML identity provider, save the custom domain configuration and ensure it is enabled. Wait approximately 30 minutes for the cache to invalidate, then re-configure your SAML identity provider using the updated information in the service provider (SP) metadata file, as described in Configure SAML settings. You should see your custom domain in the SP metadata.

  • If you configure a custom domain before you configure and enable the SAML identity provider, you need to reset the custom domain (described below) to ensure that the SAML identity provider is configured correctly.

  • If you need to reset (disable and re-enable) the SAML identity provider, as described in Enable the SAML identity provider, you must also Reset the custom domain (described below).

Resetting the custom domain

To reset (disable and enable) the custom domain:

  1. Select Publish > Portals in the left navigation and select your portal.
  2. Select Settings in the drop-down menu in the top navigation bar or on the landing page.
  3. Click the Domains tab.
  4. Click Disable to disable the custom domain.
  5. Click Enable to re-enable the custom domain.

For more information, see Customize your domain.

Uploading a new certificate

To upload a new certificate:

  1. Download the certificate from your SAML identity provider.

    Note: The certificate must be in PEM or PKCSS format. If necessary, convert an x509 certificate to PEM format.

  2. Access the SAML Identity Provider page.

  3. Click the row of the identity zone for which you want to upload a new certificate.

  4. In the Certificate section, click .

  5. Click Browse and navigate to the certificate in your local directory.

  6. Click Open to upload the new certificate.
    The Certificate information fields are updated to reflect the selected certificate.

  7. Verify that the certificate is valid and has not expired.

  8. Click Save.

Converting an x509 certificate to PEM format

If you download an x509 certificate, you need to convert it to PEM format.

To convert an x509 certificate to PEM format:

  1. Copy the contents of the ds:X509Certificate element from the SAML identity provider metadata file and paste it into your favorite text editor.
  2. Add the following line at the top of the file:
    -----BEGIN CERTIFICATE-----
  3. Add the following line at the bottom of the file:
    -----END CERTIFICATE-----
  4. Save the file using a .pem extension.

The following provides an example of the PEM file contents:

-----BEGIN CERTIFICATE-----
MIICMzCCAZygAwIBAgIJALiPnVsvq8dsMA0GCSqGSIb3DQEBBQUAMFMxCzAJBgNV
BAYTAlVTMQwwCgYDVQQIEwNmb28xDDAKBgNVBAcTA2ZvbzEMMAoGA1UEChMDZm9v
MQwwCgYDVQQLEwNmb28xDDAKBgNVBAMTA2ZvbzAeFw0xMzAzMTkxNTQwMTlaFw0x
ODAzMTgxNTQwMTlaMFMxCzAJBgNVBAYTAlVTMQwwCgYDVQQIEwNmb28xDDAKBgNV
BAcTA2ZvbzEMMAoGA1UEChMDZm9vMQwwCgYDVQQLEwNmb28xDDAKBgNVBAMTA2Zv
bzCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAzdGfxi9CNbMf1UUcvDQh7MYB
OveIHyc0E0KIbhjK5FkCBU4CiZrbfHagaW7ZEcN0tt3EvpbOMxxc/ZQU2WN/s/wP
xph0pSfsfFsTKM4RhTWD2v4fgk+xZiKd1p0+L4hTtpwnEw0uXRVd0ki6muwV5y/P
+5FHUeldq+pgTcgzuK8CAwEAAaMPMA0wCwYDVR0PBAQDAgLkMA0GCSqGSIb3DQEB
BQUAA4GBAJiDAAtY0mQQeuxWdzLRzXmjvdSuL9GoyT3BF/jSnpxz5/58dba8pWen
v3pj4P3w5DoOso0rzkZy2jEsEitlVM2mLSbQpMM+MUVQCQoiG6W9xuCFuxSrwPIS
pAqEAuV4DNoxQKKWmhVv+J0ptMWD25Pnpxeq5sXzghfJnslJlQND
-----END CERTIFICATE-----