Things to know about SAML IdPs in Amazon Cognito user pools

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.

The signing certificate in your SAML provider metadata must not be expired when you configure the SAML IdP in your user pool.

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.

Amazon Cognito and your SAML IdP maintain session information with a relayState parameter.

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.

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.

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.

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.

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

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.

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.

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>

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

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.

The /saml2/logout endpoint accepts LogoutResponse as HTTP POST requests. User pools don't accept logout responses with HTTP GET binding.