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) such as Microsoft Active Directory Federation Services (ADFS), or Shibboleth. You must choose a SAML IdP which supports the SAML 2.0 standard.

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 AWS Management Console through the AWS 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 AWS Management Console.

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

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

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

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

    1. The Amazon Cognito saml2/idpresponse endpoint doesn't accept encrypted SAML assertions.

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

  4. You must provide your IdP with 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:<your user pool ID>

    You can find the value of <yourUserPoolID> under User pool overview in the Amazon Cognito console.

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

  6. Your SAML IdP must include the following claims in the SAML response.

    • 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:<your user pool ID>
</saml:AudienceRestriction>

    • A Response claim with an InResponseTo value of the original SAML request ID.

      <saml2p:Response Destination="https://<your user pool domain>/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">

    • A SubjectConfirmationData claim with a Recipient value of your user pool saml2/idpresponse endpoint and an InResponseTo value that matches the original SAML request ID.

      <saml2:SubjectConfirmationData InResponseTo="_dd0a3436-bc64-4679-a0c2-cb4454f04184" NotOnOrAfter="Date-time stamp" Recipient="https://<your user pool domain>/saml2/idpresponse"/>

  7. 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 your saml2/idpresponse endpoint. Amazon Cognito doesn't sign SAML requests.

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