Configuring SAML for SSO | MuleSoft Documentation
# Configuring 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


## Before You Begin
  * 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. Sign in to Anypoint Platform using an account that has the root 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. It is the "X509Certificate" value in the SAML Response.
     * **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. Sign out of Anypoint Platform, navigate to the sign-on URL you entered in the **Identity Management SAML 2.0** form, and then sign 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. Sign in to Anypoint Platform using an account that has the root 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. Sign in to Anypoint Platform using an account that has the root 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. Sign in to Anypoint Platform using an account that has the root 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. Sign in to Anypoint Platform using an account that has the root 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**.
### 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. Sign in to Anypoint Platform using an account that has the root 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 signin.
  1. When a user signs in to Anypoint Platform, a cookie is created for the signin session: `mulesoft.sess=xxxxx`.
The cookie contains the location, such as a public portal, where the user initiated the signin.
  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 where they initiated the signin process.
  6. After the user successfully signs 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.
## Updating a SAML Identity Provider
Organization administrators can update existing SAML providers. However, when you update `Issuer` or `Audience`, you will effectively switch to a different IdP, which can cause issues such as unwanted user duplication. For more information, see the Help article on preventing user duplication.
## View Limits for a SAML Identity Provider
Each configured SAML IdP has a **Limits** section that shows how close it is to hitting limits imposed by Anypoint Platform.
To view limits:
  1. In the Access Management navigation menu, click **Identity Providers**.
  2. Click the SAML IdP for which you want to view limits.
  3. Click the **Limits** tab.


For more information on limits in Access Management, see Limits.
## See Also
  * Configuring Single Signout