Accessing Trusted Websites using Amazon Cognito user pool

Amazon Cognito does not provide single sign on out of the box when accessing multiple websites with the same credentials . In this blog, I will explain how, using the Amazon Cognito hosted UI, users can access multiple websites with their authenticated logins. This will prevent them to sign in multiple times.

Amazon Cognito is a secure and scalable identity and access management service that can be used to manage your user base through Cognito user pools and it integrates with other identity providers. Amazon Cognito lets you add user sign-up, sign-in, and access control to applications quickly and easily. With Cognito, you can provision a hosted authentication UI that you can add to your application to handle sign-up and sign-in workflows. Cognito’s hosted UI is the foundation for other features, such as the ability to sign in directly to your user pool .

You can use your own custom domain for Cognito’s hosted UI. This offers the users a unified login experience, allowing them to stay within your application’s domain and will use the OAuth flow for authentication to access multiple websites.

Accessing Multiple-sites using Amazon Cognito userpool

As shown in the above architecture diagram we will set up a custom domain name for the Cognito and will use Postman to retrieve a OAuth token from the Cognito user pool to test the OAuth flow.

Steps to set up Custom Domain for the Amazon Cognito :

Create a certificate from the AWS Certificate Manager(ACM):

As a prerequisite, you need a certificate for the custom domain. The certificate can be requested from the ACM console.

Select the option Request certificate and select the Request Public Certificate this shows a screen similar below, in the fully Qualified domain name enter your domain name with a wildcard to make sure the certificate applied to any of the subdomain

The status of the certificate will be Pending validation , you need to create the CNAME record in Route 53 with the values similar below in the DNS record , the certificate will be of the status issued

Configure a Amazon Route 53 Record for the Custom Domain Name:

As a prerequisite you need a web domain. Its parent domain must have a valid A record in DNS. If your custom domain is auth.xyz.example.com, Amazon Cognito must be able to resolve xyz.example.com to an IP address. To prevent accidental impact on customer infrastructure, Amazon Cognito doesn’t support the use of top-level domains (TLDs) for custom domains.

From the AWS Console Select the Route 53 , Select the Hosted Zone and pick up your domain name and create record . You can define a simple record pointing to the alias Amazon S3 website endpoint.

Set up the Amazon Congnito UserPool & App Integration:

You can create a userpool from Amazon Cognito console, by selecting the Create User Pool option and select the sign in option as below :

Cognito configuration guides through the steps :

Configure security requirements : To set the password policy , MFA and User Account Recovery

Configure sign-up experience: Self-service sign-up , we will enable the self registration which shows the sign-in page of the hosted UI. Attribute verification and user account confirmation , shows how to verify the account .

Configure message delivery: This has option how user pool sends email message to user

Integrate your app: In the Hosted authentication pages select the Use the Cognito Hosted UI . In the Domain section select the Custom Domain name , in the custom domain name choose fully qualified subdomain, like “auth.<customdomain>.com” and the select the certificate created earlier:

In the Initial App Client provide a name for the App Client, Do not select the Don’t generate a client secret. The call back url is the url where the user user will be redirected once successfully logged-in or Sign-Up at a time.

Once you create this, it takes some time to active the Domain name and it gives an alias target shown below

Create a record in the Route 53 for the Amazon Cloudfront Alias target

App Client Setup:

Select the Cognito User Pool being created and go the App Integration tab and from the App Client List select the App Client and select Cognito User Pool as the Identity Provider, Authorization Code grant selected for the OAuth Type and select the OpenID Connect scopes

We can view the OpenID Config with the url given below :

https://cognito-idp.{region}.amazonaws.com/{userpoolid}/.well-known/openid-configuration

The output of this will be shows as below:

{
"authorization_endpoint":"https://auth.{customdomainname}/oauth2/authorize",
"id_token_signing_alg_values_supported":[
    "RS256"
],
"issuer":"https://cognito-idp.us-east-1.amazonaws.com/{userpoolid}",
"jwks_uri":"https://cognito-idp.us-east-1.amazonaws.com/{userpoolid}/.well-known/jwks.json",
"response_types_supported":[
    "code",
    "token"
],
"scopes_supported":[
    "openid",
    "email",
    "phone",
    "profile"
],
"subject_types_supported":[
    "public"
],
"token_endpoint":"https://auth.{customdomainname}/oauth2/token",
"token_endpoint_auth_methods_supported":["client_secret_basic","client_secret_post"],
"userinfo_endpoint":"https://auth.{customdomainname}/oauth2/userInfo"
}

We will create a new user , you can access the sign-in and sign-up pages by the below url

https://<your_domain>/oauth2/authorize?response_type=code&client_id=<your_app_client_id>&redirect_uri=<your_callback_url>

You need to verify the user , now we will use the Postman to get a new token with the user created in this . You can download the Postman from https://www.postman.com/downloads/ . Once you launch the Postman click on the Authorization option and select the Type to OAuth2.0 . You can configure the values such as callback url , I have used https://localhost for demo purpose , Auth URL & Access Token URL can be found from the OpenID config I have shows above . Fill up the Client ID from the Cognito User Pool App settings we created earlier

Once you select Get New Access Token it will ask to enter the user details , you can fill up the details for the user we created earlier and this will provide a user token as shown below

Once the user is authenticated you can see the token as shown below

The token returned can be decoded at https://jwt.io , this token is used to send to our service to authenticate. An example of payload can be seen below.

{
  "sub": "{uuid}",
  "iss": "https://cognito-idp.{region}.amazonaws.com/{userpoolid}",
  "version": 2,
  "client_id": "{clientid}",
  "origin_jti": "{uuid}",
  "event_id": "7f7b5427-0aee-4d40-a2b1-30b9fd27cb4f",
  "token_use": "access",
  "scope": "openid profile",
  "auth_time": 1688731333,
  "exp": 1688731933,
  "iat": 1688731333,
  "jti": "{uuid}",
  "username": "test1"
}

Conclusion:

Amazon Cognito Hosted UI and OAuth Authorization server save you the complex hassle of of building and maintaining system that do their authentication and user management by themselves and using these we can control the access to other trusted websites .