Adding SAML identity providers to a user pool - Amazon Cognito

Adding SAML identity providers to 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), or Shibboleth. You must choose a SAML IdP which supports the SAML 2.0 standard.

With the hosted UI and federation endpoints, 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.


                Authentication overview with SAML sign-in
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.

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.

  2. 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.

  3. Assign the IdP to your app clients. See User pool app clients

Things to know about SAML IdPs in Amazon Cognito user pools

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.

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 or when a user authenticates with SAML 2.0.

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.

  2. 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.

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.us-east-1.amazoncognito.com/saml2/idpresponse With a custom domain: https://auth.example.com/saml2/idpresponse

See Configuring a user pool domain 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.

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 Specifying identity provider attribute mappings for your user pool.

Assertion format has specific requirements

Your SAML IdP must include the following claims in the SAML assertion.

  1. 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.

    <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:persistent"> carlos </saml2:NameID>
  2. An AudienceRestriction claim with an Audience value that sets your user pool SP entity ID as the target of the response.

    <saml:AudienceRestriction> <saml:Audience> urn:amazon:cognito:sp:us-east-1_EXAMPLE </saml:AudienceRestriction>
  3. For SP-initiated single sign-on, a Response element with an InResponseTo value of the original SAML request ID.

    <saml2p:Response Destination="https://mydomain.us-east-1.amazoncognito.com/saml2/idpresponse" ID="id123" InResponseTo="_dd0a3436-bc64-4679-a0c2-cb4454f04184" IssueInstant="Date-time stamp" Version="2.0" xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    Note

    IdP-initiated SAML assertions must not contain an InResponseTo value.

  4. 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.

    <saml2:SubjectConfirmationData InResponseTo="_dd0a3436-bc64-4679-a0c2-cb4454f04184" NotOnOrAfter="Date-time stamp" Recipient="https://mydomain.us-east-1.amazoncognito.com/saml2/idpresponse"/>
SP-initiated sign-in requests

When the Authorize endpoint 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 Sign-in experience tab of 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.

  2. 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:

<saml2:Attribute Name="Name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">😐</saml2:AttributeValue> </saml2:Attribute>

In contrast to the preceding example, the following attribute claim will be accepted:

<saml2:Attribute Name="Name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">8J+YkA==</saml2:AttributeValue> </saml2:Attribute>
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 <metadata endpoint>," 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?.

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.

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.