SAML session initiation in Amazon Cognito user pools
Amazon Cognito supports service provider-initiated (SP-initiated) single sign-on
(SSO) and IdP-initiated SSO. As a best security practice, implement SP-initiated
SSO in your user pool. Section 5.1.2 of the SAML V2.0 Technical Overview
For some enterprise use cases, access to internal applications starts at a bookmark on a dashboard hosted by the enterprise IdP. When a user selects a bookmark, the IdP generates a SAML response and sends it to the SP to authenticate the user with the application.
You can configure a SAML IdP in your user pool to support IdP-initiated SSO. When you support IdP-initiated authentication, Amazon Cognito can't verify that it has solicited the SAML response that it receives because Amazon Cognito doesn't initiate authentication with a SAML request. In SP-initiated SSO, Amazon Cognito sets state parameters that validate a SAML response against the original request. With SP-initiated sign-in you can also guard against cross-site request forgery (CSRF).
For an example of how to build SP-initiated SAML in an environment where you don't want your users to interact with the user pool hosted UI, see Example scenario: bookmark Amazon Cognito apps in an enterprise dashboard.
Using IdP-initiated SAML SSO
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.
-
Create or designate a user pool and app client.
-
Create a SAML 2.0 IdP in your user pool.
-
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.
-
Associate your IdP-initiated SAML provider with an app client in your user pool.
-
Direct your user to the sign-in page for your SAML IdP and retrieve a SAML assertion.
-
Direct your user to your user pool
saml2/idpresponse
endpoint with their SAML assertion. -
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]