# Using SAML identity providers with a user pool You can choose to have your web and mobile app users sign in through a SAML identity provider (IdP) like [Microsoft Active Directory Federation Services (ADFS)](https://msdn.microsoft.com/en-us/library/bb897402.aspx), or [Shibboleth](http://www.shibboleth.net/). You must choose a SAML IdP which supports the [SAML 2.0 standard](http://saml.xml.org/saml-specifications). With managed login, Amazon Cognito authenticates local and third-party IdP users and issues JSON web tokens (JWTs). With the tokens that Amazon Cognito issues, you can consolidate multiple identity sources into a universal OpenID Connect (OIDC) standard across all of your apps. Amazon Cognito can process SAML assertions from your third-party providers into that SSO standard. You can create and manage a SAML IdP in the AWS Management Console, through the AWS CLI, or with the Amazon Cognito user pools API. To create your first SAML IdP in the AWS Management Console, see [Adding and managing SAML identity providers in a user pool](cognito-user-pools-managing-saml-idp.md). ![\[Authentication overview with SAML sign-in\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-saml.png) **Note** Federation with sign-in through a third-party IdP is a feature of Amazon Cognito user pools. Amazon Cognito identity pools, sometimes called Amazon Cognito federated identities, are an implementation of federation that you must set up separately in each identity pool. A user pool can be a third-party IdP to an identity pool. For more information, see [Amazon Cognito identity pools](cognito-identity.md). ## Quick reference for IdP configuration You must configure your SAML IdP to accept request and send responses to your user pool. The documentation for your SAML IdP will contain information about how to add your user pool as a relying party or application for your SAML 2.0 IdP. The documentation that follows provides the values that you must provide for the SP entity ID and assertion consumer service (ACS) URL.User pool SAML values quick reference **SP entity ID** ``` urn:amazon:cognito:sp:us-east-1_EXAMPLE ``` **ACS URL** ``` https://Your user pool domain/saml2/idpresponse ``` You must configure your user pool to support your identity provider. The high-level steps to add an external SAML IdP are as follows. 1. Download SAML metadata from your IdP, or retrieve the URL to your metadata endpoint. See [Configuring your third-party SAML identity provider](cognito-user-pools-integrating-3rd-party-saml-providers.md). 1. Add a new IdP to your user pool. Upload the SAML metadata or provide the metadata URL. See [Adding and managing SAML identity providers in a user pool](cognito-user-pools-managing-saml-idp.md). 1. Assign the IdP to your app clients. See [Application-specific settings with app clients](user-pool-settings-client-apps.md). **Topics** + [Quick reference for IdP configuration](#cognito-user-pools-saml-idp-reference) + [Things to know about SAML IdPs in Amazon Cognito user pools](cognito-user-pools-saml-idp-things-to-know.md) + [Case sensitivity of SAML user names](#saml-nameid-case-sensitivity) + [Configuring your third-party SAML identity provider](cognito-user-pools-integrating-3rd-party-saml-providers.md) + [Adding and managing SAML identity providers in a user pool](cognito-user-pools-managing-saml-idp.md) + [SAML session initiation in Amazon Cognito user pools](cognito-user-pools-SAML-session-initiation.md) + [Signing out SAML users with single sign-out](cognito-user-pools-saml-idp-sign-out.md) + [SAML signing and encryption](cognito-user-pools-SAML-signing-encryption.md) + [SAML identity provider names and identifiers](cognito-user-pools-managing-saml-idp-naming.md) # Things to know about SAML IdPs in Amazon Cognito user pools Implementation of a SAML 2.0 IdP comes with some requirements and restrictions. Refer to this section when you're implementing your IdP. You'll also find information that's useful for troubleshooting errors during SAML federation with a user pool. **Amazon Cognito processes SAML assertions for you** Amazon Cognito user pools support SAML 2.0 federation with POST-binding endpoints. This eliminates the need for your app to retrieve or parse SAML assertion responses, because the user pool directly receives the SAML response from your IdP through a user agent. Your user pool acts as a service provider (SP) on behalf of your application. Amazon Cognito supports SP-initiated and IdP-initiated single sign-on (SSO) as described in sections 5.1.2 and 5.1.4 of the [SAML V2.0 Technical Overview](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html). **Provide a valid IdP signing certificate** The signing certificate in your SAML provider metadata must not be expired when you configure the SAML IdP in your user pool. **User pools support multiple signing certificates** When your SAML IdP includes more than one signing certificate in SAML metadata, at sign-in your user pool determines that the SAML assertion is valid if it matches any certificate in the SAML metadata. Each signing certificate must be no longer than 4,096 characters in length. **Maintain the relay state parameter** Amazon Cognito and your SAML IdP maintain session information with a `relayState` parameter. 1. Amazon Cognito supports `relayState` values greater than 80 bytes. While SAML specifications state that the `relayState` value "must not exceed 80 bytes in length”, current industry practice often deviates from this behavior. As a consequence, rejecting `relayState` values greater than 80 bytes will break many standard SAML provider integrations. 1. The `relayState` token is an opaque reference to state information maintained by Amazon Cognito. Amazon Cognito doesn't guarantee the contents of the `relayState` parameter. Don't parse its contents such that your app depends on the result. For more information, see the [SAML 2.0 specification](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). **Identify the ACS endpoint** Your SAML identity provider requires that you set an assertion consumer endpoint. Your IdP redirects your users to this endpoint with their SAML assertion. Configure the following endpoint in your user pool domain for SAML 2.0 POST binding in your SAML identity provider. ``` https://Your user pool domain/saml2/idpresponse With an Amazon Cognito domain: https://mydomain.auth.us-east-1.amazoncognito.com/saml2/idpresponse With a custom domain: https://auth.example.com/saml2/idpresponse ``` See [Configuring a user pool domain](cognito-user-pools-assign-domain.md) for more information about user pool domains. **No replayed assertions** You can't repeat, or *replay*, a SAML assertion to your Amazon Cognito `saml2/idpresponse` endpoint. A replayed SAML assertion has an assertion ID that duplicates the ID of an earlier IdP response. **User pool ID is SP entity ID** You must provide your IdP with your user pool ID in the service provider (SP) `urn`, also called the *audience URI* or *SP entity ID*. The audience URI for your user pool has the following format. ``` urn:amazon:cognito:sp:us-east-1_EXAMPLE ``` You can find your user pool ID under **User pool overview** in the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). **Map all required attributes** Configure your SAML IdP to provide values for any attributes that you set as required in your user pool. For example, `email` is a common required attribute for user pools. Before your users can sign in, your SAML IdP assertions must include a claim that you map to the **User pool attribute** `email`. For more information about attribute mapping, see [Mapping IdP attributes to profiles and tokens](cognito-user-pools-specifying-attribute-mapping.md). **Assertion format has specific requirements** Your SAML IdP must include the following claims in the SAML assertion. + A `NameID` claim. Amazon Cognito associates a SAML assertion with the destination user by `NameID`. If `NameID` changes, Amazon Cognito considers the assertion to be for a new user. The attribute that you set to `NameID` in your IdP configuration must have a persistent value. To assign SAML users to a consistent user profile in your user pool, assign your `NameID` claim from an attribute with a value that doesn't change. ``` carlos ``` A `Format` in your IdP `NameID` claim of `urn:oasis:names:tc:SAML:1.1:nameid-format:persistent` indicates that your IdP is passing an unchanging value. Amazon Cognito doesn't require this format declaration, and assigns a format of `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` if your IdP doesn't specify a format of the `NameID` claim. This behavior complies with section 2.2.2 *Complex Type NameIDType*, of [the SAML 2.0 specification](https://groups.oasis-open.org/higherlogic/ws/public/download/35711/sstc-saml-core-errata-2.0-wd-06-diff.pdf/latest). + An `AudienceRestriction` claim with an `Audience` value that sets your user pool SP entity ID as the target of the response. ``` urn:amazon:cognito:sp:us-east-1_EXAMPLE ``` + For SP-initiated single sign-on, a `Response` element with an `InResponseTo` value of the original SAML request ID. ``` ``` **Note** IdP-initiated SAML assertions must *not* contain an `InResponseTo` value. + A `SubjectConfirmationData` element with a `Recipient` value of your user pool `saml2/idpresponse` endpoint and, for SP-initiated SAML, an `InResponseTo` value that matches the original SAML request ID. ``` ``` **SP-initiated sign-in requests** When the [Authorize endpoint](authorization-endpoint.md) redirects your user to your IdP sign-in page, Amazon Cognito includes a *SAML request* in a URL parameter of the `HTTP GET` request. A SAML request contains information about your user pool, including your ACS endpoint. You can optionally apply a cryptographic signature to these requests. **Sign requests and encrypt responses** Every user pool with a SAML provider generates an asymmetric key pair and *signing certificate* for a digital signature that Amazon Cognito assigns to SAML requests. Every external SAML IdP that you configure to support encrypted SAML response causes Amazon Cognito to generate a new key pair and *encryption certificate* for that provider. To view and download the certificates with the public key, choose your IdP in the **Social and external providers** menu in the Amazon Cognito console. To establish trust with SAML requests from your user pool, provide your IdP with a copy of your user pool SAML 2.0 signing certificate. Your IdP might ignore SAML requests that your user pool signed if you don’t configure the IdP to accept signed requests. 1. Amazon Cognito applies a digital signature to SAML requests that your user passes to your IdP. Your user pool signs all single logout (SLO) requests, and you can configure your user pool to sign single sign-on (SSO) requests for any SAML external IdP. When you provide a copy of the certificate, your IdP can verify the integrity of your users' SAML requests. 1. Your SAML IdP can encrypt SAML responses with the encryption certificate. When you configure an IdP with SAML encryption, your IdP must only send encrypted responses. **Encode non-alphanumeric characters** Amazon Cognito doesn't accept 4-byte UTF-8 characters like 😐 or 𠮷 that your IdP passes as an attribute value. You can encode the character to Base64, pass it as text, and then decode it in your app. In the following example, the attribute claim will not be accepted: ``` 😐 ``` In contrast to the preceding example, the following attribute claim will be accepted: ``` 8J+YkA== ``` **Metadata endpoint must have valid transport-layer security** If you see `InvalidParameterException` while creating a SAML IdP with an HTTPS metadata endpoint URL, for example, "Error retrieving metadata from **," make sure that the metadata endpoint has SSL correctly set up and that there is a valid SSL certificate associated with it. For more information about validating certificates, see [What Is An SSL/TLS Certificate?](https://aws.amazon.com/what-is/ssl-certificate/). **Metadata endpoint must be on standard TCP port for HTTP or HTTPS** Amazon Cognito only accepts metadata URLs for SAML providers on the standard TCP ports 80 for HTTP and 443 for HTTPS. As a security best practice, host SAML metadata at a TLS-encrypted URL with the `https://` prefix. Enter metadata URLs in the format *`http://www.example.com/saml2/metadata.xml`* or *`https://www.example.com/saml2/metadata.xml`*. The Amazon Cognito console accepts metadata URLs only with the `https://` prefix. You can also configure IdP metadata with [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) and [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html). **App clients with IdP-initiated SAML can only sign in with SAML** When you activate support for a SAML 2.0 IdP that supports IdP-initiated sign in an app client, you can only add other SAML 2.0 IdPs to that app client. You're prevented from adding the user directory in the user pool *and* all non-SAML external identity providers to an app client configured in this way. **Logout responses must use POST binding** The `/saml2/logout` endpoint accepts `LogoutResponse` as `HTTP POST` requests. User pools don't accept logout responses with `HTTP GET` binding. **Metadata Signing Certificate Rotation** Amazon Cognito caches SAML metadata for up to six hours when you provide metadata with a URL. When performing any metadata signing certificate rotation, configure your metadata source to publish *both* the original and new certificates for at least six hours. When Amazon Cognito refreshes the cache from the metadata URL, it treats each certificate as valid and your SAML IdP can start signing SAML assertions with the new certificate. After this period has elapsed, you can remove the original certificate from the published metadata. ## Case sensitivity of SAML user names When a federated user attempts to sign in, the SAML identity provider (IdP) passes a unique `NameId` to Amazon Cognito in the user's SAML assertion. Amazon Cognito identifies a SAML-federated user by their `NameId` claim. Regardless of the case sensitivity settings of your user pool, Amazon Cognito recognizes a returning federated user from a SAML IdP when they pass their unique and case-sensitive `NameId` claim. If you map an attribute like `email` to `NameId`, and your user changes their email address, they can't sign in to your app. Map `NameId` in your SAML assertions from an IdP attribute that has values that don't change. For example, Carlos has a user profile in your case-insensitive user pool from an Active Directory Federation Services (ADFS) SAML assertion that passed a `NameId` value of `Carlos@example.com`. The next time Carlos attempts to sign in, your ADFS IdP passes a `NameId` value of `carlos@example.com`. Because `NameId` must be an exact case match, the sign-in doesn't succeed. If your users can't log in after their `NameID` changes, delete their user profiles from your user pool. Amazon Cognito will create new user profiles the next time they sign in. **Topics** + [Quick reference for IdP configuration](#cognito-user-pools-saml-idp-reference) + [Things to know about SAML IdPs in Amazon Cognito user pools](cognito-user-pools-saml-idp-things-to-know.md) + [Case sensitivity of SAML user names](#saml-nameid-case-sensitivity) + [Configuring your third-party SAML identity provider](cognito-user-pools-integrating-3rd-party-saml-providers.md) + [Adding and managing SAML identity providers in a user pool](cognito-user-pools-managing-saml-idp.md) + [SAML session initiation in Amazon Cognito user pools](cognito-user-pools-SAML-session-initiation.md) + [Signing out SAML users with single sign-out](cognito-user-pools-saml-idp-sign-out.md) + [SAML signing and encryption](cognito-user-pools-SAML-signing-encryption.md) + [SAML identity provider names and identifiers](cognito-user-pools-managing-saml-idp-naming.md) # Configuring your third-party SAML identity provider When you want to add a SAML identity provider (IdP) to your user pool, you must make some configuration updates in the management interface of your IdP. This section describes how to format the values that you must provide to your IdP. You can also learn about how to retrieve the static or active-URL metadata document that identifies the IdP and its SAML claims to your user pool. To configure third-party SAML 2.0 identity provider (IdP) solutions to work with federation for Amazon Cognito user pools, you must configure your SAML IdP to redirect to the following Assertion Consumer Service (ACS) URL: `https://mydomain.auth.us-east-1.amazoncognito.com/saml2/idpresponse`. If your user pool has an Amazon Cognito domain, you can find your user pool domain path in the **Domain** menu of your user pool in the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). Some SAML IdPs require that you provide the `urn`, also called the audience URI or SP entity ID, in the form `urn:amazon:cognito:sp:us-east-1_EXAMPLE`. You can find your user pool ID under **User pool overview** in the Amazon Cognito console. You must also configure your SAML IdP to provide values for any attributes that you designated as *required attributes* in your user pool. Typically, `email` is a required attribute for user pools, in which case the SAML IdP must provide some form of an `email` claim in their SAML assertion, and you must map the claim to the attribute for that provider. The following configuration information for third-party SAML 2.0 IdP solutions is a good place to start setting up federation with Amazon Cognito user pools. For the most current information, consult your provider's documentation directly. To sign SAML requests, you must configure your IdP to trust requests signed by your user pool signing certificate. To accept encrypted SAML responses, you must configure your IdP to encrypt *all* SAML responses to your user pool. Your provider will have documentation about configuring these features. For an example from Microsoft, see [Configure Microsoft Entra SAML token encryption](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/howto-saml-token-encryption). **Note** Amazon Cognito only requires your identity provider metadata document. Your provider might also offer customized configuration information for SAML 2.0 federation with IAM or AWS IAM Identity Center. To learn how to set up Amazon Cognito integration, look for general directions for retrieving the metadata document and manage the rest of the configuration in your user pool. | Solution | More information | | --- | --- | | Microsoft Entra ID | [Federation Metadata](https://learn.microsoft.com/en-us/entra/identity-platform/federation-metadata) | | Okta | [How to Download the IdP Metadata and SAML Signing Certificates for a SAML App Integration](https://support.okta.com/help/s/article/Location-to-download-Okta-IDP-XML-metadata-for-a-SAML-app-in-the-new-Admin-User-Interface) | | Auth0 | [Configure Auth0 as SAML Identity Provider](https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-identity-provider) | | Ping Identity (PingFederate) | [Exporting SAML metadata from PingFederate](https://docs.pingidentity.com/integrations/contentful/configuring_single_sign-on/pf_contentful_integration_exporting_saml_metadata_from_pf.html) | | JumpCloud | [SAML Configuration Notes](https://jumpcloud.com/support/saml-configuration-notes) | | SecureAuth | [SAML application integration](https://docs.secureauth.com/2104/en/saml-application-integration.html) | # Adding and managing SAML identity providers in a user pool After you configure your identity provider to work with Amazon Cognito, you can add it to your user pools and app clients. The following procedures demonstrate how to create, modify, and delete SAML providers in an Amazon Cognito user pool. ------ #### [ AWS Management Console ] You can use the AWS Management Console to create and delete SAML identity providers (IdPs). Before you create a SAML IdP, you must have the SAML metadata document that you get from the third-party IdP. For instructions on how to get or generate the required SAML metadata document, see [Configuring your third-party SAML identity provider](cognito-user-pools-integrating-3rd-party-saml-providers.md). **To configure a SAML 2.0 IdP in your user pool** 1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials. 1. Choose **User Pools**. 1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html). 1. Choose the **Social and external providers** menu and then select **Add an identity provider**. 1. Choose a **SAML** IdP. 1. Enter a **Provider name**. You can pass this friendly name in an `identity_provider` request parameter to the [Authorize endpoint](authorization-endpoint.md). 1. Enter **Identifiers** separated by commas. An identifier tells Amazon Cognito it should check the email address a user enters when they sign in, and then direct them to the provider that corresponds to their domain. 1. Choose **Add sign-out flow** if you want Amazon Cognito to send signed sign-out requests to your provider when a user logs out. You must configure your SAML 2.0 IdP to send sign-out responses to the `https://mydomain.auth.us-east-1.amazoncognito.com/saml2/logout` endpoint that is created when you configure managed login. The `saml2/logout` endpoint uses POST binding. **Note** If this option is selected and your SAML IdP expects a signed logout request, you must also provide your SAML IdP with the signing certificate from your user pool. The SAML IdP will process the signed logout request and sign out your user from the Amazon Cognito session. 1. Choose your **IdP-initiated SAML sign-in** configuration. As a security best practice, choose **Accept SP-initiated SAML assertions only**. If you have prepared your environment to securely accept unsolicited SAML sign-in sessions, choose **Accept SP-initiated and IdP-initiated SAML assertions**. For more information, see [SAML session initiation in Amazon Cognito user pools](cognito-user-pools-SAML-session-initiation.md). 1. Choose a **Metadata document source**. If your IdP offers SAML metadata at a public URL, you can choose **Metadata document URL** and enter that public URL. Otherwise, choose **Upload metadata document** and select a metadata file you downloaded from your provider earlier. **Note** We recommend that you enter a metadata document URL if your provider has a public endpoint instead of uploading a file. Amazon Cognito automatically refreshes metadata from the metadata URL. Typically, metadata refresh happens every 6 hours or before the metadata expires, whichever is earlier. 1. **Map attributes between your SAML provider and your user pool** to map SAML provider attributes to the user profile in your user pool. Include your user pool required attributes in your attribute map. For example, when you choose **User pool attribute** `email`, enter the SAML attribute name as it appears in the SAML assertion from your IdP. If your IdP offers sample SAML assertions, you can use these sample assertions to help you to find the name. Some IdPs use simple names, such as `email`, while others use names like the following. ``` http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress ``` 1. Choose **Create**. ------ #### [ API/CLI ] Use the following commands to create and manage a SAML identity provider (IdP). **To create an IdP and upload a metadata document** + AWS CLI: `aws cognito-idp create-identity-provider` Example with metadata file: `aws cognito-idp create-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1 --provider-type SAML --provider-details file:///details.json --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` Where `details.json` contains: ``` "ProviderDetails": { "MetadataFile": "", "IDPSignout" : "true", "RequestSigningAlgorithm" : "rsa-sha256", "EncryptedResponses" : "true", "IDPInit" : "true" } ``` **Note** If the ** contains any instances of the character `"`, you must add `\` as an escape character: `\"`. Example with metadata URL: `aws cognito-idp create-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1 --provider-type SAML --provider-details MetadataURL=https://myidp.example.com/sso/saml/metadata --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` + AWS API: [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) **To upload a new metadata document for an IdP** + AWS CLI: `aws cognito-idp update-identity-provider` Example with metadata file: `aws cognito-idp update-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1 --provider-details file:///details.json --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` Where `details.json` contains: ``` "ProviderDetails": { "MetadataFile": "", "IDPSignout" : "true", "RequestSigningAlgorithm" : "rsa-sha256", "EncryptedResponses" : "true", "IDPInit" : "true" } ``` **Note** If the ** contains any instances of the character `"`, you must add `\` as an escape character: `\"`. Example with metadata URL: `aws cognito-idp update-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1 --provider-details MetadataURL=https://myidp.example.com/sso/saml/metadata --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` + AWS API: [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) **To get information about a specific IdP** + AWS CLI: `aws cognito-idp describe-identity-provider` `aws cognito-idp describe-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1` + AWS API: [DescribeIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeIdentityProvider.html) **To list information about all IdPs** + AWS CLI: `aws cognito-idp list-identity-providers` Example: `aws cognito-idp list-identity-providers --user-pool-id us-east-1_EXAMPLE --max-results 3` + AWS API: [ListIdentityProviders](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListIdentityProviders.html) **To delete an IdP** + AWS CLI: `aws cognito-idp delete-identity-provider` `aws cognito-idp delete-identity-provider --user-pool-id us-east-1_EXAMPLE --provider-name=SAML_provider_1` + AWS API: [DeleteIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteIdentityProvider.html) ------ **To set up the SAML IdP to add a user pool as a relying party** + The user pools service provider URN is: `urn:amazon:cognito:sp:us-east-1_EXAMPLE`. Amazon Cognito requires an audience restriction value that matches this URN in the SAML response. Configure your IdP to use the following POST binding endpoint for the IdP-to-SP response message. ``` https://mydomain.auth.us-east-1.amazoncognito.com/saml2/idpresponse ``` + Your SAML IdP must populate `NameID` and any required attributes for your user pool in the SAML assertion. `NameID` is used for uniquely identifying your SAML federated user in the user pool. Your IdP must pass each user’s SAML name ID in a consistent, case-sensitive format. Any variation in the value of a user's name ID creates a new user profile. **To provide a signing certificate to your SAML 2.0 IDP** + To download a copy of the the public key from Amazon Cognito that your IdP can use to validate SAML logout requests, choose the **Social and external providers** menu of your user pool, select your IdP, and under **View signing certificate**, select **Download as .crt**. You can delete any SAML provider you have set up in your user pool with the Amazon Cognito console. **To delete a SAML provider** 1. Sign in to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). 1. In the navigation pane, choose **User Pools**, and choose the user pool you want to edit. 1. Choose the **Social and external providers** menu. 1. Select the radio button next to the SAML IdPs you wish to delete. 1. When you are prompted to **Delete identity provider**, enter the name of the SAML provider to confirm deletion, and then choose **Delete**. # SAML session initiation in Amazon Cognito user pools Amazon Cognito supports service provider-initiated (SP-initiated) single sign-on (SSO) and IdP-initiated SSO. As a best security practice, implement SP-initiated SSO in your user pool. Section 5.1.2 of the [ SAML V2.0 Technical Overview](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html#5.1.2.SP-Initiated%20SSO:%20%20Redirect/POST%20Bindings|outline) describes SP-initiated SSO. Amazon Cognito is the identity provider (IdP) to your app. The app is the service provider (SP) that retrieves tokens for authenticated users. However, when you use a third-party IdP to authenticate users, Amazon Cognito is the SP. When your SAML 2.0 users authenticate with an SP-initiated flow, they must always first make a request to Amazon Cognito and redirect to the IdP for authentication. For some enterprise use cases, access to internal applications starts at a bookmark on a dashboard hosted by the enterprise IdP. When a user selects a bookmark, the IdP generates a SAML response and sends it to the SP to authenticate the user with the application. You can configure a SAML IdP in your user pool to support IdP-initiated SSO. When you support IdP-initiated authentication, Amazon Cognito can't verify that it has solicited the SAML response that it receives because Amazon Cognito doesn't initiate authentication with a SAML request. In SP-initiated SSO, Amazon Cognito sets state parameters that validate a SAML response against the original request. With SP-initiated sign-in you can also guard against cross-site request forgery (CSRF). **Topics** + [Implement SP-initated SAML sign-in](#cognito-user-pools-saml-idp-authentication) + [Implement IdP-initiated SAML sign-in](#cognito-user-pools-SAML-session-initiation-idp-initiation) ## Implement SP-initated SAML sign-in As a best practice, implement service-provider-initiated (SP-initiated) sign-in to your user pool. Amazon Cognito initiates your user's session and redirects them to your IdP. With this method, you have the greatest control over who presents sign-in requests. You can also permit IdP-initiated sign-in under certain conditions. The following process shows how users complete SP-initiated sign in to your user pool through a SAML provider. ![\[Authentication flow diagram of Amazon Cognito SP-initiated SAML sign-in.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-saml-stepbystep.png) 1. Your user enters their email address at a sign-in page. To determine your user’s redirect to their IdP, you can collect their email address in a custom-built application or invoke managed login in web view. You can configure your managed login pages to display a list of IdPs or to prompt for an email address and match it to the identifier of your SAML IdP. To prompt for an email address, edit your managed login branding style and in **Foundation**, locate **Authentication behavior** and under **Provider display**, set **Display style** to **Domain search input**. 1. Your app invokes your user pool redirect endpoint and requests a session with the client ID that corresponds to the app and the IdP ID that corresponds to the user. 1. Amazon Cognito redirects your user to the IdP with a SAML request, [optionally signed](cognito-user-pools-SAML-signing-encryption.md#cognito-user-pools-SAML-signing.title), in an `AuthnRequest` element. 1. The IdP authenticates the user interactively, or with a remembered session in a browser cookie. 1. The IdP redirects your user to your user pool SAML response endpoint with the [optionally-encrypted](cognito-user-pools-SAML-signing-encryption.md#cognito-user-pools-SAML-signing-encryption.title) SAML assertion in their POST payload. **Note** Amazon Cognito cancels sessions that don't receive a response within 5 minutes, and redirects the user to managed login. When your user experiences this outcome, they receive a `Something went wrong` error message. 1. After it verifies the SAML assertion and [maps user attributes](cognito-user-pools-specifying-attribute-mapping.md#cognito-user-pools-specifying-attribute-mapping.title) from the claims in the response, Amazon Cognito internally creates or updates the user's profile in the user pool. Typically, your user pool returns an authorization code to your user's browser session. 1. Your user presents their authorization code to your app, which exchanges the code for JSON web tokens (JWTs). 1. Your app accepts and processes your user's ID token as authentication, generates authorized requests to resources with their access token, and stores their refresh token. When a user authenticates and receives an authorization code grant, the user pool returns ID, access, and refresh tokens. The ID token is a authentication object for OIDC-based identity management. The access token is an authorization object with [OAuth 2.0](https://oauth.net/2/) scopes. The refresh token is an object that generates new ID and access tokens when your user's current tokens have expired. You can configure the duration of users' tokens in your user pool app client. You can also choose the duration of refresh tokens. After a user's refresh token expires, they must sign in again. If they authenticated through a SAML IdP, your users' session duration is set by the expiration of their tokens, not the expiration of their session with their IdP. Your app must store each user's refresh token and renew their session when it expires. Managed login maintains user sessions in a browser cookie that's valid for 1 hour. ## Implement IdP-initiated SAML sign-in When you configure your identity provider for IdP-initiated SAML 2.0 sign-in, you can present SAML assertions to the `saml2/idpresponse` endpoint in your user pool domain without the need to initiate the session at the [Authorize endpoint](authorization-endpoint.md). A user pool with this configuration accepts IdP-initiated SAML assertions from a user pool external identity provider that the requested app client supports. ![\[Authentication flow diagram of Amazon Cognito IdP-initiated SAML sign-in.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-saml-idpinit.png) 1. A user requests SAML sign-in with your application. 1. Your application invokes a browser or redirects the user to the sign-in page for their SAML provider. 1. The IdP authenticates the user interactively, or with a remembered session in a browser cookie. 1. The IdP redirects your user to your application with the SAML assertion, or response, in their POST body. 1. Your application adds the SAML assertion to the POST body of a request to your user pool `saml2/idpresponse` endpoint. 1. Amazon Cognito issues an authorization code to your user. 1. Your user presents their authorization code to your app, which exchanges the code for JSON web tokens (JWTs). 1. Your application accepts and processes your user's ID token as authentication, generates authorized requests to resources with their access token, and stores their refresh token. The following steps describe the overall process to configure and sign in with an IdP-initiated SAML 2.0 provider. 1. Create or designate a user pool and app client. 1. Create a SAML 2.0 IdP in your user pool. 1. Configure your IdP to support IdP initiation. IdP-initiated SAML introduces security considerations that other SSO providers aren’t subject to. Because of this, you can’t add non-SAML IdPs, including the user pool itself, to any app client that uses a SAML provider with IdP-initiated sign-in. 1. Associate your IdP-initiated SAML provider with an app client in your user pool. 1. Direct your user to the sign-in page for your SAML IdP and retrieve a SAML assertion. 1. Direct your user to your user pool `saml2/idpresponse` endpoint with their SAML assertion. 1. Receive JSON web tokens (JWTs). To accept unsolicited SAML assertions in your user pool, you must consider its effect on your app security. Request spoofing and CSRF attempts are likely when you accept IdP-initiated requests. Although your user pool can't verify an IdP-initiated sign-in session, Amazon Cognito validates your request parameters and SAML assertions. Additionally, your SAML assertion must not contain an `InResponseTo` claim and must have been issued within the previous 6 minutes. You must submit requests with IdP-initiated SAML to your `/saml2/idpresponse`. For SP-initiated and managed login authorization requests, you must provide parameters that identify your requested app client, scopes, redirect URI, and other details as query string parameters in `HTTP GET` requests. For IdP-initiated SAML assertions, however, the details of your request must be formatted as a `RelayState` parameter in the body of an `HTTP POST` request. The request body must also contain your SAML assertion as a `SAMLResponse` parameter. The following is an example request and response for an IdP-initiated SAML provider. ``` POST /saml2/idpresponse HTTP/1.1 User-Agent: USER_AGENT Accept: */* Host: example.auth.us-east-1.amazoncognito.com Content-Type: application/x-www-form-urlencoded SAMLResponse=[Base64-encoded SAML assertion]&RelayState=identity_provider%3DMySAMLIdP%26client_id%3D1example23456789%26redirect_uri%3Dhttps%3A%2F%2Fwww.example.com%26response_type%3Dcode%26scope%3Demail%2Bopenid%2Bphone HTTP/1.1 302 Found Date: Wed, 06 Dec 2023 00:15:29 GMT Content-Length: 0 x-amz-cognito-request-id: 8aba6eb5-fb54-4bc6-9368-c3878434f0fb Location: https://www.example.com?code=[Authorization code] ``` ------ #### [ AWS Management Console ] **To configure an IdP for IdP-initiated SAML** 1. Create a [user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html), [app client](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html), and SAML identity provider. 1. Disassociate all social and OIDC identity providers from your app client, if any are associated. 1. Navigate to the **Social and external providers** menu of your user pool. 1. Edit or add a SAML provider. 1. Under **IdP-initiated SAML sign-in**, choose **Accept SP-initiated and and IdP-initiated SAML assertions**. 1. Choose **Save changes**. ------ #### [ API/CLI ] **To configure an IdP for IdP-initiated SAML** Configure IdP-initiated SAML with the `IDPInit` parameter in a [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) or [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) API request. The following is an example `ProviderDetails` of an IdP that supports IdP-initiated SAML. ``` "ProviderDetails": { "MetadataURL" : "https://myidp.example.com/saml/metadata", "IDPSignout" : "true", "RequestSigningAlgorithm" : "rsa-sha256", "EncryptedResponses" : "true", "IDPInit" : "true" } ``` ------ # Signing out SAML users with single sign-out Amazon Cognito supports SAML 2.0 [single logout](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html#5.3.Single%20Logout%20Profile|outline) (SLO. With SLO, your application can sign out users from their SAML identity providers (IdPs) when they sign out from your user pool. This way, when users want to sign in to your application again, they must authenticate with their SAML IdP. Otherwise, they might have IdP or user pool browser cookies in place that pass them through to your application without the requirement that they provide credentials. When you configure your SAML IdP to support **Sign-out flow**, Amazon Cognito redirects your user with a signed SAML logout request to your IdP. Amazon Cognito determines the redirect location from the `SingleLogoutService` URL in your IdP metadata. Amazon Cognito signs the sign-out request with your user pool signing certificate. ![\[Authentication flow diagram of Amazon Cognito SAML sign-out. The user requests sign-out and Amazon Cognito redirects them to their provider with a SAML sign-out request.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-saml-sign-out.png) When you direct a user with a SAML session to your user pool `/logout` endpoint, Amazon Cognito redirects your SAML user with the following request to the SLO endpoint that's specified in the IdP metadata. ``` https://[SingleLogoutService endpoint]? SAMLRequest=[encoded SAML request]& RelayState=[RelayState]& SigAlg=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256& Signature=[User pool RSA signature] ``` Your user then returns to your `saml2/logout` endpoint with a `LogoutResponse` from their IdP. Your IdP must send the `LogoutResponse` in an `HTTP POST` request. Amazon Cognito then redirects them to the redirect destination from their initial sign-out request. Your SAML provider might send a `LogoutResponse` with more than one `AuthnStatement` in it. The `sessionIndex` in the first `AuthnStatement` in a response of this type must match the `sessionIndex` in the SAML response that originally authenticated the user. If the `sessionIndex` is in any other `AuthnStatement`, Amazon Cognito won’t recognize the session and your user won’t be signed out. ------ #### [ AWS Management Console ] **To configure SAML sign-out** 1. Create a [user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html), [app client](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html), and SAML IdP. 1. When you create or edit your SAML identity provider, under **Identity provider information**, check the box with the title **Add sign-out flow**. 1. From the **Social and external providers** menu of your user pool, choose your IdP and locate the **Signing certificate**. 1. Choose **Download as .crt**. 1. Configure your SAML provider to support SAML single logout and request signing, and upload the user pool signing certificate. Your IdP must redirect to `/saml2/logout` in your user pool domain. ------ #### [ API/CLI ] **To configure SAML sign-out** Configure single logout with the `IDPSignout` parameter of a [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) or [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) API request. The following is an example `ProviderDetails` of an IdP that supports SAML single logout. ``` "ProviderDetails": { "MetadataURL" : "https://myidp.example.com/saml/metadata", "IDPSignout" : "true",, "RequestSigningAlgorithm" : "rsa-sha256", "EncryptedResponses" : "true", "IDPInit" : "true" } ``` ------ # SAML signing and encryption SAML 2.0 sign-in is built around the user of an application as a bearer of requests and responses in their authentication flow. You might want to ensure that users aren't reading or modifying these SAML documents in transit. To accomplish this, add SAML signing and encryption to the SAML identity providers (IdPs) in your user pool. With SAML signing, your user pools adds a signature to SAML sign-in and sign-out requests. With your user pool public key, your IdP can verify that it's receiving unmodified SAML requests. Then, when your IdP responds and passes SAML assertions to users' browser sessions, the IdP can encrypt that response so that the user can't inspect their own attributes and entitlements. With SAML signing and encryption, all cryptographic operations during user pool SAML operations must generate signatures and ciphertext with user-pool-provided keys that Amazon Cognito generates. Currently, you can't configure a user pool to sign requests or accept encrypted assertions with an external key. **Note** Your user pool certificates are valid for 10 years. Once per year, Amazon Cognito generates new signing and encryption certificates for your user pool. Amazon Cognito returns the most recent certificate when you request the signing certificate, and signs requests with the most recent signing certificate. Your IdP can encrypt SAML assertions with any user pool encryption certificate that isn’t expired. Your previous certificates continue to be valid for their entire duration and the public key doesn't change between certificates. As a best practice, update the certificate in your provider configuration annually. **Topics** + [Accepting encrypted SAML responses from your IdP](#cognito-user-pools-SAML-encryption) + [Signing SAML requests](#cognito-user-pools-SAML-signing) ## Accepting encrypted SAML responses from your IdP Amazon Cognito and your IdP can establish confidentiality in SAML responses when users sign in and sign out. Amazon Cognito assigns a public-private RSA key pair and a certificate to each external SAML provider that you configure in your user pool. When you enable response encryption for your user pool SAML provider, you must upload your certificate to an IdP that supports encrypted SAML responses. Your user pool connection to your SAML IdP isn’t functional before your IdP begins to encrypt all SAML assertions with the provided key. The following is an overview of the flow of an encrypted SAML sign-in. 1. Your user starts sign-in and chooses their SAML IdP. 1. Your user pool [Authorize endpoint](authorization-endpoint.md) redirects your user to their SAML IdP with a SAML sign-in request. Your user pool can optionally accompany this request with a signature that enables integrity verification by the IdP. When you want to sign SAML requests, you must configure your IdP to accept requests that your user pool has signed with the public key in the signing certificate. 1. The SAML IdP signs in your user and generates a SAML response. The IdP encrypts the response with the public key and redirects your user to your user pool `/saml2/idpresponse` endpoint. The IdP must encrypt the response as defined by the SAML 2.0 specification. For more information, see `Element ` in [Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf). 1. Your user pool decrypts the ciphertext in the SAML response with the private key and signs in your user. **Important** When you enable response encryption for a SAML IdP in your user pool, your IdP must encrypt all responses with a public key that's specific to the provider. Amazon Cognito doesn't accept unencrypted SAML responses from a SAML external IdP that you configure to support encryption. Any external SAML IdP in your user pool can support response encryption, and each IdP receives its own key pair. ------ #### [ AWS Management Console ] **To configure SAML response encryption** 1. Create a [user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html), [app client](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html), and SAML IdP. 1. When you create or edit your SAML identity provider, under **Sign requests and encrypt responses**, check the box with the title **Require encrypted SAML assertions from this provider**. 1. From the **Social and external providers** menu of your user pool, select your SAML IdP and choose **View encryption certificate**. 1. Choose **Download as .crt** and provide the downloaded file to your SAML IdP. Configure your SAML IdP to encrypt SAML responses with the key in the certificate. ------ #### [ API/CLI ] **To configure SAML response encryption** Configure response encryption with the `EncryptedResponses` parameter of a [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) or [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) API request. The following is an example `ProviderDetails` of an IdP that supports request signing. ``` "ProviderDetails": { "MetadataURL" : "https://myidp.example.com/saml/metadata", "IDPSignout" : "true", "RequestSigningAlgorithm" : "rsa-sha256", "EncryptedResponses" : "true", "IDPInit" : "true" } ``` To get the encryption certificate from your user pool, make a [DescribeIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeIdentityProvider.html) API request and retrieve the value of `ActiveEncryptionCertificate` in the response parameter `ProviderDetails`. Save this certificate and provide it to your IdP as the encryption certificate for sign-in requests from your user pool. ------ ## Signing SAML requests The ability to prove the integrity of SAML 2.0 requests to your IdP is a security advantage of Amazon Cognito SP-initiated SAML sign-in. Each user pool with a domain receives a user pool X.509 signing certificate. With the public key in this certificate, user pools apply a cryptographic signature to the *sign-out requests* that your user pool generates when your users select a SAML IdP. You can optionally configure your app client to sign SAML *sign-in requests*. When you sign your SAML requests, your IdP can check that the signature in the XML metadata of your requests matches the public key in the user pool certificate that you provide. ------ #### [ AWS Management Console ] **To configure SAML request signing** 1. Create a [user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html), [app client](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-app-integration.html), and SAML IdP. 1. When you create or edit your SAML identity provider, under **Sign requests and encrypt responses**, check the box with the title **Sign SAML requests to this provider**. 1. From the **Social and external providers** menu of your user pool, choose **View signing certificate**. 1. Choose **Download as .crt** and provide the downloaded file to your SAML IdP. Configure your SAML IdP to verify the signature of incoming SAML requests. ------ #### [ API/CLI ] **To configure SAML request signing** Configure request signing with the `RequestSigningAlgorithm` parameter of a [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) or [UpdateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateIdentityProvider.html) API request. The following is an example `ProviderDetails` of an IdP that supports request signing. ``` "ProviderDetails": { "MetadataURL" : "https://myidp.example.com/saml/metadata", "IDPSignout" : "true", "RequestSigningAlgorithm" : "rsa-sha256", "EncryptedResponses" : "true", "IDPInit" : "true" } ``` ------ # SAML identity provider names and identifiers When you name your SAML identity providers (IdPs) and assign IdP identifiers, you can automate the flow of SP-initiated sign-in and sign-out requests to that provider. For information about string constraints to the provider name, see the `ProviderName` property of [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html#CognitoUserPools-CreateIdentityProvider-request-ProviderName). ![\[Authentication flow diagram of Amazon Cognito SP-initiated SAML sign-in with an IdP identifier and managed login. The user provides an email address to managed login and Amazon Cognito automatically redirects them to their provider.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/scenario-authentication-saml-identifier.png) You can also choose up to 50 identifiers for your SAML providers. An identifier is a friendly name for an IdP in your user pool, and must be unique within the user pool. If your SAML identifiers match your users' email domains, managed login requests each user's email address, evaluates the domain in their email address, and redirects them to the IdP that corresponds to their domain. Because the same organization can own multiple domains, a single IdP can have multiple identifiers. Whether you use or don't use email-domain identifiers, you can use identifiers in a multi-tenant app to redirect users to the correct IdP. When you want to bypass managed login entirely, you can customize the links that you present to users such that they redirect through the [Authorize endpoint](authorization-endpoint.md) directly to their IdP. To sign in your users with an identifier and redirect to their IdP, include the identifier in the format `idp_identifier=myidp.example.com` in the request parameters of their initial authorization request. Another method to pass a user through to your IdP is to populate the parameter `identity_provider` with the name of your IdP in the following URL format. ``` https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? response_type=code& identity_provider=MySAMLIdP& client_id=1example23456789& redirect_uri=https://www.example.com ``` After a user signs in with your SAML IdP, your IdP redirects them with a SAML response in the `HTTP POST` body to your `/saml2/idpresponse` endpoint. Amazon Cognito processes the SAML assertion and, if the claims in the response meet expectations, redirects to your app client callback URL. After your user has completed authentication in this way, they have interacted with webpages for only your IdP and your app. With IdP identifiers in a domain format, managed login requests email addresses at sign-in and then, when the email domain matches an IdP identifier, redirects users to the sign-in page for their IdP. As an example, you build an app that requires sign-in by employees of two different companies. The first company, AnyCompany A, owns `exampleA.com` and `exampleA.co.uk`. The second company, AnyCompany B, owns `exampleB.com`. For this example, you have set up two IdPs, one for each company, as follows: + For IdP A, you define identifiers `exampleA.com` and `exampleA.co.uk`. + For IdP B, you define identifier `exampleB.com`. In your app, invoke managed login for your app client to prompt each user to enter their email address. Amazon Cognito derives the domain from the email address, correlates the domain to an IdP with a domain identifier, and redirects your user to the correct IdP with a request to the [Authorize endpoint](authorization-endpoint.md) that contains an `idp_identifier` request parameter. For example, if a user enters `bob@exampleA.co.uk`, the next page that they interact with is the IdP sign-in page at `https://auth.exampleA.co.uk/sso/saml`. You can also implement the same logic independently. In your app, you can build a custom form that collects user input and correlates it to the correct IdP according to your own logic. You can generate custom portals for each of your app tenants, where each links to the authorize endpoint with the tenant's identifier in the request parameters. To collect an email address and parse the domain in managed login, assign at least one identifier to each SAML IdP that you have assigned to your app client. By default, the managed login sign-in screen displays a button for each of the IdPs that you have assigned to your app client. However, if you have successfully assigned identifiers, your classic hosted UI sign-in page looks like the following image. ![\[An Amazon Cognito managed login sign-in page displaying local user sign-in and a prompt for a federated user to enter an email address.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/cup-saml-identifiers.png) **Note** In the classic hosted UI, the sign-in page for your app client automatically prompts for an email address when you assign identifiers to your IdPs. In the managed login experience, you must enable this behavior in the branding editor. In the **Authentication behavior** settings category, select **Domain search input** under the heading **Provider display**. Domain parsing in managed login requires that you use domains as your IdP identifiers. If you assign an identifier of any type to each of the SAML IdPs for an app client, managed login for that app no longer displays IdP-selection buttons. Add IdP identifiers for SAML when you intend to use email parsing or custom logic to generate redirects. When you want to generate silent redirects and also want your managed login pages to display a list of IdPs, don't assign identifiers and use the `identity_provider` request parameter in your authorization requests. + If you assign only one SAML IdP to your app client, the managed login sign-in page displays a button to sign in with that IdP. + If you assign an identifier to every SAML IdP that you activate for your app client, a user input prompt for an email address appears in the managed login sign-in page. + If you have multiple IdPs and you do not assign an identifier to all of them, the managed login sign-in page displays a button to sign in with each assigned IdP. + If you assigned identifiers to your IdPs and you want your managed login pages to display a selection of IdP buttons, add a new IdP that has no identifier to your app client, or create a new app client. You can also delete an existing IdP and add it again without an identifier. If you create a new IdP, your SAML users will create new user profiles. This duplication of active users might have a billing impact in the month that you change your IdP configuration. For more information about IdP setup, see [Configuring identity providers for your user pool](cognito-user-pools-identity-provider.md).