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


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


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.


The OAuth 2.0 grant type.


The app client ID.


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


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


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


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 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: Content-Type: application/x-www-form-urlencoded SAMLResponse=[Base64-encoded SAML assertion]&
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:[Authorization code]