Configure SAML for SSO

Configure SAML to provide external authentication of users and Single Sign-on (SSO) capability so users don’t need to provide additional credentials when they access Anypoint Platform.

Configuring SAML for SSO involves:

  • Beginning with a configured SAML identity provider (IdP)

  • Navigating to and completing the External Identity - Identity Management SAML 2.0 form in Anypoint Platform, and optionally configuring some advanced settings

  • Saving and testing your new configuration

Prerequisites

  • Your Anypoint Platform organization must be set up as your audience.

  • The assertion consumer service must be set to send a POST request to https://anypoint.mulesoft.com/accounts/login/:org-domain/providers/:providerId/receive-id.
    Note that :providerId is available only after you create the provider configuration.

  • If you are using the Anypoint Platform EU Control Plane, the endpoint is https://eu1.anypoint.mulesoft.com/accounts/login/:org-domain/providers/:providerId/receive-id.

  • If you are using the Anypoint Platform Gov Cloud, the endpoint is https://gov.anypoint.mulesoft.com/accounts/login/:org-domain/providers/:providerId/receive-id.

Configure SAML in Identity Management

  1. Log in to Anypoint Platform using an account that has the Organization Administrator permission.

  2. In the navigation bar or the main Anypoint Platform page, click Access Management.

  3. In the Access Management navigation menu, click Identity Providers.

  4. Select Identity Providers > SAML 2.0.

  5. In the Configurations tab, complete the required fields of the Identity Management SAML 2.0 form:

    • Sign On URL

      Redirect URL provided by the IdP for signin, for example: https://example.com/sso/saml.

    • Sign Off URL

      URL to redirect signout requests, so users both sign out of the Anypoint Platform and have their SAML user’s status set to signed out.

    • Issuer

      ID of the identity provider instance that sends SAML assertions.

    • Public Key

      Public key provided by the identity provider, which is used to sign the SAML assertion.

    • Audience

      An arbitrary string value that identifies your Anypoint Platform organization. The typical value for this string is <organizationDomain>.anypoint.mulesoft.com.

    • Single Sign-On Initiation

      Specify whether SSO can be initiated by the Anypoint Platform, your identity provider (for example, Okta), or both.

      • The Service Provider Only option allows only the Anypoint Platform to initiate SSO.

      • The Identity Provider Only option allows only your external identity provider to initiate SSO.

      • The Both option allows either Anypoint Platform or your external identity provider to initiate SSO.

        The default value for this setting for newly configured identity provider configurations is Both.

  6. Optionally, expand Advanced settings, and provide the following values:

    • Username Attribute

      Field name in the SAML AttributeStatements that maps to username. If no value is configured, the NameID attribute of the SAML Subject is used (Note: this is outside the SAML AttributeStatements).

    • First Name Attribute

      Field name in the SAML AttributeStatements that maps to First Name.

    • Last Name Attribute

      Field name in the SAML AttributeStatements that maps to Last Name.

    • Email Attribute

      Field name in the SAML AttributeStatements that maps to Email.

    • Group Attribute

      Field name in the SAML AttributeStatements that maps to Group.

    • Require encrypted SAML assertions

      If enabled, the SAML assertions sent from the IdP must be encrypted and follow the guidelines mentioned in the Prerequisites.

  7. Click Create.

  8. Log out of Anypoint Platform, navigate to the sign-on URL you entered in the Identity Management SAML 2.0 form, and then log in through your identity provider to test the configuration.

Rotate a SAML Key

As a security best practice, many organizations rotate the key used to encrypt SAML 2.0 assertions. With the Key Rotation feature, Anypoint Platform can generate a new key, or you can upload a public and private key pair (up to three keys). When you want to rotate a key, you can designate a new primary key in Anypoint Platform and your IdP, and you can revoke the obsolete key to remove it from the rotation.

The keys that you create or upload to Anypoint Platform must also exist in your IdP. All keys present in Anypoint Platform can decrypt SAML 2.0 assertions sent by your IdP. However, only the primary key is used by Anypoint Platform to sign SAML 2.0 AuthnRequests and SLO requests; the primary key must be configured in your IdP to validate the signatures.

If you are migrating from the default Anypoint Platform SSO certificate to a new certificate, you must update the Assertion Consumer Service (ACS) URL in your IdP. Only the new ACS URL supports the keys generated by the key rotation feature. If your ACS URL already follows the pattern of …​/accounts/login/:org-domain/providers/:providerId/receive-id, you do not need to change the ACS URL.

Add Keys for Key Rotation

When you use the key rotation feature, you must have keys available in Anypoint Platform for your IdP to use. Anypoint Platform enables you to generate new keys or upload existing public/private key pairs.

Generate a New Key

  1. Log in to Anypoint Platform using an account that has the Organization Administrator permission.

  2. In the navigation bar or the main Anypoint Platform page, click Access Management.

  3. In the Access Management navigation menu, click Identity Providers.

  4. Next to a SAML 2.0 IdP, click Edit.

  5. Click the Anypoint Keys tab.

  6. Click + New key and select Generate.
    A newly generated key appears in the list of keys.

Upload an Existing Private and Public Key Pair

  1. Log in to Anypoint Platform using an account that has the Organization Administrator permission.

  2. In the navigation bar or the main Anypoint Platform page, click Access Management.

  3. In the Access Management navigation menu, click Identity Providers.

  4. Next to a SAML 2.0 IdP, click Edit.

  5. Click the Anypoint Keys tab.

  6. Click + New key, and select Upload.

  7. In the Private key field, paste your private key.

  8. In the Public key field, paste your certificate.

  9. Click Upload.
    The key you uploaded appears in the list of keys.

Rotate the Primary Key

Because you can store up to three keys, you must designate a primary key to be used for signing requests from Anypoint Platform. Before reassigning the primary key, ensure your IdP can access the key that you intend to use.

  1. Log in to Anypoint Platform using an account that has the Organization Administrator permission.

  2. In the navigation bar or the main Anypoint Platform page, click Access Management.

  3. In the Access Management navigation menu, click Identity Providers.

  4. Next to a SAML 2.0 IdP, click Edit.

  5. Click the Anypoint Keys tab.

  6. Next to the key that you want to make primary, click …​ and select Use as primary key…​.

  7. Click Apply.

Revoke a Key

To help ensure security, revoke a key that you have already used as the primary key. Before you revoke a key, ensure your IdP is not using the key. Note that when you revoke a public key, Anypoint Platform also revokes the corresponding private key. For security purposes, you cannot retrieve a key that has been revoked.

  1. Log in to Anypoint Platform using an account that has the Organization Administrator permission.

  2. In the navigation bar or the main Anypoint Platform page, click Access Management.

  3. In the Access Management navigation menu, click Identity Providers.

  4. Next to a SAML 2.0 IdP, click Edit.

  5. Click the Anypoint Keys tab.

  6. Next to the key that you want to revoke, click …​ and select Revoke.

  7. Click Revoke.

Import SAML Metadata

When creating a new SAML 2.0 configuration, you can upload an XML file containing your identity provider’s SAML 2.0 metadata to Anypoint Platform using the Import IdP Metadata link. Once uploaded, the XML file’s values automatically populate the Identity Management SAML 2.0 form.

When you upload an XML file to import your metadata:

  • The file must be smaller than 16 KB.

  • If you upload an XML file that contains more than one entry, Anypoint Platform uses the first identity provider configuration.

  • Anypoint Platform does not check the validity of the values in the XML that you upload.
    Verify that your identity configuration is correct before creating the identity provider configuration.

Export SAML Metadata

If your identity provider supports uploading service-provider metadata, you can click the Anypoint service provider metadata link to download your SAML configuration settings in an XML file. You can then upload this file to your identity provider to configure Anypoint Platform. Note that you must have a SAML 2.0 identity configuration to export this data.

SSO Redirect Process Using Cookies

Anypoint Platform uses cookies to ensure that SSO users are redirected to the same location from which they initiated their login.

  1. When a user logs in to Anypoint Platform, a cookie is created for the login session: mulesoft.sess=xxxxx.
    The cookie contains the location, such as a public portal, from which the user initiated the login.

  2. The cookie is passed to the user’s browser.

  3. The user is directed to their SSO provider for authentication.

  4. After the user is authenticated using SSO, the provider directs the user back to Anypoint Platform with the authorization decision SAML response.

  5. The session cookie, mulesoft.sess=xxxxx, is passed from the browser, which redirects the user back to the location from which they initiated the login process.

  6. After the user successfully logs in to Anypoint Platform, the mulesoft.sess cookie returns to its default value, based on the OWASP standard.

Users can also be redirected based on their permissions. This occurs when:

  • The browser does not pass a cookie.

  • The cookie has expired.

  • The cookie is set to the default value.

In these cases, a user with the Organization Administrator permission is redirected to the Anypoint Platform landing page. Users who do not have the Organization Administrator permission are directed to Anypoint Exchange.

See Also

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub