This document describes the use of AWS Cognito as an identity provider with Pomerium. It assumes you have already [installed Pomerium](https://www.pomerium.com/docs/get-started/quickstart.md)

While we do our best to keep our documentation up to date, changes to third-party systems are outside our control. Refer to [Amazon Cognito Documentation](https://docs.aws.amazon.com/cognito/index.html) as needed, or [let us know](https://github.com/pomerium/pomerium/issues/new?assignees=\&labels=\&template=bug_report.md) if we need to re-visit this page.

## Setting up AWS Cognito

If you're following this doc you likely already have a Cognito user pool. If not, expand the section below to learn how to create a user pool.

### Create an App Client

1. From the user pool, create an **App Client** under **General settings**. This is where you configure the Pomerium application settings. Choose **Add an App Client**. You can configure the values to match your needs, or use the default settings:

   \[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, enter the following details (replace `{AUTHENTICATE_DOMAIN}` with the actual domain you will use for the [Authenticate Service URL](https://www.pomerium.com/docs/reference/service-urls.md#authenticate-service-url))

   | **Field** | **Description** |
   | --- | --- |
   | Enabled Identity Providers | Choose **Cognito User Pool**, unless you have set up another **Identity Provider** (eg SAML) |
   | Allowed callback URLs | `https://{AUTHENTICATE_DOMAIN}/oauth2/callback` |
   | Allowed sign-out URLs | `https://{AUTHENTICATE_DOMAIN}/.pomerium/signed_out` |
   | 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:

**Config file keys:**

```yaml
idp_provider: 'oidc'
idp_provider_url: 'https://cognito-idp.${AWS-REGION}.amazonaws.com/${USER-POOL-ID}'
idp_client_id: '304a12ktcc5djt9d7enj6dsjkg'
idp_client_secret: '1re5ukkv3dab6up5aefv7rru65lu60oblf04t6cv8u9s0itjbci7'
idp_scopes: 'openid,profile,email'
```

**Environment Variables:**

```bash
IDP_PROVIDER="oidc"
IDP_PROVIDER_URL="https://cognito-idp.${AWS-REGION}.amazonaws.com/${USER-POOL-ID}"
IDP_CLIENT_ID="304a12ktcc5djt9d7enj6dsjkg"
IDP_CLIENT_SECRET="1re5ukkv3dab6up5aefv7rru65lu60oblf04t6cv8u9s0itjbci7"
IDP_SCOPES="openid,profile,email"
```

**Kubernetes ConfigMap:**

```yaml
apiVersion: v1
data:
  config.yaml: |
    # Main configuration flags: https://www.pomerium.com/docs/reference
    authenticate_service_url: https://k8s-auth-prod.example.com # The URL you have set up for the Pomerium Authentication service
    authorize_service_url: https://pomerium-authorize-service.default.svc.cluster.local

    idp_provider: oidc
    idp_provider_url: https://cognito-idp.${AWS-REGION}.amazonaws.com/${USER_POOL_ID}
    idp_client_id: 304a12ktcc5djt9d7enj6dsjkg
    idp_client_secret: "1re5ukkv3dab6up5aefv7rru65lu60oblf04t6cv8u9s0itjbci7"
    idp_scopes: ["openid", "email", "profile"]
kind: ConfigMap
metadata:
  name: pomerium-config
```

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**.

## Getting Groups

Cognito embeds group membership into the access token. To create policies based on group membership, use the `allowed_idp_claims` key. Replace `admins` in the examples below with your group:

**Custom Claim (Open Source):**

### Custom Claim (Open Source)

```yaml
- from: http://from.example.com
  to: http://to.example.com
  allowed_idp_claims:
    cognito:groups:
      - admins
```

**Directory Sync (Enterprise):**

### Directory Sync (Enterprise)

\[Example policy using Cognito groups in Pomerium Enterprise Console]