saml2/idpresponse endpoint - 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).

saml2/idpresponse endpoint

The /saml2/idpresponse receives SAML assertions. In service-provider-initiated (SP-initiated) sign-in, your SAML 2.0 identity provider (IdP) redirects your user to this endpoint with their SAML response. In SP-initiated sign-in, your application doesn't interact with this endpoint. Configure your IdP with the path to your saml2/idpresponse as the assertion consumer service (ACS) URL. For more information about session initiation, see SAML session initiation in Amazon Cognito user pools.

In IdP-initiated sign-in, your users can sign in with your IdP through your own process and submit a SAML assertion in the body of a HTTP POST request over HTTPS. The body of your POST request must be a SAMLResponse parameter and a Relaystate parameter. For more information, see Using IdP-initiated SAML sign-in.

POST /saml2/idpresponse

To use the /saml2/idpresponse endpoint in an IdP-initiated sign-in, generate a POST request with parameters that provide your user pool with information about your user's session.

  • The app client that they want to sign in to.

  • The callback URL that they want to end up at.

  • The OAuth 2.0 scopes that they want to request in your user's access token.

  • The IdP that initiated the sign-in request.

IdP-initiated request body parameters

SAMLResponse

A Base64-encoded SAML assertion from an IdP associated with a valid app client and IdP configuration in your user pool.

RelayState

A RelayState parameter contains the request parameters that you would otherwise pass to the oauth2/authorize endpoint. For detailed information about these parameters, see Authorize endpoint.

response_type

The OAuth 2.0 grant type.

client_id

The app client ID.

redirect_uri

The URL where the authentication server redirects the browser after Amazon Cognito authorizes the user.

identity_provider

The name of the identity provider where you want to redirect your user.

idp_identifier

The identifier of the identity provider where you want to redirect your user.

scope

The OAuth 2.0 scopes that you want your user to request from the authorization server.

Example requests with positive responses

Example – POST request

The following request is for an authorization code grant for a user from IdP MySAMLIdP in app client 1example23456789. The user redirects to https://www.example.com with their authorization code, which can be exchanged for tokens that include an access token with the OAuth 2.0 scopes openid, email, and phone.

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
Example – response

The following is the response to the previous request.

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]