Cognito — Amazon Cognito User Pools

AWS docs: https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html

Cognito User Pools (Identity Provider) uses the application/x-amz-json-1.1 protocol. Operations are identified by the X-Amz-Target header with the prefix AWSCognitoIdentityProviderService.. RPC v2 CBOR is also supported via the Smithy RPC path (POST /service/cognito/operation/{Operation}).

Accepted wire protocols: awsJson1_1, rpcv2Cbor

---

Summary

Category	✅ Supported	⚠️ Partial	🚧 WIP	❌ Unsupported
User Pools	5	0	0	0
Pool Clients	5	0	0	0
Users	10	0	0	0
Auth / Tokens	19	0	0	0
Groups	9	0	0	0
Domains	4	0	0	0

---

User Pool operations

Operation	Status	Notes
CreateUserPool	✅	Returns Id and Arn; Id format {region}_{8-char-hex}; accepts email templates
DescribeUserPool	✅	Returns email templates, admin config, email configuration
DeleteUserPool	✅	ResourceNotFoundException if not found
UpdateUserPool	✅	Updates VerificationMessageTemplate, AdminCreateUserConfig, EmailConfiguration
ListUserPools	✅	Pagination via NextToken

User Pool Client operations

Operation	Status	Notes
CreateUserPoolClient	✅	Returns ClientId (26-char hex); accepts AccessTokenValidity, IdTokenValidity, RefreshTokenValidity, TokenValidityUnits
DescribeUserPoolClient	✅	ResourceNotFoundException if not found
DeleteUserPoolClient	✅	ResourceNotFoundException if not found
UpdateUserPoolClient	✅	Updates client name, token validity
ListUserPoolClients	✅	Pagination via NextToken

User operations

Operation	Status	Notes
AdminCreateUser	✅	Bcrypt hashes password; sends email unless MessageAction=SUPPRESS
AdminDeleteUser	✅	UserNotFoundException if not found
AdminGetUser	✅	Returns attributes + status
AdminSetUserPassword	✅	Permanent=true sets status CONFIRMED
AdminConfirmSignUp	✅	Confirms a UNCONFIRMED user
AdminUpdateUserAttributes	✅	Merges attributes
AdminDeleteUserAttributes	✅	Removes named attributes from a user
AdminDisableUser	✅	Sets Enabled=false; sign-in returns NotAuthorizedException
AdminEnableUser	✅	Re-enables a disabled user
ListUsers	✅	Pagination via PaginationToken

Auth / Token operations

Operation	Status	Notes
SignUp	✅	Sends confirmation email; returns UserSub
ConfirmSignUp	✅	CodeMismatchException / ExpiredCodeException on failure; returns Session for USER_AUTH sign-in
ResendConfirmationCode	✅	Generates and emails a new confirmation code
InitiateAuth	✅	USER_PASSWORD_AUTH + REFRESH_TOKEN_AUTH; USER_AUTH with ConfirmSignUp Session; returns NEW_PASSWORD_REQUIRED or SOFTWARE_TOKEN_MFA
AdminInitiateAuth	✅	USER_PASSWORD_AUTH + REFRESH_TOKEN_AUTH with UserPoolId; USER_AUTH with ConfirmSignUp Session
RespondToAuthChallenge	✅	NEW_PASSWORD_REQUIRED and SOFTWARE_TOKEN_MFA challenges
AdminRespondToAuthChallenge	✅	Same as above with admin credentials
ForgotPassword	✅	Sends password-reset code by email
ConfirmForgotPassword	✅	Validates reset code; sets new bcrypt password
ChangePassword	✅	Validates AccessToken + old password before setting new one
GetUser	✅	Validates AccessToken; returns full user profile
UpdateUserAttributes	✅	Self-service; validates AccessToken; merges attributes
DeleteUserAttributes	✅	Self-service; validates AccessToken; removes named attributes
GlobalSignOut	✅	Revokes access + id + refresh tokens for the user
RevokeToken	✅	Revokes a specific refresh token
AssociateSoftwareToken	✅	Issues a TOTP secret for the user; requires valid AccessToken
VerifySoftwareToken	✅	Verifies a TOTP code and marks the secret verified
SetUserMFAPreference	✅	Enables/disables TOTP MFA for the calling user
AdminSetUserMFAPreference	✅	Same as above, admin version

Group operations

Operation	Status	Notes
CreateGroup	✅	GroupExistsException if duplicate
GetGroup	✅	ResourceNotFoundException if not found
DeleteGroup	✅	ResourceNotFoundException if not found
UpdateGroup	✅	Updates Description, Precedence, RoleArn
ListGroups	✅	Returns all groups for a pool
AdminAddUserToGroup	✅	Idempotent
AdminRemoveUserFromGroup	✅	No error if user is not in group
AdminListGroupsForUser	✅	Returns groups the user belongs to
ListUsersInGroup	✅	Returns users belonging to the specified group

User Pool Domain operations

Operation	Status	Notes
CreateUserPoolDomain	✅	Associates a domain with the user pool’s hosted UI
DescribeUserPoolDomain	✅	Returns domain details; empty DomainDescription when domain not found
DeleteUserPoolDomain	✅	Removes the domain association from the pool
UpdateUserPoolDomain	✅	Accepted; SSL certificate updates are inert in the emulator

---

Notes

Each user pool exposes a JWKS endpoint used by API Gateways and libraries to validate tokens:

GET /{poolId}/.well-known/jwks.json

Access and ID tokens are RS256-signed JWTs. The signing key is lazily generated per pool (RSA-2048) and stored in the emulator state so it survives restarts when a persistent backend is used.

• Target dispatch header: X-Amz-Target: AWSCognitoIdentityProviderService.<Operation>.
• Unimplemented operations return JSON 501 Not Implemented.
• Pool IDs follow the {region}_{8-char-hex} format (e.g. us-east-1_A1B2C3D4).
• Passwords are stored using bcrypt (cost 10).
• Access and ID tokens are RS256-signed JWTs (standard 3-part format). Refresh, session, and MFA tokens are opaque hex strings.
• Each pool has a lazily-generated RSA-2048 signing key exposed at the JWKS endpoint.
• Email delivery uses the configured SMTP server (the built-in mock SMTP server by default).
• Per-pool email templates: VerificationMessageTemplate (with EmailMessage, EmailSubject, EmailMessageByLink, EmailSubjectByLink, DefaultEmailOption, SmsMessage), AdminCreateUserConfig (with InviteMessageTemplate containing EmailMessage, EmailSubject, SMSMessage; plus AllowAdminCreateUserOnly and UnusedAccountValidityDays), and EmailConfiguration (with EmailSendingAccount, SourceArn, From, ReplyToEmailAddress). Templates use {username} and {####} placeholders.
• TOTP MFA: RFC 6238, HMAC-SHA1, 30-second window, 6-digit codes. Clock skew tolerance: ±30 seconds.

User import (emulator-only)

Users can be imported from a real AWS Cognito user pool into an Overcast pool. Imported users are placed in FORCE_CHANGE_PASSWORD status because password hashes cannot be extracted from AWS.

CLI

overcast import cognito-users \
  --from-pool-id us-east-1_abc123 \
  --to-pool-id us-east-1_abc123 \
  --from-profile my-aws-profile \
  --batch-size 100

Flag	Default	Description
--from-pool-id	(req)	Source user pool ID in real AWS
--to-pool-id	(req)	Target user pool ID in Overcast
--from-profile		AWS profile for source credentials
--from-region		AWS region (auto-detected if omitted)
--user		Import a single user by sub (UUID)
--max-users	0	Limit total users (0 = unlimited)
--batch-size	100	Users per POST to the server
--endpoint		Overcast daemon URL (inherited from root command)

HTTP endpoint

POST /_overcast/cognito/user-pools/{poolId}/import-users

Content-Type: application/json

{
  "users": [
    {
      "username": "jdoe",
      "sub": "a1b2c3d4-...",
      "enabled": true,
      "status": "CONFIRMED",
      "createdAt": "2024-01-01T00:00:00Z",
      "modifiedAt": "2024-01-01T00:00:00Z",
      "attributes": [
        {"name": "email", "value": "jdoe@example.com"}
      ],
      "groups": ["Admins"],
      "mfaEnabled": false
    }
  ]
}

Response

{
  "imported": 1,
  "skipped": 0,
  "errors": []
}

Status mapping

AWS status	Overcast status
CONFIRMED	FORCE_CHANGE_PASSWORD
FORCE_CHANGE_PASSWORD	FORCE_CHANGE_PASSWORD
RESET_REQUIRED	FORCE_CHANGE_PASSWORD
UNCONFIRMED	UNCONFIRMED
DISABLED	DISABLED
ARCHIVED, COMPROMISED	DISABLED
EXTERNAL_PROVIDER	skipped

Behaviour

• The original sub is preserved; any sub attribute in the payload is overwritten.
• Groups referenced by the user are auto-created as stubs if they don’t already exist in the target pool.
• Duplicate usernames are skipped (reported in errors).
• No password, confirmation code, or TOTP secret is imported.

Summary

Category	✅ Supported
User Pool operations	7
User Pool Client operations	5
User operations	10
Auth / Token operations	32
Group operations	9
User Pool Domain operations	4
Tags	3

---

Endpoints

User Pool operations

Operation	Status	Notes	AWS Docs
CreateUserPool	✅ Supported	Returns Id and Arn; Id format {region}_{8-char-hex}; accepts SignInPolicy, email templates, UserAttributeUpdateSettings, DeviceConfiguration, AliasAttributes, AccountRecoverySetting, SmsConfiguration, SmsAuthenticationMessage, SmsVerificationMessage, EmailVerificationMessage, EmailVerificationSubject, and LambdaConfig; LambdaConfig’s PreSignUp, PostConfirmation, PreTokenGeneration, PostAuthentication, and CustomMessage are invoked on the classic X-Amz-Target API (issue #1171); PreAuthentication, UserMigration, the CUSTOM_AUTH challenge triggers (#88/#94/#101), and the Smithy RPC v2 duplicate dispatch path are not	docs
DescribeUserPool	✅ Supported	Returns SignInPolicy, email templates, admin config, email configuration, UserAttributeUpdateSettings, AliasAttributes, AccountRecoverySetting, SmsConfiguration, SmsAuthenticationMessage, SmsVerificationMessage, EmailVerificationMessage, EmailVerificationSubject, and LambdaConfig	docs
DeleteUserPool	✅ Supported	ResourceNotFoundException if not found	docs
UpdateUserPool	✅ Supported	Updates SignInPolicy, VerificationMessageTemplate, AdminCreateUserConfig, EmailConfiguration, UserAttributeUpdateSettings, DeviceConfiguration, AccountRecoverySetting, SmsConfiguration, SmsAuthenticationMessage, SmsVerificationMessage, EmailVerificationMessage, EmailVerificationSubject, and LambdaConfig; the CloudFormation UserPool handler treats an AliasAttributes/UsernameAttributes change as requiring replacement, matching real Cognito’s UpdateUserPoolRequest (neither is a member there)	docs
ListUserPools	✅ Supported	Pagination via NextToken	docs
SetUserPoolMfaConfig	✅ Supported	Stores MfaConfiguration and WebAuthnConfiguration for passkey sign-in; passkey cryptographic validation is intentionally partial	docs
GetUserPoolMfaConfig	✅ Supported	Returns stored MfaConfiguration and WebAuthnConfiguration	docs

User Pool Client operations

Operation	Status	Notes	AWS Docs
CreateUserPoolClient	✅ Supported	Returns ClientId (26-char hex); accepts and validates ExplicitAuthFlows, AccessTokenValidity, IdTokenValidity, RefreshTokenValidity, TokenValidityUnits, PreventUserExistenceErrors, ReadAttributes, WriteAttributes	docs
DescribeUserPoolClient	✅ Supported	ResourceNotFoundException if not found	docs
DeleteUserPoolClient	✅ Supported	ResourceNotFoundException if not found	docs
UpdateUserPoolClient	✅ Supported	Updates client name, validates ExplicitAuthFlows, token validity, PreventUserExistenceErrors, ReadAttributes, WriteAttributes	docs
ListUserPoolClients	✅ Supported	Pagination via NextToken	docs

User operations

Operation	Status	Notes	AWS Docs
AdminCreateUser	✅ Supported	Bcrypt hashes password; sends email unless MessageAction=SUPPRESS; invokes PreSignUp_AdminCreateUser (its autoConfirm/autoVerify response fields are ignored, matching AWS) and CustomMessage_AdminCreateUser (issue #1171)	docs
AdminDeleteUser	✅ Supported	UserNotFoundException if not found	docs
AdminGetUser	✅ Supported	Returns attributes + status	docs
AdminSetUserPassword	✅ Supported	Permanent=true sets status CONFIRMED	docs
AdminConfirmSignUp	✅ Supported	Confirms a UNCONFIRMED user; invokes PostConfirmation_ConfirmSignUp fire-and-forget — a trigger error is logged but does not fail the call or roll back the confirmation (issue #1171)	docs
AdminUpdateUserAttributes	✅ Supported	Merges attributes; honors verification-before-update settings unless *_verified=true is supplied	docs
AdminDeleteUserAttributes	✅ Supported	Removes named attributes from a user	docs
AdminDisableUser	✅ Supported	Sets Enabled=false; sign-in returns NotAuthorizedException	docs
AdminEnableUser	✅ Supported	Re-enables a disabled user	docs
ListUsers	✅ Supported	Pagination via PaginationToken	docs

Auth / Token operations

Operation	Status	Notes	AWS Docs
SignUp	✅ Supported	Sends confirmation email; returns UserSub; invokes PreSignUp_SignUp (autoConfirmUser/autoVerifyEmail/autoVerifyPhone honored — an auto-confirmed user also fires PostConfirmation_ConfirmSignUp within the same call, and no confirmation message is sent) and CustomMessage_SignUp; either failing fails SignUp with UserLambdaValidationException (issue #1171)	docs
ConfirmSignUp	✅ Supported	CodeMismatchException / ExpiredCodeException on failure; returns Session for USER_AUTH sign-in; invokes PostConfirmation_ConfirmSignUp fire-and-forget (issue #1171)	docs
ResendConfirmationCode	✅ Supported	Generates and emails a new confirmation code; invokes CustomMessage_ResendCode, failing the call on a trigger error (issue #1171)	docs
InitiateAuth	✅ Supported	USER_PASSWORD_AUTH + USER_SRP_AUTH + REFRESH_TOKEN_AUTH + CUSTOM_AUTH; USER_AUTH with ConfirmSignUp Session, SELECT_CHALLENGE/PASSWORD/PASSWORD_SRP/WEB_AUTHN/EMAIL_OTP/SMS_OTP, or preferred PASSWORD/WEB_AUTHN/EMAIL_OTP/SMS_OTP; returns NEW_PASSWORD_REQUIRED, SOFTWARE_TOKEN_MFA, or DEVICE_SRP_AUTH; a completed authentication invokes PostAuthentication_Authentication then PreTokenGeneration (TokenGeneration_Authentication/_RefreshTokens/_NewPasswordChallenge/_AuthenticateDevice as appropriate), each able to fail the call (issue #1171)	docs
AdminInitiateAuth	✅ Supported	USER_PASSWORD_AUTH + USER_SRP_AUTH + REFRESH_TOKEN_AUTH + CUSTOM_AUTH with UserPoolId; USER_AUTH with ConfirmSignUp Session, SELECT_CHALLENGE/PASSWORD/PASSWORD_SRP/WEB_AUTHN/EMAIL_OTP/SMS_OTP, or preferred PASSWORD/WEB_AUTHN/EMAIL_OTP/SMS_OTP; same PostAuthentication/PreTokenGeneration trigger invocation as InitiateAuth (issue #1171)	docs
RespondToAuthChallenge	✅ Supported	SELECT_CHALLENGE/PASSWORD/PASSWORD_SRP/WEB_AUTHN/EMAIL_OTP/SMS_OTP, PASSWORD, PASSWORD_VERIFIER, CUSTOM_CHALLENGE, DEVICE_SRP_AUTH, DEVICE_PASSWORD_VERIFIER, WEB_AUTHN, EMAIL_OTP, SMS_OTP, NEW_PASSWORD_REQUIRED, and SOFTWARE_TOKEN_MFA challenges; a challenge completion that issues tokens invokes PostAuthentication_Authentication (skipped for NEW_PASSWORD_REQUIRED) then PreTokenGeneration, each able to fail the call (issue #1171)	docs
AdminRespondToAuthChallenge	✅ Supported	Same as above with admin credentials, including the same trigger invocation (issue #1171)	docs
ConfirmDevice	✅ Supported	Confirms a NewDeviceMetadata device key and stores remembered-device metadata; SRP verifier validation is intentionally partial	docs
GetDevice	✅ Supported	Returns a confirmed device for the signed-in user	docs
ListDevices	✅ Supported	Lists confirmed devices for the signed-in user	docs
UpdateDeviceStatus	✅ Supported	Marks a signed-in user’s confirmed device as remembered or not_remembered	docs
ForgetDevice	✅ Supported	Removes a confirmed device for the signed-in user	docs
AdminGetDevice	✅ Supported	Returns a user’s confirmed device	docs
AdminListDevices	✅ Supported	Lists a user’s confirmed devices with pagination	docs
AdminUpdateDeviceStatus	✅ Supported	Marks a user’s confirmed device as remembered or not_remembered	docs
AdminForgetDevice	✅ Supported	Removes a user’s confirmed device	docs
ForgotPassword	✅ Supported	Sends password-reset code by email; invokes CustomMessage_ForgotPassword, failing the call on a trigger error (issue #1171)	docs
ConfirmForgotPassword	✅ Supported	Validates reset code; sets new bcrypt password; invokes PostConfirmation_ConfirmForgotPassword fire-and-forget (issue #1171)	docs
ChangePassword	✅ Supported	Validates AccessToken + old password before setting new one	docs
GetUser	✅ Supported	Validates AccessToken; returns full user profile	docs
UpdateUserAttributes	✅ Supported	Self-service; validates AccessToken; merges attributes or creates pending email/phone updates with CodeDeliveryDetailsList	docs
VerifyUserAttribute	✅ Supported	Verifies pending email/phone updates and sets *_verified=true	docs
GetUserAttributeVerificationCode	✅ Supported	Sends or resends email/phone verification codes for the signed-in user	docs
DeleteUserAttributes	✅ Supported	Self-service; validates AccessToken; removes named attributes	docs
GlobalSignOut	✅ Supported	Revokes access + id + refresh tokens for the user	docs
RevokeToken	✅ Supported	Revokes a specific refresh token	docs
AssociateSoftwareToken	✅ Supported	Issues a TOTP secret for the user; requires valid AccessToken	docs
VerifySoftwareToken	✅ Supported	Verifies a TOTP code and marks the secret verified	docs
StartWebAuthnRegistration	✅ Supported	Returns passkey CredentialCreationOptions for the signed-in user	docs
CompleteWebAuthnRegistration	✅ Supported	Registers passkey credential metadata; attestation validation is intentionally partial	docs
SetUserMFAPreference	✅ Supported	Enables/disables TOTP MFA for the calling user	docs
AdminSetUserMFAPreference	✅ Supported	Same as above, admin version	docs

Group operations

Operation	Status	Notes	AWS Docs
CreateGroup	✅ Supported	GroupExistsException if duplicate	docs
GetGroup	✅ Supported	ResourceNotFoundException if not found	docs
DeleteGroup	✅ Supported	ResourceNotFoundException if not found	docs
UpdateGroup	✅ Supported	Updates Description, Precedence, RoleArn	docs
ListGroups	✅ Supported	Returns all groups for a pool	docs
AdminAddUserToGroup	✅ Supported	Idempotent	docs
AdminRemoveUserFromGroup	✅ Supported	No error if user is not in group	docs
AdminListGroupsForUser	✅ Supported	Returns groups the user belongs to	docs
ListUsersInGroup	✅ Supported	Returns users belonging to the specified group	docs

User Pool Domain operations

Operation	Status	Notes	AWS Docs
CreateUserPoolDomain	✅ Supported	Associates a domain with the user pool’s hosted UI	docs
DescribeUserPoolDomain	✅ Supported	Returns domain details; empty DomainDescription when domain not found	docs
DeleteUserPoolDomain	✅ Supported	Removes the domain association from the pool	docs
UpdateUserPoolDomain	✅ Supported	Accepted; SSL certificate updates are inert in the emulator	docs

Tags

Operation	Status	Notes	AWS Docs
TagResource	✅ Supported		docs
UntagResource	✅ Supported		docs
ListTagsForResource	✅ Supported		docs