AWS Cognito integrates with a corporate identity provider such as Active Directory (AD) using SAML. In the last post, I explored the sign-up process that creates a user in the Cognito User Pool. In this post, I will demonstrate user creation and authentication via SAML 2.0. Authentication of users by social or corporate identity providers is more common for products delivered natively from AWS.

Overview of SAML

SAML enables shared credentials in applications irrespective of their location within or outside the corporate perimeter. For example, an organization may have Exchange and AD servers within its internal network. When an employee logs into Exchange, they are authenticated against the AD server credentials. The organization can use SAML to let the employee use the same credentials to access another service that accepts the AD as an Identity Provider (IdP). With this flow, the organization can achieve Single Sign-on (SSO) for its users.

The redirect-relay steps (#4, #5) can be replaced with a POST request directly to the SP.

Auth0 as Identity Provider

Auth0 provides authentication solutions for different use cases. In our case, I set up Auth0 as the IdP.

From the Auth0 dashboard, I created a user in the User Management section. I need Family Name and Given Name fields in my User Pool setup to create a new user. I added them as user metadata.

{
  "family_name": "Wick", 
  "given_name": "John"
}

Next, I enabled the SAML 2 add-on in the Auth0 application. In the SAML 2 add-on details, I set the callback URL to https://<domain-name>.auth.<region>.amazoncognito.com/saml2/idpresponse. In the same detail card, I set the settings as follows (mind the placeholders).

{
  "audience": "urn:amazon:cognito:sp:<User Pool Code>",
  "destination": "https://<domain>.auth.<region>.amazoncognito.com/saml2/idpresponse",
  "mappings": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  },
  "createUpnClaim": false,
  "passthroughClaimsWithNoMapping": false,
  "mapUnknownClaimsAsIs": false,
  "mapIdentities": false,
  "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "nameIdentifierProbes": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  ]
}

The last step is to add the user_metadata fields to the SAML assertion. I used the following Auth0 rule to set the fields in the SAML mapping object.

function mapSamlAttributes(user, context, callback) {
  context.samlConfiguration.mappings = {
  	"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname": "user_metadata.family_name",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname": "user_metadata.given_name",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "email"
  };

  callback(null, user, context);
}

The last step was to copy the SAML Metadata URL from the Auth0 application details (Advanced section). I needed this URL later to configure Cognito as an SP.

Cognito as Service Provider

To set up Cognito as an SP, I enabled SAML as an IdP in the Federation section of the User Pool. Then, I proceeded to add a provider with a name and the SAML Metadata URL copied from the last step of setting up Auth0 as an Identity Provider.

Next, I mapped the attributes such as configured in the Auth0 rule. After this configuration was complete, the IdP was available in the App client settings. Finally, I enabled this new IdP in the Enabled Identity Providers section.

Authentication Flow

On navigating to the Hosted UI sign-in page, the new Identity Provider was available as an additional authentication method. The link opens the Auth0 authentication dialog. Cognito added the user to the User Pool on successful authentication, and the client application received the JWT tokens as usual.

In this entire process, there was no change to the authentication success handler. The means, regardless of the authentication method, the client application will receive the same JWT tokens. This consistency paves the way for a consistent authorization mechanism, keeps the authentication out of application code, and re-uses the same handler for any supported authentication method.

Authorization Flow

Once a user is authenticated through the SAML approach or directly against the User Pool, they can access AWS resources using identity federation or directly with the received tokens. I will explore these use cases in the following posts.