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) such as Microsoft Active
Directory Federation Services (ADFS)
With the built-in hosted web UI, Amazon Cognito provides token handling and management for all authenticated users. This way, your backend systems can standardize on one set of user pool tokens. You can create and manage a SAML IdP in the Amazon Web Services Management Console through the Amazon CLI or with Amazon Cognito API calls. To get started with the console see Adding sign-in through SAML-based identity providers to a user pool with the Amazon Web Services Management Console.

Note
Sign-in through a third party (federation) is available in Amazon Cognito user pools. This feature is independent of federation through Amazon Cognito identity pools (federated identities).
You need to update your SAML IdP and configure your user pool to support the provider. See the documentation for your SAML IdP for information about how to add your user pool as a relying party or application for your SAML 2.0 IdP.
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 single sign-on (SSO) as described in section 5.1.2 of the SAML V2.0 Technical Overview
Things to know about SAML IdPs in Amazon Cognito user pools
-
Amazon Cognito and your SAML IdP maintain session information with a
relayState
parameter.-
Amazon Cognito supports
relayState
values greater than 80 bytes. While SAML specifications state that therelayState
value "Must not exceed 80 bytes in length”, current industry practice often deviates from this behavior. As a consequence, rejectingrelayState
values greater than 80 bytes will break many standard SAML provider integrations. -
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.
-
-
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. You can find values for
<yourDomainPrefix>
and<Region>
for your user pool on the App integration tab of the Amazon Cognito console. See Configuring a user pool domain for more information about user pool domains.
https://
Your user pool domain
/saml2/idpresponse With an Amazon Cognito domain: https://<yourDomainPrefix>
.auth.<region>
.amazoncognito.com/saml2/idpresponse With a custom domain: https://Your custom domain
/saml2/idpresponse-
The Amazon Cognito
saml2/idpresponse
endpoint doesn't accept encrypted SAML 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.
-
-
For some SAML IdPs, you also need to provide 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:
<yourUserPoolID>
You can find the value of
<yourUserPoolID>
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 attributeemail
. For more information about attribute mapping, see Specifying identity provider attribute mappings for your user pool. -
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 and yoursaml2/idpresponse
endpoint. Amazon Cognito doesn't sign SAML requests. -
Amazon Cognito applies a cryptographic signature to logout requests that your user passes to the logout endpoint of your IdP. To establish trust with these logout requests, you can provide your IdP with a copy of your user pool SAML 2.0 signing certificate. Retrieve the signing certificate in the Sign-in experience tab of the Amazon Cognito console.
Topics
- SAML user pool IdP authentication flow
- Choosing SAML identity provider names
- Creating and managing a SAML identity provider for a user pool (Amazon Web Services Management Console)
- Creating and managing a SAML identity provider for a user pool (Amazon CLI and Amazon API)
- Integrating third-party SAML identity providers with Amazon Cognito user pools
- SAML session initiation in Amazon Cognito user pools