Using SP-initated SAML sign-in - Amazon Cognito

Using SP-initated SAML sign-in

As a best practice, implement service-provider-initiated (SP-initiated) sign-in to your user pool. Amazon Cognito initiates your user's session and redirects them to your IdP. With this method, you have the greatest control over who presents sign-in requests. You can also permit IdP-initiated sign-in under certain conditions. For more information, see SAML session initiation in Amazon Cognito user pools.

The following process shows how users sign in to your user pool through a SAML provider.

Authentication flow diagram of Amazon Cognito SP-initiated SAML sign-in.

  1. Your user enters their email address at a sign-in page. To determine your user’s redirect to their IdP, you can collect their email address in a custom app or invoke the hosted UI in web view. You can configure your hosted UI to display a list of IdPs or to only prompt for an email address.

  2. Your app invokes your user pool redirect endpoint and requests a session with the client ID that corresponds to the app and the IdP ID that corresponds to the user.

  3. Amazon Cognito redirects your user to the IdP with a SAML request, optionally signed, in an AuthnRequest element.

  4. The IdP authenticates the user interactively, or with a remembered session in a browser cookie.

  5. The IdP redirects your user to your user pool SAML response endpoint with the optionally-encrypted SAML assertion in their POST payload.

    Note

    Amazon Cognito cancels sessions that don't receive a response within 5 minutes, and redirects the user to the hosted UI. When your user experiences this outcome, they receive a Something went wrong error message.

  6. After it verifies the SAML assertion and maps user attributes from the claims in the response, Amazon Cognito internally creates or updates the user's profile in the user pool. Typically, your user pool returns an authorization code to your user's browser session.

  7. Your user presents their authorization code to your app, which exchanges the code for JSON web tokens (JWTs).

  8. Your app accepts and processes your user's ID token as authentication, generates authorized requests to resources with their access token, and stores their refresh token.

When a user authenticates and receives an authorization code grant, the user pool returns ID, access, and refresh tokens. The ID token is a authentication object for OIDC-based identity management. The access token is an authorization object with OAuth 2.0 scopes. The refresh token is an object that generates new ID and access tokens when your user's current tokens have expired. You can configure the duration of users' tokens in your user pool app client.

You can also choose the duration of refresh tokens. After a user's refresh token expires, they must sign in again. If they authenticated through a SAML IdP, your users' session duration is set by the expiration of their tokens, not the expiration of their session with their IdP. Your app must store each user's refresh token and renew their session when it expires. The hosted UI maintains user sessions in a browser cookie that's valid for 1 hour.