Docs gap: AWS Cognito worker SSO (OpenID Connect) walkthrough

[cerb]

Question

How do I configure AWS Cognito as an OpenID Connect SSO provider for worker logins to Cerb?

Gap

Cerb already documents OIDC worker SSO for Azure AD, Okta, and Salesforce under /guides/sso/:

• https://cerb.ai/guides/sso/azure-openid/
• https://cerb.ai/guides/sso/okta-openid/
• https://cerb.ai/guides/sso/salesforce-openid/

AWS Cognito is a popular OIDC provider (often used by AWS-shop teams that already have a Cognito user pool for customer apps) but has no equivalent guide. The setup is straightforward once you know the pieces, but the Cognito-side step has a non-obvious gotcha (the allowed callback URL must match Cerb's /sso/<connected-service-uri> exactly, and the Cognito hosted UI caches for several minutes after you change it, which looks like a Cerb-side failure if you don't know to wait).

Closest existing page

/guides/sso/azure-openid/ — same OIDC flow on Cerb's side, different IdP-side configuration steps.

Suggested content

A new page at /guides/sso/aws-cognito-openid/ mirroring the structure of the Azure guide. Below is the procedure verified end-to-end against the 11.2-oauth2-jwt-deps branch (league/oauth2-server 9.x + lcobucci/jwt 5.x), Cerb running on localhost behind an ngrok tunnel, against a Cognito user pool named Workers.

1. Configure AWS Cognito (in AWS Console)

• Create or open a user pool (this guide uses one named Workers).
• Note the Client ID and Client Secret from the app client section.
• Grab the issuer URL from any of the code examples on the app client page (e.g. iOS, Python, JavaScript). It has the form https://cognito-idp.<region>.amazonaws.com/<user-pool-id>.

2. Create the Connected Service in Cerb

• In Cerb, navigate to Search » Connected Services » (+).
• Click the Build tab.
• Fill in:
  • Name: AWS Cognito
  • URI: aws-cognito
  • Type: OpenID Connect Identity Provider
  • Client ID: (from Cognito)
  • Client Secret: (from Cognito)
  • Issuer URL: (the URL grabbed in step 1)
• Click the Run Discovery button. Cerb fetches the IdP's .well-known/openid-configuration document and auto-populates the four remaining URLs (Authorization, Access Token, Userinfo, JWKS).
• Save Changes.

3. Enable Cognito as an SSO provider

• Navigate to Setup » Security » Authentication.
• Under Single Sign-on, check the box next to AWS Cognito.
• Save Changes.

4. Configure the callback URL in Cognito

The Cerb-side callback URL is https://<your-cerb-host>/sso/<connected-service-uri>. With the URI from step 2, that's https://<your-cerb-host>/sso/aws-cognito.

• Back in the AWS Console, open your Cognito user pool's app client.
• Open the Login pages tab.
• Under Allowed callback URLs, add https://<your-cerb-host>/sso/aws-cognito exactly. The trailing path matters — it must match Cerb's URI.
• Save Changes.

5. Test the login flow

• Open Cerb's login page in a new browser session (private window is easiest).
• Click the AWS Cognito button at the top of the login form.
• Cognito's hosted UI loads. Sign in with a Cognito user that maps to a Cerb worker email.
• After successful authentication, you're redirected back to /sso/aws-cognito and logged into Cerb.

Troubleshooting

• "Allowed callback URL" error in the Cognito hosted UI: Make sure step 4's URL exactly matches Cerb's /sso/<uri> (including https vs http, no trailing slash unless Cerb is configured to use one).
• You changed the callback URL but still get the error: Cognito caches the hosted UI config for several minutes after changes. Wait 2–5 minutes before retrying.
• Worker email doesn't exist in Cerb: The OIDC subject must match a Cerb worker's email address. Create the worker first (or auto-provision if your install supports it) before the SSO login.

Notes

Procedure dictated by @jstanden during 2026-05-22 verification of the OAuth2/JWT upgrade branch (11.2-oauth2-jwt-deps) and reformatted for publication. The Cerb side of this flow is identical to the existing Azure/Okta/Salesforce guides — only the IdP-side steps differ.