AWS Cognito
Use a Cognito user pool and confidential authorization-code app client. An identity pool that issues AWS credentials is a different service. The released named driver discovers the pool's endpoints, validates the provider tokens, and maps selected Cognito claims. It does not automatically renew the Cognito refresh token as an AuthCrunch browser session.
Cognito User Pool
Create or select the pool in your AWS region. Choose sign-in, verification, password/MFA, and recovery policy appropriate to the organization. The screenshots are a preserved 2022 console sequence, not recommendations to disable verification or MFA. Add a user-pool domain for managed login and OAuth endpoints; the pool ID and managed-login domain are different values. See AWS endpoint documentation.
Preserved Cognito pool configuration screens
Cognito Client
Create a confidential web app client with a secret, enable the authorization-code
grant and openid profile email, and register:
https://auth.example.com/auth/oauth2/cognito/authorization-code-callback
Use a separate registered sign-out URL only when deliberately integrating provider
logout. AWS supports client_secret_post, used by this server-side exchange.
See the token endpoint contract.
Store COGNITO_CLIENT_ID, COGNITO_CLIENT_SECRET, COGNITO_USER_POOL_ID, and a
private AUTHCRUNCH_SIGNING_KEY in the server environment. Change region if
the pool is outside us-east-1; never copy IDs or secrets from the old example.
Preserved Cognito client screens
Cognito User
Provision and confirm a test user through your organization's invitation and
verification workflow. Do not bypass a required password change or mark an
email verified merely to reproduce the old screenshots. Put intended application
members in an administrator-managed Cognito group named app-members.
The released Cognito parser supports these ID-token claims:
| Claim | AuthCrunch mapping |
|---|---|
cognito:groups | Group strings become roles |
custom:roles | String split on ` |
cognito:roles | Role strings/ARNs become roles; they do not assume an AWS IAM role |
cognito:username | username |
zoneinfo, then custom:timezone | timezone, with the custom value taking precedence |
The prior guide's claim that custom roles/timezone are absent is outdated.
Malformed types can reject login. Attribute readability controls whether custom
values reach the ID token; granting an end user write permission to an attribute
used for authorization would let them change that permission input. Prefer
administrator-managed groups, and do not emit reserved authp/admin to all users.
See Cognito ID-token claims.
Preserved Cognito user provisioning screens
Cognito group claims authorize the app; IAM role names do not assume a role. The example maps the administrator-managed app-members Cognito group into app/member. The parser also accepts documented Cognito custom-role fields, but an IAM ARN or user-writable attribute must not bypass this group rule. Cognito managed login, portal tokens, and AWS role assumption remain separate behaviors.
Configure AuthCrunch
# caddy-security v1.3.0 / go-authcrunch v1.3.8. Replace auth.example.com.
{
admin off
persist_config off
security {
oauth identity provider cognito {
realm cognito
driver cognito
client_id {env.COGNITO_CLIENT_ID}
client_secret {env.COGNITO_CLIENT_SECRET}
user_pool_id {env.COGNITO_USER_POOL_ID}
region us-east-1
scopes openid profile email
login icon text "Cognito"
}
authentication portal myportal {
enable identity provider cognito
crypto default token lifetime 900
crypto key sign-verify {env.AUTHCRUNCH_SIGNING_KEY}
ui {
links {
"Example app" /app
"My identity" /auth/whoami
}
}
transform user {
regex match role "^(authp/.*|app/member)$"
action drop matched role
}
transform user {
match realm cognito
action add role authp/user
}
transform user {
match realm cognito
match role app-members
action add role app/member
}
}
authorization policy apppolicy {
set auth url https://auth.example.com/auth/
crypto key verify {env.AUTHCRUNCH_SIGNING_KEY}
validate bearer header
allow roles app/member
}
}
}
auth.example.com {
route {
redir /auth /auth/ 308
authenticate /auth/* with myportal
@app path /app /app/*
route @app {
authorize with apppolicy
respond "You reached the protected example app." 200
}
respond "Open /app to begin." 200
}
}
The first transform removes provider-controlled reserved portal roles and direct
app/member, then grants a limited portal role. Only app-members receives
application access. A cognito:roles IAM ARN or a similarly named group must not
satisfy that rule.
User Login
Open /auth/oauth2/cognito, complete Cognito login, and inspect the portal
identity. Verify that a group member reaches /app and a second confirmed user
outside the group is denied. Cognito's managed-login session and AuthCrunch's
access-token lifetime/logout are separate; test them separately.
Preserved Cognito login and identity screens
Verify and troubleshoot
Sign in through /auth/oauth2/cognito, inspect /auth/whoami?format=json, and
record the exact subject and realm without logging access tokens. Confirm that
an intended member reaches /app and another valid identity is denied. A
successful provider login alone does not establish application authorization.
Check callback scheme, hostname, port, mount, and realm literally; inspect provider errors and diagnostic logs. Keep client secrets on the server. These examples are parser-verified against the released bundle; console registration, live provider login, consent, and production TLS require verification in your own organization.
Agentic Prompts
Copy a prompt into your LLM to explore this topic. Each prompt prioritizes upstream repository guidance and code over this page, and asks for version-aware reasoning.
Separate user and identity pools
Help me understand AWS Cognito.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-oauth-providers,
oauth-identity-provider.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/oauth/backend-oauth2-0012-cognito
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Explain the Cognito user-pool confidential code client used for sign-in versus
an identity pool issuing AWS credentials. Trace hosted UI/domain, pool issuer
metadata, callback realm, and AuthCrunch token issuance. Keep AWS resource
credentials outside the portal session model.
Read Cognito claim mappings
Help me understand AWS Cognito.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-oauth-providers,
oauth-identity-provider.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/oauth/backend-oauth2-0012-cognito
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Inspect cognito:groups and supported custom role/profile fields in my
installed parser. Explain malformed types, attribute readability, and
administrator-controlled authorization inputs. Compare a custom user-writable
attribute with a managed membership grant.
Diagnose a pool/client mismatch
Help me understand AWS Cognito.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-oauth-providers,
oauth-identity-provider.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/oauth/backend-oauth2-0012-cognito
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Help me investigate region/pool issuer, hosted-domain setup, secret-enabled
app client, exact callback, scope, confirmed account, and claim shape. Ask for
public identifiers and redacted metadata only. Do not bypass required password
changes to imitate historical screenshots.
Review logout and refresh boundaries
Help me understand AWS Cognito.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-oauth-providers,
oauth-identity-provider.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/oauth/backend-oauth2-0012-cognito
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Explain Cognito upstream logout URL requirements separately from portal logout
and local refresh sessions. Compare Cognito refresh-token availability with
whether AuthCrunch renews it. Check current official Cognito registration
rules before constructing a complete URL.
Test groups and account lifecycle
Help me understand AWS Cognito.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-oauth-providers,
oauth-identity-provider.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/oauth/backend-oauth2-0012-cognito
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Create cases for managed app group member, nonmember, user-editable custom
role, malformed list, missing optional data, and fresh login after group
removal. Include local versus upstream session observations and keep reserved
portal role injection from becoming a grant.
Source Code References
Start with the code search, then follow the parser, runtime, and tests relevant
to this topic. These links target main; use GitHub's branch/tag selector to
compare them with your installed release.
- Search this topic in both repositories — searches topic-specific symbols and paths across both codebases.
- caddy-security: caddyfile_identity_provider_oauth.go — adapts OAuth/OIDC provider settings, scopes, endpoints, and trust options.
- go-authcrunch: pkg/idp/oauth/config.go — validates generic and named-driver defaults and endpoint settings.
- go-authcrunch: pkg/idp/oauth/claim_parser.go — maps supported token claims into the normalized provider identity.
- go-authcrunch: pkg/idp/oauth/jwt.go — checks upstream token signatures, issuer, audience, and transaction trust.
- go-authcrunch: pkg/idp/oauth/claim_parser_test.go — tests supported claim paths and rejected value shapes.