How do I securely integrate and configure Amazon Cognito with external SAML identity providers?

Resolution

Add a SAML IdP to your user pool

If you don't have an Amazon Cognito user pool, then see Getting started with user pools. After you create your user pool, configure your SAML application on the IdP side. To add a SAML IdP to your Amazon Cognito user pool, see Adding and managing SAML identity providers in a user pool.

Provide the encryption certificate to your SAML IdP to send encrypted SAML assertions to Amazon Cognito

First, download the encryption certificate from your Amazon Cognito console. Then, in your SAML IdP's configuration interface, import the encryption certificate. Refer to your IdP's documentation for instructions on how to import and activate the encryption certificate. For example, see Configure token encryption in the Microsoft Entra admin center on the Microsoft Learn website.

Verify the encrypted SAML assertion flow

Complete the following steps:

1. Open your browser's developer tools, and create an HTTP Archive (HAR) file.
2. Navigate to your Amazon Cognito user pool's managed login page.
3. Select SAML IdP. Amazon Cognito redirects you to the IdP's sign-in page.
4. In the HAR file, retrieve the SAML assertion request that your IdP sent to the saml2/idpresponse endpoint.
5. In your browser, view the SAML assertion response from the HAR file.

Example of a decoded SAML response with an encrypted SAML assertion:

<saml:EncryptedAssertion>
    <xenc:EncryptedData 
        xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" 
        Type="http://www.w3.org/2001/04/xmlenc#Element">
        <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
        <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <xenc:EncryptedKey>
                <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
                <xenc:CipherData>
                    <xenc:CipherValue>
                        <!-- Encrypted key data -->
                        hY7PK8L9eM+2Uw7....[abbreviated]....4nmB2gTfLwqX=
                    </xenc:CipherValue>
                </xenc:CipherData>
            </xenc:EncryptedKey>
        </ds:KeyInfo>
        <xenc:CipherData>
            <xenc:CipherValue>
                <!-- Encrypted assertion data -->
                kB4urcHh7K5HHJ....[abbreviated]....8JpWGpfTj=
            </xenc:CipherValue>
        </xenc:CipherData>
    </xenc:EncryptedData>
</saml:EncryptedAssertion>

Example of a decoded SAML response without encryption:

<saml:Assertion
    ID="ASRT#########"
    Version="2.0"
    IssueInstant="2024-07-10T10:00:00Z">
    
    <saml:Issuer>https://idp.example.com/saml</saml:Issuer>
    
    <saml:Subject>
        <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">
            USER123456789
        </saml:NameID>
        <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml:SubjectConfirmationData
                NotOnOrAfter="2024-07-10T11:00:00Z"
                Recipient="https://app.example.com/saml/acs"/>
        </saml:SubjectConfirmation>
    </saml:Subject>
    
    <saml:Conditions
        NotBefore="2024-07-10T10:00:00Z"
        NotOnOrAfter="2024-07-10T11:00:00Z">
        <saml:AudienceRestriction>
            <saml:Audience>https://app.example.com/saml</saml:Audience>
        </saml:AudienceRestriction>
    </saml:Conditions>
    
    <saml:AuthnStatement
        AuthnInstant="2024-07-10T10:00:00Z"
        SessionNotOnOrAfter="2024-07-10T18:00:00Z"
        SessionIndex="SESSION123456789">
        <saml:AuthnContext>
            <saml:AuthnContextClassRef>
                urn:oasis:names:tc:SAML:2.0:ac:classes:Password
            </saml:AuthnContextClassRef>
        </saml:AuthnContext>
    </saml:AuthnStatement>
    
    <saml:AttributeStatement>
        <saml:Attribute Name="uid" 
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
            <saml:AttributeValue>user123</saml:AttributeValue>
        </saml:Attribute>
        <saml:Attribute Name="email" 
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
            <saml:AttributeValue>user@example.com</saml:AttributeValue>
        </saml:Attribute>
        <saml:Attribute Name="roles" 
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
            <saml:AttributeValue>user</saml:AttributeValue>
            <saml:AttributeValue>admin</saml:AttributeValue>
        </saml:Attribute>
    </saml:AttributeStatement>
</saml:Assertion>

Note: The saml:EncryptedAssertion element in the response confirms that you have an encrypted SAML assertion. Only your IdP can decrypt and read assertion contents with the correct private key. If saml:EncryptedAssertion isn't in the response, then you have an unencrypted SAML assertion that shows user and authentication details in cleartext.

Related information

Using SAML identity providers with a user pool

How to set up Amazon Cognito for federated authentication using Azure AD

Configure SAML assertions for the authentication response