WorkOS Docs Homepage
DashboardSign In

AWS Cognito

Learn how to use WorkOS with your existing AWS Cognito applications.

This guide outlines the steps to make WorkOS SSO Connections available to AWS Cognito applications without requiring changes to your existing application code.

The integration works by configuring WorkOS connections as third-party Identity Providers inside a Cognito User Pool which enables users to sign in to a Cognito application leveraging all SSO integrations supported by WorkOS.

The AWS Cognito integration is in feature preview. Reach out to WorkOS support if you want early access.

WorkOS manages the configuration of the Cognito Identity Providers by leveraging AWS role delegation. You will need to create an IAM role in your AWS account that grants permissions to the WorkOS AWS account. This is can be easily accomplished through the AWS Console.

Create AWS IAM role

The external ID will be provided by the WorkOS support team upon request. The AWS account ID should be 611361754156 which is the ID of a dedicated WorkOS AWS account used for Cognito integrations.

You will need to attach the following policy to the role so that the Identity Providers can be managed when the role is assumed by WorkOS.

IAM Policy

Complete the creation of the role and take note of the name you provide as it will be used in the following step.

Once the role has been configured you will need to provide the following details from your AWS account to the WorkOS support team.

  • Account ID
  • Role name
  • User pool ID

Once the WorkOS support team has configured your AWS details, you should see Identity Providers configured in the specified User Pool for every connection configured in WorkOS. Newly added WorkOS connections will automatically be created in the specified User Pool.

Now that the Identity Providers have been configured, they will need to be enabled for the App Client you wish to use the WorkOS Connections with.

From the user pool navigate to App integrationYour App ClientEdit hosted UI settings and select the newly created Identity Providers.

App Client Identity Provider settings

If you do not complete this step you will receive a Login option is not available error from Cognito upon sign in.

Locate the domain of the Cognito User Pool and configure the following redirect URI in the WorkOS Dashboard under ConfigurationSettingsRedirect URIs.

Cognito callback URI

Once an Identity Provider has been created in the Cognito User Pool, you may initiate authentication by passing the idp_identifier query parameter to the OAuth2 Authorize endpoint provided by Cognito using the details from the App Client that was previously configured with the Identity Providers.

You may pass either a WorkOS Organization or Connection ID as the idp_identifier. Passing this query parameter will result in Cognito bypassing it’s standard sign-in page and immediately redirecting the user to the appropriate sign-in page of the upstream identity provider configured in the WorkOS Connection.

Once the user is authenticated they will be redirected to your Cognito App Client redirect URL with the Cognito code query parameter.