SAML signing and encryption - Amazon Cognito
Accepting encrypted SAML responses from your IdPSigning SAML requests
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).

SAML signing and encryption

Amazon Cognito supports signed SAML requests and encrypted SAML responses for sign-in and sign-out. All cryptographic operations during user pool SAML operations must generate signatures and ciphertext with user-pool-provided keys that Amazon Cognito generates. Currently, you can't configure a user pool to sign requests or accept encrypted assertions with an external key.

Note

Your user pool certificates are valid for 10 years. Once per year, Amazon Cognito generates new signing and encryption certificates for your user pool. Amazon Cognito returns the most recent certificate when you request the signing certificate, and signs requests with the most recent signing certificate. Your IdP can encrypt SAML assertions with any user pool encryption certificate that isn’t expired. Your previous certificates continue to be valid for their entire duration. As a best practice, update the certificate in your provider configuration annually.

Accepting encrypted SAML responses from your IdP

Amazon Cognito and your IdP can establish confidentiality in SAML responses when users sign in and sign out. Amazon Cognito assigns a public-private RSA key pair and a certificate to each external SAML provider that you configure in your user pool. When you enable response encryption for your user pool SAML provider, you must upload your certificate to an IdP that supports encrypted SAML responses. Your user pool connection to your SAML IdP isn’t functional before your IdP begins to encrypt all SAML assertions with the provided key.

The following is an overview of the flow of an encrypted SAML sign-in.

  1. Your user starts sign-in and chooses their SAML IdP.

  2. Your user pool Authorize endpoint redirects your user to their SAML IdP with a SAML sign-in request. Your user pool can optionally accompany this request with a signature that enables integrity verification by the IdP. When you want to sign SAML requests, you must configure your IdP to accept requests that your user pool has signed with the public key in the signing certificate.

  3. The SAML IdP signs in your user and generates a SAML response. The IdP encrypts the response with the public key and redirects your user to your user pool /saml2/idpresponse endpoint. The IdP must encrypt the response as defined by the SAML 2.0 specification. For more information, see Element <EncryptedAssertion> in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

  4. Your user pool decrypts the ciphertext in the SAML response with the private key and signs in your user.

Important

When you enable response encryption for a SAML IdP in your user pool, your IdP must encrypt all responses with a public key that's specific to the provider. Amazon Cognito doesn't accept unencrypted SAML responses from a SAML external IdP that you configure to support encryption.

Any external SAML IdP in your user pool can support response encryption, and each IdP receives its own key pair.

Amazon Web Services Management Console
To configure SAML response encryption

  1. Create a user pool, app client, and SAML IdP.

  2. When you create or edit your SAML identity provider, under Sign requests and encrypt responses, check the box with the title Require encrypted SAML assertions from this provider.

  3. From the Sign-in experience tab of your user pool, under Federated identity provider sign-in, select your SAML IdP and choose View encryption certificate.

  4. Choose Download as .crt and provide the downloaded file to your SAML IdP. Configure your SAML IdP to encrypt SAML responses with the key in the certificate.

API/CLI

To configure SAML response encryption

Configure response encryption with the EncryptedResponses parameter of a CreateIdentityProvider or UpdateIdentityProvider API request. The following is an example ProviderDetails of an IdP that supports request signing.

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

Signing SAML requests

The ability to to prove the integrity of SAML 2.0 requests to your IdP is a security advantage of Amazon Cognito SP-initiated SAML sign-in. Each user pool with a domain receives a user pool X.509 signing certificate. With the public key in this certificate, user pools apply a cryptographic signature to the sign-out requests that your user pool generates when your users select a SAML IdP. You can optionally configure your app client to sign SAML sign-in requests. When you sign your SAML requests, your IdP can check that the signature in the XML metadata of your requests matches the public key in the user pool certificate that you provide.

Amazon Web Services Management Console
To configure SAML request signing

  1. Create a user pool, app client, and SAML IdP.

  2. When you create or edit your SAML identity provider, under Sign requests and encrypt responses, check the box with the title Sign SAML requests to this provider.

  3. From the Sign-in experience tab of your user pool, under Federated identity provider sign-in, choose View signing certificate.

  4. Choose Download as .crt and provide the downloaded file to your SAML IdP. Configure your SAML IdP to verify the signature of incoming SAML requests.

API/CLI

To configure SAML request signing

Configure request signing with the RequestSigningAlgorithm parameter of a CreateIdentityProvider or UpdateIdentityProvider API request. The following is an example ProviderDetails of an IdP that supports request signing.

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