AWS Documentation » Amazon Cognito » Developer Guide » Amazon Cognito User Pools » Adding User Pool Sign-in Through a Third Party » Adding SAML Identity Providers for Your User Pool » SAML User Pool IdP Authentication Flow » Creating and Managing a SAML Identity Provider for a User Pool (AWS Management Console)

Creating and Managing a SAML Identity Provider for a User Pool (AWS Management Console)

You can use the AWS Management Console to create and delete SAML identity providers.

Before you create a SAML identity provider, you need the SAML metadata document that you get from the third-party identity provider (IdP). For instructions on how to get or generate the required SAML metadata document, see Integrating Third-Party SAML Identity Providers with Amazon Cognito User Pools.

You need to choose names for your SAML providers. The string format is [\w\s+=.@-]+ and can be up to 40 characters long.

You can also optionally choose identifiers for your SAML providers. An identifier uniquely resolves to an identity provider associated with your user pool. Typically each identifier corresponds to a domain that belongs to the company that the IdP represents. For a multitenant app that can be used by different companies, identifiers can be used to redirect users to the correct IdP. Since there can be multiple domains owned by the same company, you can provide multiple identifiers.

You can associate up to 50 identifiers with each SAML provider. Identifiers must be unique across the identity provider.

For example, suppose that you built an app that can be used by employees of two different companies, A and B. Company A owns domainA.com and domainA.co.uk; Company B owns domainB.com. Suppose further that you set up two IdPs, one for each company:

• For IdP A, you can define identifiers DomainA.com and DomainA.co.uk.

• For IdP B, you can define identifier DomainB.com.

In your application, you can prompt users to enter their email addresses. By deriving the domain from the email address, you can redirect the user to the correct IdP by providing the domain in the IdPIdentifier in the call to the /authorize endpoint. For example, if a user enters [e-mail], the user is redirected to IdP A.

The sign-in page hosted by Amazon Cognito parses the email address automatically to derive the information. It parses the email domain from email and uses it as IdPIdentifier when calls the /authorize endpoint.

• If you have multiple SAML IdPs and you specify an IdPIdentifier value for any one of them, you will see a box to enter an email address on the hosted page.

• If you have multiple IdPs, and you do not specify an IdPIdentifier value for any of them, the hosted page will show a list of IdPs.

If you're building your own UI, you should parse the domain name so that it matches the IdPIdentifiers that are provided during the IdP setup. For more information about IdP setup, see Configuring Identity Providers for Your User Pool.

To create a SAML provider for a user pool

1. Sign in to the Amazon Cognito console. You may be prompted for your AWS credentials.

2. In the navigation pane, choose Manage your User Pools, and select the user pool you want to edit.

3. Choose Identity providers from the Federation console page.

4. Choose SAML to display the SAML dialog.

5. To attach your own custom metadata document, choose Select file. Or, enter a metadata document endpoint URL. The metadata document must be a valid XML file.

   Note

   We recommend that you provide the endpoint URL if it is a public endpoint, rather than uploading a file, because this allows Amazon Cognito to refresh the metadata automatically. Typically metadata refresh happens every 6 hours or before the metadata expires, whichever is earlier.

6. Enter your SAML Provider name and any Identifiers that you want. The provider name is required; the identifiers are optional.

7. Select Enable IdP sign out flow when you want your user to be logged out from a SAML IdP when logging out from Amazon Cognito.

   Enabling this flow sends a signed logout request to the SAML IdP when the LOGOUT Endpoint is called.

   Note

   If this option is selected and your SAML identity provider expects a signed logout request, you will also need to configure the signing certificate provided by Amazon Cognito with your SAML IdP.

   The SAML IdP will process the signed logout request and logout your user from the Amazon Cognito session.

8. Choose Create provider.

Note

If you see InvalidParameterException while creating a SAML identity provider with an HTTPS metadata endpoint URL, for example, "Error retrieving metadata from <metadata endpoint>," make sure that the metadata endpoint has SSL correctly set up and that there is a valid SSL certificate associated with it.

To set up the SAML IdP to add a user pool as a relying party

• The user pools service provider URN is: urn:amazon:cognito:sp:<user_pool_id>. Amazon Cognito issues the AuthnRequest to SAML IdP to issue a SAML assertion with audience restriction to this URN. Your IdP uses the following POST binding endpoint for the IdP-to-SP response message: https://<domain_prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse.

• Make sure your SAML IdP populates NameID and any required attributes for your user pool in the SAML assertion. NameID is used for uniquely identifying your SAML federated user in the user pool. Use persistent SAML Name ID format.

To set up the SAML IdP to add a signing certificate

• To get the certificate containing the public key which will be used by the identity provider to verify the signed logout request, choose Show signing certificate under Active SAML Providers on the SAML dialog under Identity providers on the Federation console page.

To delete a SAML provider

1. Sign in to the Amazon Cognito console.

2. In the navigation pane, choose Manage your User Pools, and choose the user pool you want to edit.

3. Choose Identity providers from the Federation console page.

4. Choose SAML to display the SAML identity providers.

5. Select the check box next to the provider to be deleted.

6. Choose Delete provider.