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)
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 Amazon Web Services Management Console, through the Amazon CLI, or with the Amazon Cognito user pools API. To create your first SAML IdP in the Amazon Web Services Management Console, see Adding and managing SAML identity providers in a user pool.
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.
-
Download SAML metadata from your IdP, or retrieve the URL to your metadata endpoint. See Configuring your third-party SAML identity provider.
-
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.
-
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.-
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 therelayState
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/idpresponseSee 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 attributeemail
. 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.
-
A
NameID
claim. Amazon Cognito associates a SAML assertion with the destination user byNameID
. IfNameID
changes, Amazon Cognito considers the assertion to be for a new user. The attribute that you set toNameID
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>
-
An
AudienceRestriction
claim with anAudience
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> -
For SP-initiated single sign-on, a
Response
element with anInResponseTo
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. -
A
SubjectConfirmationData
element with aRecipient
value of your user poolsaml2/idpresponse
endpoint and, for SP-initiated SAML, anInResponseTo
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.
-
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.
-
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.