Streamlining Web App Authentication: A Guide to AD FS Federation with Amazon Cognito User Pools

More Info

User authentication and authorization pose significant challenges for web and mobile app development. Issues such as safeguarding user data and passwords, implementing token-based authentication, federating identities from external identity providers (IdPs), managing intricate permissions, and ensuring scalability can be daunting. This post aims to guide you through federating identities from Windows Server Active Directory to authenticate users in your web app using AWS services, primarily focusing on Amazon Cognito.

Amazon Cognito user pools facilitate user sign-up and sign-in for your mobile and web applications through a secure and scalable user directory. You can also federate users from a SAML IdP with Amazon Cognito user pools, linking these users to a user directory and obtaining standard authentication tokens following successful authentication with a SAML IdP.

This article will illustrate how to integrate Amazon Cognito user pools with Microsoft Active Directory Federation Services (AD FS) to acquire JSON Web Tokens (JWTs) for your web app, which can then be utilized for downstream authentication. To showcase the authentication flow, we’ve developed a straightforward REST API using Amazon API Gateway, which retrieves data from an Amazon DynamoDB table through an AWS Lambda function. We will leverage the JWT tokens provided by the user pools to authenticate to the REST API hosted on API Gateway.

One of the advantages of using Amazon Cognito user pools for federating users from a SAML provider is the support for SAML 2.0 post-binding endpoints. This feature eliminates the need for client-side parsing of the SAML assertion response, allowing the user pool to receive the SAML response directly from your IdP via a user agent. The user pool serves as a service provider on behalf of your application, centralizing identity management and reducing the need to integrate with multiple SAML IdPs.

Solution Overview

The authentication flow is depicted in Figure 1 below.

Figure 1: Authentication Flow with Amazon Cognito User Pool

The authentication flow consists of the following steps:

1. The application initiates the sign-up and sign-in process by directing the user to the Cognito user pools’ hosted web UI. For mobile apps, use a web view to display this UI. In this example, a web app hosted on Amazon Simple Storage Service (Amazon S3) and backed by Amazon CloudFront is utilized.
2. The Amazon Cognito user pool identifies the appropriate IdP based on your configuration. For AD FS, this is determined by the metadata file or endpoint URL from your SAML IdP, which may resemble https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml.
3. The user is redirected to the IdP, which in this case is Active Directory.
4. If necessary, the IdP authenticates the user. If the user has an active session, the IdP can skip authentication for a seamless single sign-on experience.
5. The IdP sends the SAML assertion to Amazon Cognito.
6. A user profile is created in the user pool.
7. Upon verifying the SAML assertion and collecting user attributes (claims), Amazon Cognito provides OIDC tokens (ID, access, and refresh tokens) for the authenticated user.
8. Finally, the application sends a GET request to API Gateway, including the JWT token for authorization. If authorized, the request is processed by Lambda to retrieve data from DynamoDB.

Installation and Configuration Walkthrough

To establish the described authentication flow, follow these steps:

Step 1: Install Active Directory and AD FS

You will need to set up Active Directory and AD FS. For instructions on installation using an AWS CloudFormation template, refer to Enabling Federation to AWS Using Windows Active Directory, ADFS, and SAML 2.0. Ensure you have a functioning Active Directory service and AD FS service, with at least one user created in Active Directory. For this walkthrough, we created a user named Sam with the email address sam@corp.example.com.

Step 2: Create an Amazon Cognito User Pool

Sign in to the Amazon Cognito console. If you already have a user pool, select User pools from the navigation pane and create a new one. If not, you’ll see a landing page where you can select Create user pool. Follow the prompts to configure the sign-in experience, security requirements, and message delivery settings. Be sure to create a domain name using a Cognito domain.

Step 3: Configure Active Directory and AD FS

After creating the Amazon Cognito user pool, set it up as a relying party in AD FS. Connect to the Windows Server instance where you installed AD FS via RDP and access the AD FS 2.0 console.

For further insights on this topic, check out this authoritative source. Additionally, for those interested in a valuable resource, consider visiting this link.

By following these steps, you will establish a robust authentication mechanism for your web application.

Location: Amazon IXD – VGT2, 6401 E Howdy Wells Ave, Las Vegas, NV 89115.