Last year, we launched SAML federation support for Amazon Cognito Identity. This feature enables you to get temporary scoped AWS credentials in exchange for a SAML response. Amazon Cognito Identity supports an API-based approach that requires you to parse the SAML response from the SAML IdP (Identity Provider) and call the Amazon Cognito Identity API with a SAML response to get the AWS credentials.

With Amazon Cognito user pools, you can add user sign-up and sign-in to your mobile and web apps using a secure and scalable user directory. Now we are excited to announce that you can federate users from a SAML IdP with Amazon Cognito user pools, map these users to a user directory, and get standard authentication tokens from a user pool after the user authenticates with a SAML IdP. User pools support SAML 2.0 post-binding endpoints. This eliminates the need for client-side parsing of the SAML assertion response and the user pool directly receives the SAML response from your IdP through a user agent.

As part of the SAML federation feature, the user pool acts as a service provider (SP) on behalf of your application. The user pool becomes a single point of identity management for your application, and your application does not need to integrate with multiple SAML IdPs. You can add one or more SAML IdPs by using the Amazon Cognito console, where you can define attribute mapping and get started quickly.

Use the following steps to enable a SAML IdP for your mobile or web app with Amazon Cognito.

1. Set up the SAML IdP in Amazon Cognito User Pools
To set up a SAML IdP in Amazon Cognito User Pools, you need the metadata file or metadata endpoint URL from your SAML IdP. You can refer to your IdP’s documentation to find the metadata. For example, if you use Microsoft Active Directory Federation Service (AD FS), the metadata URL looks like: https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml.

After you have the SAML IdP metadata, do the following:

• Sign in to the Amazon Cognito console, choose Manage your User Pools, and then select Identity providers in the federation section.
• If you don’t have a user pool, create one.
• Select Identity Provider via SAML Federation.
• Provide the metadata URL or upload the metadata file.
• Provide a name. Optionally, provide a list of comma-separated identifiers to create the SAML provider.

If you have a public SAML IdP metadata endpoint, we recommend that you provide the metadata URL. This enables Amazon Cognito to automatically refresh metadata when it is near expiration. Make sure that you have SSL set up correctly for your metadata endpoint if you are using the metadata URL to set up the SAML provider.

2. Enable your App Client to allow federation from the new SAML IdP 

Next, you configure this SAML provider for an available app client in the Amazon Cognito console:

• In the App integration section, select App client settings.
• If you have already created app clients, they are displayed. If you don’t have an app client, create one in the App clients section under General Settings.
• Find the name of the SAML IdP you set up earlier and select the corresponding check box for your app client.
• Provide the Callback URL(s).This is a comma-separated list of URLs for your application, which Amazon Cognito is allowed to redirect to after successful authentication.
• Provide the Sign out URL(s). This is a comma-separated list of URLs for your application, which Amazon Cognito is allowed to redirect to after successful sign out.
• Select Allowed OAuth Flows. If you do not want to expose Amazon Cognito tokens to the user agent, select Authorization code grant flow. If you have a public client, select Implicit grant flow. For more information, see https://tools.ietf.org/html/rfc6749#section-4.1.  For this example, select both.
• Select the allowed scopes for the token, which will be vended to the client. If you want your user to be able to call Amazon Cognito user level APIs (ChangePassword, UpdateUserAttributes, etc.) with the access token, select the ‘aws.cognito.signin.user.admin’scope. If you want to issue an ID token for the user for the given app client, select the ‘openid’ scope. For this example, select all of the scopes.
• Select the Attribute mapping section. These mappings map the claims from the SAML assertion from your SAML IdP to your user pool attributes. Make sure that you create a mapping for all the required attributes for your user pool.

3. Add Amazon Cognito as a relying party in your SAML identity provider

You are done setting up your user pool for your SAML IdP. If you have not created a domain already, create a domain for your user pool by using the Domain name tab in the Amazon Cognito console. Enable your user pool as a relying partyin your SAML IdP. You need the following information:

• The SAML 2.0 post-binding endpoint (a.k.a assertion consumer URL) for your user pool will be : https://<domain_prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse. You can find the domain prefix and region values in the Domain name tab. Please note that any SAML identity providers that you created in a user pool during the public beta before August 10, 2017 have redirect URLs of https://<domain_prefix>.auth.<region>.amazoncognito.com/login/redirect. These identity providers will continue to support the old redirect URL. But for future compatibility, please update the configuration in your SAML identity provider to accept both the old and new redirect URLs.
• The URN for your user pool service provider will be : urn:amazon:cognito:sp:<user_pool_id>. You can find the user pool id in General settings tab.
• Make sure that your SAML IdP populates NameID and any required attributes for your user pool in the SAML assertion. The NameID populated by your SAML IdP uniquely identifies your SAML federated user in the user pool. Use persistent identifier for NameID.

4. Get started with your application

You can get started by using the UI hosted by Amazon Cognito. Open following URL in your web browser:

https://<domain_prefix>.auth.<region>.amazoncognito.com/login?response_type=token&client_id=<app client id>&redirect_uri=<your redirect URI>

Your configured SAML IdP is displayed in this page. Clicking the SAML IdP takes you to the /authorize endpoint. This endpoint redirects you to the IdP. After you authenticate with the IdP, you are redirected back to your application’s callback URL.

5. IdP identifiers support

In common scenarios, your application can be used by multiple organizations. To redirect the user of your app to the SAML IdP of the organization the user belongs to, use IdP identifiers while setting up the SAML IdP in your user pool. Typically, these identifiers are the domain names used in the email addresses of users of the organization. When the users try to sign in with a SAML IdP, you can ask for their email address, extract the domain name, and pass it as idp_identifier to the /authorize endpoint. If the IdP identifier is associated with an IdP, Amazon Cognito automatically redirects the user to the corresponding IdP. The following is an example of an /authorize call with an idp_identifier parameter:

https://<domain_prefix>.auth.us-east-1.amazoncognito.com/authorize?idp_identifier=cognito.com&response_type=token&client_id=<app client id>&redirect_uri=<your redirect URI>

The SAML federation feature in Amazon Cognito User Pools helps you set up and integrate your apps with multiple SAML IdPs. When you are using the SAML federation feature, your app does not need to handle the type of SAML IdP it is interacting with. Amazon Cognito takes care of it on behalf of your application.