Self-hosted Cognito sign-in
Install the pre-token Lambda, grant Cognito permissions, alert on a denied revoke, and turn on threat protection, passkeys and factor self-service.
This page applies when your server runs in Cognito mode. That means CH_COGNITO_USER_POOL_ID is set and the user pool is in your AWS account. In OIDC mode there is no pool, and deprovision skips the identity provider.
When you deprovision a member, the server revokes their CodeHerder keys in its database. It then calls Cognito to sign the person out and disable their pool login. If the server cannot make that call, the database part still holds. But the person can still sign in to the pool.
Install the pre-token Lambda
The server reads three claims from the Cognito access token: email, email_verified and identity_provider. A stock Cognito access token carries none of them. Without the Lambda, every sign-in fails with a 401 and the server logs reason=missing_email. A Pre Token Generation trigger adds the claims. To avoid the Lambda, use OIDC mode instead. The server also reads the stock username claim to decide whether a user has a password. The Lambda does not need to add it.
The trigger must add all three claims in one object. A token with email but no identity_provider makes a federated user look native. That user then skips the federated signup gate. The reference function below fails closed. If the user has no email, or the identities attribute does not parse, it adds no claims. The server then rejects the token.
Access-token customisation needs trigger event version V2_0. That version needs the Cognito Essentials or Plus feature plan. Check the current AWS documentation for your plan. Set user_pool_tier to ESSENTIALS or PLUS on the pool.
// Cognito Pre Token Generation trigger, event version V2_0.
// It adds email, email_verified and identity_provider to the ACCESS token.
// The server reads all three. It fails closed: on any doubt it adds nothing,
// so the server rejects the token as missing_email.
export const handler = async (event) => {
try {
const attrs = event?.request?.userAttributes ?? {};
const email = attrs.email;
const provider = identityProvider(attrs.identities);
if (typeof email !== "string" || email === "" || provider === null) {
return event;
}
const claims = {
email,
email_verified: attrs.email_verified === "true" ? "true" : "false",
identity_provider: provider,
};
for (const name of ["name", "given_name", "family_name"]) {
if (typeof attrs[name] === "string" && attrs[name] !== "") {
claims[name] = attrs[name];
}
}
event.response = event.response ?? {};
event.response.claimsAndScopeOverrideDetails = {
...event.response.claimsAndScopeOverrideDetails,
accessTokenGeneration: { claimsToAddOrOverride: claims },
};
} catch {
// Add no claims. Never log the event: it holds the email address.
}
return event;
};
// "COGNITO" for a native user. The first provider name for a federated one.
// null when the attribute does not parse, so the caller adds no claims.
function identityProvider(identities) {
if (identities === undefined || identities === null || identities === "") {
return "COGNITO";
}
let list;
try {
list = JSON.parse(identities);
} catch {
return null;
}
if (!Array.isArray(list)) return null;
if (list.length === 0) return "COGNITO";
const name = list[0]?.providerName;
return typeof name === "string" && name !== "" ? name : null;
}
Package the file as index.mjs in a zip. Use the Node.js 20 or later runtime, with the handler index.handler. Add these resources to the Terraform for your pool. Replace LAMBDA_ROLE_ARN with a role that has only the basic Lambda logging policy.
resource "aws_lambda_function" "pre_token" {
function_name = "codeherder-pre-token"
role = "LAMBDA_ROLE_ARN"
runtime = "nodejs20.x"
handler = "index.handler"
filename = "pre-token.zip"
source_code_hash = filebase64sha256("pre-token.zip")
}
resource "aws_lambda_permission" "pre_token" {
statement_id = "AllowCognitoInvoke"
action = "lambda:InvokeFunction"
function_name = aws_lambda_function.pre_token.function_name
principal = "cognito-idp.amazonaws.com"
source_arn = aws_cognito_user_pool.main.arn
}
resource "aws_cognito_user_pool" "main" {
# ... your existing settings ...
user_pool_tier = "ESSENTIALS"
lambda_config {
pre_token_generation_config {
lambda_arn = aws_lambda_function.pre_token.arn
lambda_version = "V2_0"
}
}
}
To use the console instead, create the function, then open your pool. Go to Extensions, add a Pre token generation trigger, choose the function, and choose trigger event version V2_0.
Check the result. Sign in as a test user and decode the access token payload. The payload must hold email, email_verified and identity_provider. A native user has identity_provider set to COGNITO. Do not paste a real token into a website to decode it. Decode it locally.
Grant the lifecycle permissions
The server calls Cognito with the AWS credentials it finds by default. That is the instance role, or the IAM user whose keys the server holds. Grant that principal four actions, on your pool’s ARN only:
| Action | Used when |
|---|---|
cognito-idp:AdminUserGlobalSignOut |
You deprovision a member |
cognito-idp:AdminDisableUser |
You deprovision a member |
cognito-idp:AdminEnableUser |
You reactivate a member |
cognito-idp:AdminDeleteUser |
An instance operator erases a human |
Use this inline policy. Replace POOL_ARN with the ARN of your user pool. Find it in the Cognito console, or with aws cognito-idp describe-user-pool. Grant the permissions on that one pool only.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"cognito-idp:AdminUserGlobalSignOut",
"cognito-idp:AdminDisableUser",
"cognito-idp:AdminEnableUser",
"cognito-idp:AdminDeleteUser"
],
"Resource": "POOL_ARN"
}
]
}
Check the permissions
Run this command with an identity that can call IAM. Use the ARN of the server’s role or user.
aws iam simulate-principal-policy \
--policy-source-arn SERVER_PRINCIPAL_ARN \
--action-names cognito-idp:AdminUserGlobalSignOut cognito-idp:AdminDisableUser \
cognito-idp:AdminEnableUser cognito-idp:AdminDeleteUser \
--resource-arns POOL_ARN \
--query 'EvaluationResults[].[EvalActionName,EvalDecision]' --output text
Each line must end with allowed. Any other value means the policy is missing or too narrow.
Then run a live check. Deprovision a test member, and read the pool user:
aws cognito-idp admin-get-user --user-pool-id POOL_ID --username COGNITO_SUB
The output must show "Enabled": false. Reactivate the test member afterwards.
Alert on a denied revoke
When IAM denies the revoke, the server writes this warning. The line is logfmt, and the message text is fixed:
level=WARN msg="members: cognito identity revoke denied by IAM policy" member_id=... cognito_access_denied=true error=...
A denied reactivate writes the same line with restore in place of revoke. Alert on the field cognito_access_denied=true. It matches both lines.
To search the journal by hand:
journalctl -u codeherder.service | grep 'cognito_access_denied=true'
To ship the logs to your own storage, see Self-hosted logs.
When the alert fires, fix the policy and run the check above. Then deprovision the member again. The call is safe to repeat. Or disable the user in the pool yourself.
Turn on threat protection
Cognito threat protection has two parts. Compromised-credential detection blocks a sign-in that uses a password found in a known leak. Adaptive authentication scores each sign-in for risk, and can ask for a second factor or block it.
Both need the Cognito Plus feature plan. Plus costs extra for each monthly active user. Check the current price on the AWS Cognito pricing page.
Start in AUDIT mode. Cognito then records its decisions and takes no action. Read the results for a few weeks. Then move to ENFORCED.
Add these blocks to the Terraform for your pool. The block sets advanced_security_mode to AUDIT. Change it to ENFORCED after the review period.
resource "aws_cognito_user_pool" "main" {
# ... your existing settings ...
user_pool_tier = "PLUS"
user_pool_add_ons {
advanced_security_mode = "AUDIT"
}
}
resource "aws_cognito_risk_configuration" "main" {
user_pool_id = aws_cognito_user_pool.main.id
compromised_credentials_risk_configuration {
event_filter = ["SIGN_IN", "PASSWORD_CHANGE", "SIGN_UP"]
actions {
event_action = "BLOCK"
}
}
account_takeover_risk_configuration {
notify_configuration {
source_arn = "SES_IDENTITY_ARN"
from = "no-reply@example.com"
}
actions {
low_action {
event_action = "NO_ACTION"
notify = false
}
medium_action {
event_action = "MFA_IF_CONFIGURED"
notify = true
}
high_action {
event_action = "BLOCK"
notify = true
}
}
}
}
To use the console instead, open your pool in the Amazon Cognito console. Go to Threat protection, choose the Plus plan, and set the mode. Then set the compromised-credential and adaptive actions.
Turn on passkeys
Users can add a passkey on their profile page. The profile page links to the add-a-passkey page of managed login. The profile page also lists the passkeys and removes one. See Let users manage passkeys and the authenticator app. Passkeys need these settings on the pool:
- Feature plan: Essentials or Plus. In Terraform, set
user_pool_tier. The Lite plan has no passkeys. - Managed login: use managed login branding, not the classic hosted UI.
- Sign-in policy: allow
PASSWORDandWEB_AUTHNas first factors. - App clients: add
ALLOW_USER_AUTHtoexplicit_auth_flowson each app client. - Relying party: set the WebAuthn relying party ID to your user pool domain.
- User verification: set it to
required. - Factor configuration: set
FactorConfigurationtoMULTI_FACTOR_WITH_USER_VERIFICATION. A passkey then counts as multi-factor, and the user skips the authenticator-app prompt.
The aws Terraform provider cannot set the factor configuration. See hashicorp/terraform-provider-aws#48388. Set it with the AWS CLI or the console:
aws cognito-idp set-user-pool-mfa-config \
--user-pool-id <pool id> \
--web-authn-configuration RelyingPartyId=<user pool domain>,UserVerification=required,FactorConfiguration=MULTI_FACTOR_WITH_USER_VERIFICATION
Pass the pool’s existing MFA settings in the same call. The call replaces them.
Managed login adds a passkey only after a recent password and authenticator-app sign-in. A user with an older session sees a message and must sign in again. A user who signs in only with Google has no password. The profile page hides these links for that user.
Let users manage passkeys and the authenticator app
Managed login has no page to list or remove a passkey, or to replace the authenticator app. The profile page has these controls. They call the Cognito user APIs from the browser with the user’s own access token. That token needs the aws.cognito.signin.user.admin scope.
-
Allow the scope on the SPA app client. Add
aws.cognito.signin.user.admintoallowed_oauth_scopes. Do not add it to the CLI app client.ch loginreads the plainscopeslist and fails withinvalid_scopeif the CLI client lacks a scope it asks for.allowed_oauth_scopes = ["openid", "email", "profile", "aws.cognito.signin.user.admin"] -
Allow the Cognito origin in the web app CSP. Add
https://cognito-idp.<region>.amazonaws.comtoconnect-src. Without it the browser blocks every call. -
Know the default. The server makes the SPA ask for the scope. If the SPA client does not allow it, sign-in fails with
invalid_scope. SetCH_COGNITO_FACTOR_SELF_SERVICE=falseuntil you allow the scope. The controls then stay hidden. -
Ask users to sign in again. A session that started before the upgrade has no scope. The profile page then says to sign out and sign in again.
The controls show only for a native Cognito user. A user who signs in only with Google, and every generic OIDC deployment, see nothing.
Token lifetimes
The pool’s app client sets the Cognito access and refresh token lifetimes. For the server-side browser session limits, see Self-hosted deployment.
Related guides
- Self-hosted deployment — install and configure the server
- Self-hosted logs — log formats and how to ship them
Last updated