Setting AWS Cognito on Diffgram

Guide for setting AWS Cognito as an OAuth2 Identity Provider on Diffgram

In this guide you will learn how to setup an integration with Cognito on your Diffgram installation, this will allow you to federate the identity checks to Cognito while to protect access to Diffgram's resources.

Pre-Requisites

1. A working installation of Diffgram (either with docker or kubernetes)
2. An AWS Account with access to Cognito Service with an existing user pool to integrate.

1. Configuring Diffgram App in Cognito User Pool

The first step is to create a new Application configuration inside the user pool you want to user for the identity checks.

Go to your Cognito user pool > app integration tab > create app client:

1. Set your client as Public client. Optionally you can set as private and provider the secret key to Diffgram at a later step.
2. Set your app client name.
3. Make sure to have ALLOW_USER_PASSWORD_AUTH ON YOUR Authentication flows. You can add more flows if you desire.

Now go to the Hosted UI Settings Section:

1. On the Allowed Callback URLs add <YOUR_DIFFGRAM_URL_BASE>user/oauth2-login/
2. On the Allowed sign-out URLs add <YOUR_DIFFGRAM_URL_BASE>user/login/
3. Make sure Authorization code grant is selected on the OAuth2.0 grant types selector.
4. Add any extra custom scopes you desire, the only required scope is the email and OpenID

Hit Create App Client, and take note of your App Client ID

2. Prepare Diffgram Env Variables

On your Diffgram Installation Make Sure you have the following env variables set:

Shell

USE_OAUTH2 = "True"
OAUTH2_PROVIDER_NAME = "cognito"
OAUTH2_PROVIDER_HOST = "https://YOUR_COGNITO_API_URL"
OAUTH2_PROVIDER_CLIENT_ID = "YOUR APP CLIENT ID"
OAUTH2_PROVIDER_CLIENT_SECRET = "YOUR APP CLIENT SECRET (OPTIONAL)"
COGNITO_LOGIN_URL = "THE HOSTED UI URL FOR YOUR LOGIN"

All of these parameters are required. If you're using docker compose edit the .env file to set these. Or if you're using kubernetes edit the values.yaml in the helm chart inside the diffgramSettings section.

3. Cognito Troubleshooting

Headers too big 502 error (Kubernetes/ Ingress NGINX)

Sometime when adding new information to the user session, the header can grow too big. Nginx has some hard limits and might start throwing 502 responses. If you're getting this error be sure to follow this helpful post to solve it: https://andrewlock.net/fixing-nginx-upstream-sent-too-big-header-error-when-running-an-ingress-controller-in-kubernetes/#:~:text=This%20was%20due%20to%20the,additional%20arg%20in%20your%20Deployment%20.