diff --git a/docs/docs/identity-providers/cognito.md b/docs/docs/identity-providers/cognito.md index e392a5d02..768248874 100644 --- a/docs/docs/identity-providers/cognito.md +++ b/docs/docs/identity-providers/cognito.md @@ -9,69 +9,82 @@ meta: # Cognito -This document describes the use of AWS Cognito as an identity provider with Pomerium. +This document describes the use of AWS Cognito as an identity provider with Pomerium. It assumes you have already [installed Pomerium](/docs/install/readme.md) ## Setting up AWS Cognito -Log in to the [AWS Console](https://console.aws.amazon.com) account. +### Create a User Pool -Go to **Services** on the top menu, and then search for **Cognito** +1. Log in to the [AWS Console](https://console.aws.amazon.com) account. Go to **Services** on the top menu, and search for **Cognito**: -![AWS Cognito Services](./img/cognito-service.png) + ![AWS Cognito Services](./img/cognito/cognito-service.png) -Once you have selected **Cognito**, you will be presented with the option of **Manage User Pools** or **Manage Identity Pools**. Pick **Manage User Pools** +1. 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](./img/cognito-pools.png) + ![AWS Cognito User or Identity Pools](./img/cognito/cognito-pools.png) -You will now be shown any User Pools you have created already, or the option to **Create a User Pool** +1. The next page shows any User Pools you have already created, or the option to **Create a User Pool**: -![AWS Cognito Creating User Pool](./img/cognito-create-pool.png) + ![AWS Cognito Creating User Pool](./img/cognito/cognito-create-pool.png) -Give the pool a name, and then choose to either **Review defaults** or **Step through settings**. It is entirely up to you as to whether you choose to Review the defaults (and make some customization) or to set up every setting individually. +1. 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](./img/cognito-user-pool-name.png) + ![AWS Cognito Naming User Pool](./img/cognito/cognito-user-pool-name.png) -Assuming you have chosen to **Review defaults**, you will be presented with the following: - +1. Assuming you selected **Review defaults**, you will see the following: -![AWS Cognito Pool Settings](./img/cognito-pool-settings.png) + ![AWS Cognito Pool Settings](./img/cognito/cognito-pool-settings.png) -You can enable Multi-Factor Authentication (MFA), change your Password requirements, Tag the pool, among many other 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** + ::: tip + 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**. + ::: -Once you have created the pool, you can create an **App Client**. This is where you will configure the Pomerium application settings. Choose **Add an App Client** +### Create an App Client -![AWS Cognito Create App Client](./img/cognito-app-client-create.png) +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**: -Once the Client is created, you should then be able to retrieve the **Client ID** and the **Client Secret** + ![AWS Cognito Create App Client](./img/cognito/cognito-app-client-create.png) -![AWS Cognito App Client Details](./img/cognito-app-client-details.png) +1. Once the client is created, retrieve the **Client ID**, and the **Client Secret** by clicking **Show Details**. -After this is done, go to **App client settings** (in the Side menu under **App Integration**) + ![AWS Cognito App Client Details](./img/cognito/cognito-app-client-details.png) -![AWS Cognito Side Menu](./img/cognito-side-menu.png) +1. Go to **App client settings** (in the Side menu under **App Integration**) -In the settings for **Pomerium** app, put in the following details + ![AWS Cognito Side Menu](./img/cognito/cognito-side-menu.png) -| **Field** | **Description** | -| -------------------------- | -------------------------------------------------------------------------------------------- | -| Callback URL(s) | https://authenticate.corp.example.com/oauth2/callback | -| Enabled Identity Providers | Choose **Cognito User Pool**, unless you have set up another **Identity Provider** (eg SAML) | -| Allowed OAuth Flows | Authorization code grant | -| Allowed OAuth Scopes | Email, OpenID, Profile | + In the settings for **Pomerium** app, put in the following details -![AWS Cognito App Client Settings](./img/cognito-app-client-settings.png) + | **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 | -**IMPORTANT**: For OAuth2 to work correctly with AWS Cognito, you must configure a **Domain name**. This is under **App integration** in the side menu +1. **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](./img/cognito-domain-name.png) + ![AWS Cognito Domain Name](./img/cognito/cognito-domain-name.png) 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, you can place your settings in the **Pomerium** config. An example is below: - +Once you have configured AWS Cognito, configure Pomerium to connext to it: +:::: tabs +::: tab config.yaml +```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" +``` +::: +::: tab Environment Variables ```bash IDP_PROVIDER="oidc" IDP_PROVIDER_URL="https://cognito-idp.${AWS-REGION}.amazonaws.com/${USER-POOL-ID}" @@ -79,11 +92,8 @@ IDP_CLIENT_ID="304a12ktcc5djt9d7enj6dsjkg" IDP_CLIENT_SECRET="1re5ukkv3dab6up5aefv7rru65lu60oblf04t6cv8u9s0itjbci7" IDP_SCOPES="openid,profile,email" ``` - -To retrieve the **User Pool ID**, go to **General Settings** in the Cognito Side menu within your pool, and you'll see the **Pool ID** (just above the **Pool ARN**) - -An example of using this in a Kubernetes ConfigMap is below: - - +::: +::: tab Kubernetes ConfigMap ```yaml apiVersion: v1 data: @@ -92,7 +102,6 @@ data: 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 @@ -102,3 +111,7 @@ 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**. diff --git a/docs/docs/identity-providers/img/cognito-app-client-create.png b/docs/docs/identity-providers/img/cognito-app-client-create.png deleted file mode 100644 index 52738dd8f..000000000 Binary files a/docs/docs/identity-providers/img/cognito-app-client-create.png and /dev/null differ diff --git a/docs/docs/identity-providers/img/cognito-app-client-settings.png b/docs/docs/identity-providers/img/cognito-app-client-settings.png deleted file mode 100644 index 0f58b7e0c..000000000 Binary files a/docs/docs/identity-providers/img/cognito-app-client-settings.png and /dev/null differ diff --git a/docs/docs/identity-providers/img/cognito/cognito-app-client-create.png b/docs/docs/identity-providers/img/cognito/cognito-app-client-create.png new file mode 100644 index 000000000..259e60a2a Binary files /dev/null and b/docs/docs/identity-providers/img/cognito/cognito-app-client-create.png differ diff --git a/docs/docs/identity-providers/img/cognito-app-client-details.png b/docs/docs/identity-providers/img/cognito/cognito-app-client-details.png similarity index 100% rename from docs/docs/identity-providers/img/cognito-app-client-details.png rename to docs/docs/identity-providers/img/cognito/cognito-app-client-details.png diff --git a/docs/docs/identity-providers/img/cognito-create-pool.png b/docs/docs/identity-providers/img/cognito/cognito-create-pool.png similarity index 100% rename from docs/docs/identity-providers/img/cognito-create-pool.png rename to docs/docs/identity-providers/img/cognito/cognito-create-pool.png diff --git a/docs/docs/identity-providers/img/cognito-domain-name.png b/docs/docs/identity-providers/img/cognito/cognito-domain-name.png similarity index 100% rename from docs/docs/identity-providers/img/cognito-domain-name.png rename to docs/docs/identity-providers/img/cognito/cognito-domain-name.png diff --git a/docs/docs/identity-providers/img/cognito-pool-settings.png b/docs/docs/identity-providers/img/cognito/cognito-pool-settings.png similarity index 100% rename from docs/docs/identity-providers/img/cognito-pool-settings.png rename to docs/docs/identity-providers/img/cognito/cognito-pool-settings.png diff --git a/docs/docs/identity-providers/img/cognito-pools.png b/docs/docs/identity-providers/img/cognito/cognito-pools.png similarity index 100% rename from docs/docs/identity-providers/img/cognito-pools.png rename to docs/docs/identity-providers/img/cognito/cognito-pools.png diff --git a/docs/docs/identity-providers/img/cognito-service.png b/docs/docs/identity-providers/img/cognito/cognito-service.png similarity index 100% rename from docs/docs/identity-providers/img/cognito-service.png rename to docs/docs/identity-providers/img/cognito/cognito-service.png diff --git a/docs/docs/identity-providers/img/cognito-side-menu.png b/docs/docs/identity-providers/img/cognito/cognito-side-menu.png similarity index 100% rename from docs/docs/identity-providers/img/cognito-side-menu.png rename to docs/docs/identity-providers/img/cognito/cognito-side-menu.png diff --git a/docs/docs/identity-providers/img/cognito-user-pool-name.png b/docs/docs/identity-providers/img/cognito/cognito-user-pool-name.png similarity index 100% rename from docs/docs/identity-providers/img/cognito-user-pool-name.png rename to docs/docs/identity-providers/img/cognito/cognito-user-pool-name.png