Repository navigation
Runbooks Users
People and admins: how the first admin comes to exist, how invitations work, and the command-line recipe behind the Users page. Index: Runbooks.
config.firstAdmin makes the deploy itself bootstrap the one account nothing
else can (every later user is invited from the app):
firstAdmin: { email: "you@example.com" },A Custom::FirstAdmin resource in CredsStack (handler:
lambdacode/firstadmin/handler.ts) runs on deploy and is idempotent against
the live pool:
-
No such user → created in the
adminsgroup + the normal invite email (temporary password / set-password link, same template as UI invites). -
Invite still unclaimed → re-sent with a fresh temp password whenever the
resource updates. The resource only runs when its properties change, so to
force a re-send after the 7-day expiry, bump
firstAdmin.resend(any number) and redeploy — or use the UI/CLI resend if another admin exists. -
User already confirmed (this deployment:
admin@example.compredates the feature) → left untouched; onlyadminsmembership is kept. -
Removing the block never deletes the user — the resource's Delete is a
no-op by design, and its IAM role cannot
AdminDeleteUserat all. But don't read that as "the stack can't lose users": the user pool itself is RETAIN'd only whenprod: true. Withprod: false, destroying CredsStack (or a rollback that replaces the pool) deletes the ENTIRE pool — every user, passkey, and TOTP enrollment, first admin included. The issuer's KMS signing keys follow the same prod-only RETAIN rule.
Changing firstAdmin.email bootstraps the new address the same way and
leaves the old account alone (retire it from the Users page). The deploy
prints the address as the FirstAdminEmail output. The resource lowercases
the email before creating the user, so keep the config value lowercase to
match the account it makes.
With the email block set, the invite goes out through SES as part of the
CredsStack deploy — and a fresh account's SES sandbox delivers only to
verified recipients, so the very first invite is exactly the mail the sandbox
eats. Pick one BEFORE deploy #1:
- get SES production access first (see "Email deliverability" below), or
- verify the
firstAdmin.emailaddress as an SES identity (console → Identities → Create identity → Email address; recipient clicks the confirmation link), or - omit
emailfor deploy #1 — Cognito's default sender delivers to anyone (~50/day budget) — and add the block on a later deploy.
A failed send no longer rolls the deploy back: the handler falls back to
creating the user with MessageAction: SUPPRESS, and the
FirstAdminInviteSent output says which path ran — sent, or suppressed
meaning the account exists but no invite went out (resend from the Users
page once email works, or bump firstAdmin.resend and redeploy).
Timing: on a cold first deploy the invite can land minutes before the web domain is live — CloudFront takes 15-30 min to go global. The link is valid 7 days; just wait for the site.
Both end the person's sessions at once (AdminUserGlobalSignOut), and every admin route re-checks the
admins group against the directory once a minute per API container — so a removed admin cannot keep
using an already-issued token for the rest of its hour. Deleting also revokes every grant, closes the
person's open requests and ends the dev shares they own; the last remaining admin cannot be removed.
The admin UI's Create user sends a Cognito invite whose look depends on
config.web:
-
Custom domain set: the email is a "Set your password" link
(
/login#inv={username}:{####}) — the login page consumes the fragment, signs in with the embedded temp password, and lands the invitee straight on the set-password screen. The temp password is never shown. Desktop users continue from that page: Open in the desktop app under the card hands the invitation to the app (desktop/README.md "Deep links"). - No custom domain: plain text with the temporary password (the app's CloudFront URL can't be referenced from CredsStack without a stack cycle).
Both templates live on the user pool (CredsStack userInvitation);
Send invite email regenerates the temp password and reuses the same
template. Links/passwords expire after 7 days (pool policy) — after that,
send the invite email again. The API builds the same #inv= link itself
(APP_URL, from config.web; path-only without one) and returns it from
Create user only when the email is skipped (sendEmail: false →
MessageAction: SUPPRESS, still a temp password), for the admin to pass on.
Copy sign-up link on a pending user's panel sets a fresh temporary
password (AdminSetUserPassword, Permanent: false) — it replaces the
emailed one, and a later resend replaces it in turn.
After any deploy that touches pool sign-in config or the invite flow,
run a live invite check (unit tests mock AWS and can't see Cognito
reinterpret an unchanged call): invite a mailbox you own from the admin
UI, confirm the invited pill appears, the email arrives with a working
link (or temp password), and first sign-in reaches the set-password
screen. Then delete the test user. createUser must always pass a TemporaryPassword:
in a pool with passwordless factors enabled, omitting it births the user
CONFIRMED with no password, no invite state, and a password-less invite
email (this silently broke invites between 2026-07-20 and 2026-08-13).
POOL=<UserPoolId>
aws cognito-idp admin-create-user --user-pool-id $POOL --username tester@example.com --message-action SUPPRESS
aws cognito-idp admin-set-user-password --user-pool-id $POOL --username tester@example.com --password 'Test1234!' --permanent
# admin only:
aws cognito-idp admin-add-user-to-group --user-pool-id $POOL --username tester@example.com --group-name adminsGet a token, then call the API:
JWT=$(aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --client-id <UserPoolClientId> \
--auth-parameters USERNAME=tester@example.com,PASSWORD='Test1234!' \
--query 'AuthenticationResult.IdToken' --output text)
# admin: register an account + a role, then list the catalog
# (the admin UI's Accounts page now does all of this too — curl is optional)
curl -s -X POST "<ApiUrl>admin/accounts" -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' \
-d '{"accountNumber":"<ACCT>","name":"sandbox"}'
curl -s -X POST "<ApiUrl>admin/accounts/<ACCT>/roles" -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' \
-d '{"roleName":"SandboxReadOnly","roleArn":"arn:aws:iam::<ACCT>:role/SandboxReadOnly"}'
# user: vend credentials (needs an Access row for this user → role, see below)
curl -s -X POST "<ApiUrl>credentials" -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' \
-d '{"accountNumber":"<ACCT>","role":"SandboxReadOnly"}'Grant a user (their Cognito sub, from admin-get-user) permission to assume a
role via the admin API:
curl -s -X PUT "<ApiUrl>admin/accounts/<ACCT>/roles/SandboxReadOnly/grants/<sub>" \
-H "Authorization: Bearer $JWT"Check whether the user has an authenticator (TOTP) enrolled before anything else. Cognito offers a user with MFA configured the password alone in choice-based sign-in — passkey and email code are withheld for that user on every device, not just the one they enrolled on. This is Cognito's rule, not the portal's; the Authenticator dialog says so when they turn it on.
aws cognito-idp admin-get-user --user-pool-id <pool-id> --username <email> --query 'UserMFASettingList'["SOFTWARE_TOKEN_MFA"] means enrolled. The user picks one lane: keep the authenticator and sign in with password + code, or turn it off under Authenticator (MFA) in the profile menu (or an admin uses Reset MFA on the user panel) and the other methods come back on the next sign-in. If nothing is enrolled, read on.
The sign-in page lists what Cognito offers for that attempt. With loginMethods.threatProtection on, Cognito scores every attempt; on an attempt it applies an MFA action to, choice-based sign-in offers only the password — passkey and email code disappear for that attempt, even for a user who has both. The package allows Medium risk (a new network) and applies "MFA if configured" only at High, so this is rare; when a user reports it:
-
Read the user's recent attempts and their scores (times are UTC):
aws cognito-idp admin-list-user-auth-events --user-pool-id <pool-id> --username <email> --max-results 10 \ --query 'AuthEvents[].{t:CreationDate,risk:EventRisk.RiskLevel,ip:EventContextData.IpAddress,id:EventId}' --output table
-
If the attempts are the user's own, mark them valid — Cognito lowers the risk it assigns to later sessions with the same characteristics (it is not instant):
aws cognito-idp admin-update-auth-event-feedback --user-pool-id <pool-id> --username <email> \ --event-id <event-id> --feedback-value Valid
The same is available in the Cognito console under the user's event history ("Set as valid").
-
The user can always sign in by password meanwhile; the other methods return once the score drops. A user with TOTP enrolled is asked for it on a High-risk attempt.
One-time per identity provider, per deployment. After this, staff sign in with their corporate account, portal access ends when that account is disabled, and the identifier the customer's other systems key on (an employee id — Entra's oid claim, say) reads on the user record, in the portal's own token and on every audit row. Configuration reference: loginMethods.federation[]. Entra ID is the worked example below; any OIDC provider works the same way.
Nothing is replaced. The pool gains one identity provider per entry, the SPA client offers it next to the local methods, and Cognito's own hosted endpoints on authDomainName do the redirect dance (authorize → provider → /oauth2/idpresponse → the app's /auth/callback, PKCE code flow). A federated user ends up with the same tokens as a password user; grants, groups, vending and the 12-hour session cap are untouched.
Cognito treats every federated identity as a new person by default. The portal keeps "admins decide who gets in": an invite links the invited email to each configured provider, so the first federated sign-in lands on the invited user's sub; users invited before federation existed (or whose provider spells the email in another case) are linked by the pre-sign-up trigger on their first attempt, which costs them one automatic extra hop through the provider. An email nobody invited is refused with "Your account isn't set up here yet" — no stray pool user is ever created.
MFA for federated users is the provider's job (conditional access); the pool's mfa setting keeps applying to local sign-ins only. See Security Posture.
-
Decide the claim keys first. They become
custom:<key>attributes and cannot be renamed or removed once the pool has them — the same class of decision asresourcePrefix. -
Entra admin center → App registrations → New registration. Single-tenant. Platform Web, redirect URI
https://<authDomainName>/oauth2/idpresponse(the deploy prints it as theFederationRedirectUrioutput of WebStack; on a deployment without thewebblock it is the Cognito prefix domain). Leave ID tokens on. -
Certificates & secrets → New client secret. Copy the value (shown once) and note the expiry — Entra caps it at 24 months; put the date in your calendar.
-
Token configuration → Add optional claim → ID →
email,given_name,family_name.oidis always present in v2.0 tokens. API permissions:openid,profile,email(User.Read is fine; grant admin consent so users are not prompted). -
Overview → copy the Application (client) ID and the Directory (tenant) ID. The issuer is
https://login.microsoftonline.com/<tenant id>/v2.0. -
Put the secret in Secrets Manager, in the deployment's region, as a plain string:
aws secretsmanager create-secret --region <region> \ --name <resourcePrefix>/idp/ExampleCorp --secret-string '<the value from step 3>' \ --query ARN --output text
-
Add the block to
loginMethodsand deploy (pushmain):federation: [ { name: "ExampleCorp", label: "Example Corp", type: "oidc", issuerUrl: "https://login.microsoftonline.com/<tenant id>/v2.0", clientId: "<application (client) id>", clientSecretArn: "arn:aws:secretsmanager:<region>:<account>:secret:<prefix>/idp/ExampleCorp-XXXXXX", attributeMapping: { givenName: "given_name", familyName: "family_name" }, claims: { gid: { from: "oid", maxLen: 128, label: "Employee id" } }, }, ],
Entra only sends
emailfor accounts that have a mail attribute; for tenants where it is empty, mapemail: "preferred_username"(the UPN) and invite users by their UPN. -
Invite users with the address the provider asserts, lowercase (the pool's sign-in name is case-sensitive; a provider that spells it differently still gets in, at the cost of one extra hop on the first sign-in). With a provider configured, the invite email leads with "Sign in with — you don't need a password" and keeps the set-password link underneath for local users (one template serves both). Existing users need nothing — they are linked on their first federated sign-in. Changing a user's email in the portal moves their federated link to the new address. Invited people who only ever sign in through the provider never set a local password; the Users page stops calling them "invited" once they have been in.
-
Test: open the login page in a private window, click Sign in with Example Corp, complete the provider's sign-in, land on Accounts. On the Users page the mapped claim shows under the user's email once they have signed in through the provider; the next credential vend shows it on Activity (and in the CSV export).
- New secret at the provider (both stay valid until you remove the old one).
aws secretsmanager put-secret-value --secret-id <arn> --secret-string '<new value>' --query VersionId --output text- Set
clientSecretVersionIdin the block to that version id and deploy. Without the pin, CloudFormation does not re-read the secret because nothing about the provider resource changed. - Remove the old secret at the provider once a sign-in has succeeded on the new one.
Delete its block and deploy. Linked identities are dropped with the provider; the users themselves, their grants and their local sign-in methods stay. The custom attributes remain on the pool (Cognito cannot remove them) and simply stop being written.
The shell keeps the sign-in in-view only on the provider's hosts — see allowedHosts for the rule. A provider that bounces through another host (a tenant's own ADFS, login.live.com for personal Microsoft accounts) needs it listed, or the sign-in opens in the system browser and never returns.
A federated session's tokens carry no Cognito self-service scope, so the Passkeys and Authenticator (MFA) items are hidden for it: those factors belong to the provider. A user who also has a local password can still manage them after a local sign-in.
-
"Your account isn't set up here yet" — no invited user has the email the provider asserted. Invite that address (lowercase), or check which address the provider sends (Entra:
emailvspreferred_username). - The first sign-in bounced once and then worked — expected for users invited before the provider existed: the trigger linked the identity and the page re-ran the flow.
-
Deploy fails creating the provider — Cognito could not fetch
<issuerUrl>/.well-known/openid-configuration, or theissin the document differs fromissuerUrl. Use the tenant-specific v2.0 issuer, nevercommon. -
Sign-in works but the claim is empty — the provider did not send the claim (Entra: add it under Token configuration), or the value exceeded
maxLen.
Source: wiki/ in FNTIO/aws-infrastructure-client, mirrored by the Wiki workflow. Edit the files there; changes made on this site are overwritten by the next sync.
Start here
Use
How it works
Operate
Contribute