# Cognito

This document describes the use of AWS Cognito as an identity provider with Pomerium. It assumes you have already installed Pomerium

# Setting up AWS Cognito

# Create a User Pool

  1. Log in to the AWS Console (opens new window) account. Go to Services on the top menu, and search for Cognito:

    AWS Cognito Services

  2. Once you have selected Cognito, you will be presented with the option of Manage User Pools or Manage Identity Pools. Pick Manage User Pools:

    AWS Cognito User or Identity Pools

  3. The next page shows any User Pools you have already created, or the option to Create a User Pool:

    AWS Cognito Creating User Pool

  4. Give the pool a name, then choose to either Review defaults or Step through settings. It is up to you whether you choose to Review the defaults (and make some customization) or set up every setting individually.

    AWS Cognito Naming User Pool

  5. Assuming you selected Review defaults, you will see the following:

    AWS Cognito Pool Settings

    You can enable Multi-Factor Authentication (MFA), change your Password requirements, Tag the pool, among many other settings.


    If you need to make changes after creating your pool, be aware that some settings will recreate the pool rather than update the existing pool. This will also generate new Client IDs and Client Secrets. An example would be changing How do you want your end users to sign in? in Attributes from Username to Email address or phone number.

# Create an App Client

  1. Once the pool is created, create an App Client under General settings. This is where you configure the Pomerium application settings. Choose Add an App Client:

    AWS Cognito Create App Client

  2. Once the client is created, retrieve the Client ID, and the Client Secret by clicking Show Details.

    AWS Cognito App Client Details

  3. Go to App client settings (in the Side menu under App Integration)

    AWS Cognito Side Menu

    In the settings for Pomerium app, put in the following details

    Field Description
    Enabled Identity Providers Choose Cognito User Pool, unless you have set up another Identity Provider (eg SAML)
    Callback URL(s) https://${authenticate_service_url}/oauth2/callback
    Allowed OAuth Flows Authorization code grant
    Allowed OAuth Scopes Email, OpenID, Profile
  4. IMPORTANT: For OAuth2 to work correctly with AWS Cognito, you must configure a Domain name. This is under App integration in the side menu

    AWS Cognito Domain Name

You can choose whether to use your own Domain Name, or use an AWS-provided one. The AWS-provided domain names are in the format https://${DOMAIN-PREFIX}.auth.${AWS-REGION}.amazoncognito.com

# Pomerium Configuration

Once you have configured AWS Cognito, configure Pomerium to connext to it:

To retrieve the User Pool ID, go to General Settings in the Cognito Side menu within your pool. The Pool ID is just above the Pool ARN.