Using IdP-initiated SAML sign-in - Amazon Cognito
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using IdP-initiated SAML sign-in

When you configure your identity provider for IdP-initiated SAML 2.0 sign-in, you can present SAML assertions to the saml2/idpresponse endpoint in your user pool domain without the need to initiate the session at the Authorize endpoint. A user pool with this configuration accepts IdP-initiated SAML assertions from a user pool external identity provider that the requested app client supports. The following steps describe the overall process to configure and sign in with an IdP-initiated SAML 2.0 provider.

  1. Create or designate a user pool and app client.

  2. Create a SAML 2.0 IdP in your user pool.

  3. Configure your IdP to support IdP initiation. IdP-initiated SAML introduces security considerations that other SSO providers aren’t subject to. Because of this, you can’t add non-SAML IdPs, including the user pool itself, to any app client that uses a SAML provider with IdP-initiated sign-in.

  4. Associate your IdP-initiated SAML provider with an app client in your user pool.

  5. Direct your user to the sign-in page for your SAML IdP and retrieve a SAML assertion.

  6. Direct your user to your user pool saml2/idpresponse endpoint with their SAML assertion.

  7. Receive JSON web tokens (JWTs).

To accept unsolicited SAML assertions in your user pool, you must consider its effect on your app security. Request spoofing and CSRF attempts are likely when you accept IdP-initiated requests. Although your user pool can't verify an IdP-initiated sign-in session, Amazon Cognito validates your request parameters and SAML assertions.

Additionally, your SAML assertion must not contain an InResponseTo claim and must have been issued within the previous 6 minutes.

You must submit requests with IdP-initiated SAML to your /saml2/idpresponse. For SP-initiated and hosted UI authorization requests, you must provide parameters that identify your requested app client, scopes, redirect URI, and other details as query string parameters in HTTP GET requests. For IdP-initiated SAML assertions, however, the details of your request must be formatted as a RelayState parameter in the body of an HTTP POST request. The request body must also contain your SAML assertion as a SAMLResponse parameter.

The following is an example request for an IdP-initiated SAML provider.

POST /saml2/idpresponse HTTP/1.1 User-Agent: USER_AGENT Accept: */* Host: example.auth.us-east-1.amazoncognito.com Content-Type: application/x-www-form-urlencoded SAMLResponse=[Base64-encoded SAML assertion]&RelayState=identity_provider%3DMySAMLIdP%26client_id%3D1example23456789%26redirect_uri%3Dhttps%3A%2F%2Fwww.example.com%26response_type%3Dcode%26scope%3Demail%2Bopenid%2Bphone HTTP/1.1 302 Found Date: Wed, 06 Dec 2023 00:15:29 GMT Content-Length: 0 x-amz-cognito-request-id: 8aba6eb5-fb54-4bc6-9368-c3878434f0fb Location: https://www.example.com?code=[Authorization code]
Amazon Web Services Management Console
To configure an IdP for IdP-initiated SAML
  1. Create a user pool, app client, and SAML identity provider.

  2. Disassociate all social and OIDC identity providers from your app client, if any are associated.

  3. Navigate to the Sign-in experience tab of your user pool.

  4. Under Federated identity provider sign-in, edit or add a SAML provider.

  5. Under IdP-initiated SAML sign-in, choose Accept SP-initiated and and IdP-initiated SAML assertions.

  6. Choose Save changes.

API/CLI

To configure an IdP for IdP-initiated SAML

Configure IdP-initiated SAML with the IDPInit parameter in a CreateIdentityProvider or UpdateIdentityProvider API request. The following is an example ProviderDetails of an IdP that supports IdP-initiated SAML.

"ProviderDetails": { "MetadataURL" : "https://myidp.example.com/saml/metadata", "IDPSignout" : "true", "RequestSigningAlgorithm" : "rsa-sha256", "EncryptedResponses" : "true", "IDPInit" : "true" }