Cognito

kumolo implements the Cognito User Pools REST API. All operations accept standard AWS SDK v2 requests — point your client at http://localhost:5566. Unlike S3, UsePathStyle is not required; only BaseEndpoint needs to be overridden on the client.

A JWKS endpoint is available at http://localhost:5566/{userPoolId}/.well-known/jwks.json for JWT verification.

Support levels

Symbol	Meaning
✓	Fully implemented — the feature behaves like real AWS
◐	Partial support — the operation works but has known limitations; see the note for details
—	Not yet implemented

Operation support

Operations sourced from internal/cognito/router.go in the kumolo repository.

User pool management

Operation	Supported
CreateUserPool	◐
DescribeUserPool	✓
UpdateUserPool	◐
DeleteUserPool	✓
ListUserPools	✓
GetUserPoolMfaConfig	◐
SetUserPoolMfaConfig	◐
AddCustomAttributes	—
GetLogDeliveryConfiguration	—
SetLogDeliveryConfiguration	—
GetSigningCertificate	—

Note

CreateUserPool resolves the new pool’s region from the caller’s SigV4 credential scope (the region configured on the AWS SDK/CLI/Terraform provider) — falling back to the AWS_REGION/AWS_DEFAULT_REGION environment variables on the kumolo process, then to us-east-1 if neither is set. kumolo uses the resolved region in the pool ID’s {region}_ prefix and uses the same region in the pool ARN (arn:{partition}:cognito-idp:{region}:000000000000:userpool/{poolId}, account fixed at 000000000000) and the JWT iss claim (https://cognito-idp.{region}.amazonaws.com/{poolId}). {partition} follows AWS’s ARN partition scheme: aws-us-gov for GovCloud (US) regions (us-gov-west-1, us-gov-east-1), aws otherwise — kumolo doesn’t emulate the China regions’ aws-cn partition. kumolo does not validate that the region is a real AWS region name; pools created before this resolution existed keep their original us-east-1_... ID.

Password policy enforcement: kumolo enforces minimum length (default 8 characters), AWS’s 256-character maximum length, and complexity rules (RequireUppercase, RequireLowercase, RequireNumbers, RequireSymbols, all default true) on every operation that accepts a plaintext password (SignUp, AdminCreateUser, AdminSetUserPassword, RespondToAuthChallenge’s NEW_PASSWORD_REQUIRED, ConfirmForgotPassword, ChangePassword). kumolo accepts and stores PasswordHistorySize but does not enforce it — no password history is tracked.

kumolo enforces DeletionProtection: DeleteUserPool rejects a pool with DeletionProtection set to ACTIVE (InvalidParameterException); unprotected pools remain deletable.

GetUserPoolMfaConfig / SetUserPoolMfaConfig: kumolo persists only MfaConfiguration (OFF/ON/OPTIONAL) — this is the pool-level enforcement switch, not a per-user record. SoftwareTokenMfaConfiguration.Enabled always reports as false since kumolo doesn’t model this pool-level TOTP method toggle; this is independent of per-user TOTP enrollment, which is fully supported (see AssociateSoftwareToken / VerifySoftwareToken / SetUserMFAPreference below). kumolo accepts but silently ignores SmsMfaConfiguration/EmailMfaConfiguration/WebAuthnConfiguration. A pool with MfaConfiguration: "ON" forces every unenrolled user through the MFA_SETUP challenge on sign-in, and an enrolled user cannot disable MFA afterward — see RespondToAuthChallenge and SetUserMFAPreference below. MfaConfiguration: "OPTIONAL" is accepted but not enforced; only per-user SetUserMFAPreference opt-in applies in that case.

AccountRecoverySetting is accepted, stored, and returned as-is on CreateUserPool / UpdateUserPool / DescribeUserPool. CreateUserPool defaults it to verified_phone_number (priority 1) then verified_email (priority 2) when omitted, matching AWS. See ForgotPassword below for how it’s consumed.

User pool domains

Operation	Supported
CreateUserPoolDomain	—
UpdateUserPoolDomain	—
DeleteUserPoolDomain	—
DescribeUserPoolDomain	—

User pool replicas

Operation	Supported
CreateUserPoolReplica	—
UpdateUserPoolReplica	—
DeleteUserPoolReplica	—
ListUserPoolReplicas	—

User pool clients

Operation	Supported
CreateUserPoolClient	◐
DescribeUserPoolClient	✓
UpdateUserPoolClient	◐
DeleteUserPoolClient	✓
ListUserPoolClients	✓
AddUserPoolClientSecret	—
DeleteUserPoolClientSecret	—
ListUserPoolClientSecrets	—

Note

Fields omitted from CreateUserPoolClient and UpdateUserPoolClient are cleared rather than defaulted to AWS defaults. ClientSecret is generated if GenerateSecret: true but is not validated on any auth request.

Authentication

Operation	Supported
SignUp	◐
ConfirmSignUp	✓
ResendConfirmationCode	◐
InitiateAuth	◐
RespondToAuthChallenge	◐
AdminInitiateAuth	—
AdminRespondToAuthChallenge	—
ForgotPassword	◐
ConfirmForgotPassword	◐
ChangePassword	◐
GetTokensFromRefreshToken	—
RevokeToken	✓
GlobalSignOut	✓
AdminUserGlobalSignOut	—

InitiateAuth supports the following auth flows:

• USER_PASSWORD_AUTH — username and password authentication
• USER_SRP_AUTH — SRP-6a authentication (used by AWS Amplify by default)
• REFRESH_TOKEN_AUTH — exchange a refresh token for new tokens

RespondToAuthChallenge supports the NEW_PASSWORD_REQUIRED, PASSWORD_VERIFIER, SOFTWARE_TOKEN_MFA, and MFA_SETUP challenges.

Note

Confirmation codes: codes issued by SignUp and ResendConfirmationCode are written to the kumolo server log instead of being sent via email or SMS. Use AdminConfirmSignUp in tests to skip code retrieval entirely.

Token expiry: ExpiresIn and each token’s exp claim reflect the requesting client’s AccessTokenValidity/IdTokenValidity/RefreshTokenValidity, honoring TokenValidityUnits (defaults: hours for access/ID tokens, days for refresh tokens, matching AWS). Expiry is enforced on every authenticated request.

SecretHash, ClientMetadata, AnalyticsMetadata, UserContextData: accepted on all auth operations but ignored. Lambda triggers are not supported.

RespondToAuthChallenge: USERNAME is optional in kumolo (taken from the session JWT when omitted); on real AWS it is required.

USER_SRP_AUTH / PASSWORD_VERIFIER: implements the SRP-6a protocol AWS Amplify uses by default, so Amplify apps can point at kumolo without switching to USER_PASSWORD_AUTH. An unknown username fails immediately with UserNotFoundException at InitiateAuth — kumolo does not implement AWS’s anti-enumeration “fake verifier” response. A FORCE_CHANGE_PASSWORD user completing SRP authentication receives a chained NEW_PASSWORD_REQUIRED challenge instead of tokens, same as USER_PASSWORD_AUTH.

SOFTWARE_TOKEN_MFA: issued instead of tokens whenever USER_PASSWORD_AUTH, PASSWORD_VERIFIER, or the post-NEW_PASSWORD_REQUIRED reset succeeds for a user with TOTP MFA enabled (see SetUserMFAPreference below). RespondToAuthChallenge verifies the submitted SOFTWARE_TOKEN_MFA_CODE as a TOTP code (RFC 6238, ±1 time step / ±30s clock skew) against the user’s registered secret; a mismatch returns CodeMismatchException. On success, tokens are issued exactly as for the non-MFA path.

MFA_SETUP: issued instead of SOFTWARE_TOKEN_MFA/tokens whenever primary authentication succeeds for a user with no TOTP secret registered (TOTPSecret == "") in a pool with MfaConfiguration: "ON". A user who already holds a registered TOTP secret gets SOFTWARE_TOKEN_MFA instead — even if SoftwareTokenMFAEnabled is currently false (e.g. a user who enrolled and then disabled MFA while the pool was still OPTIONAL, then the pool switched to "ON"): kumolo reuses the existing authenticator rather than forcing re-enrollment through a fresh secret, matching AWS’s documented MFA decision tree. Completing that SOFTWARE_TOKEN_MFA challenge self-heals SoftwareTokenMFAEnabled back to true. ChallengeParameters reports MFAS_CAN_SETUP: ["SOFTWARE_TOKEN_MFA"] — only TOTP enrollment is offered, matching kumolo’s overall MFA support. REFRESH_TOKEN_AUTH never re-triggers this challenge, and it never fires for MfaConfiguration: "OPTIONAL" pools. Complete enrollment with the Session-authenticated AssociateSoftwareToken / VerifySoftwareToken calls below, then call RespondToAuthChallenge with ChallengeName: "MFA_SETUP" and the verified Session — no ChallengeResponses beyond an optional USERNAME (must match the session’s username if supplied) are required, since the verified secret already travels in the session. On success kumolo persists the TOTP secret, sets SoftwareTokenMFAEnabled: true and PreferredMfaSetting: "SOFTWARE_TOKEN_MFA", and issues tokens. Responding with a session that never completed VerifySoftwareToken returns NotAuthorizedException.

ForgotPassword / ConfirmForgotPassword: like SignUp, kumolo writes the reset code to the server log (ForgotPassword message) instead of emailing or texting it — set KUMOLO_LOG_LEVEL=debug to see the code; the default info level logs the event without it. ForgotPassword selects the code delivery attribute using the user pool’s AccountRecoverySetting.RecoveryMechanisms priority order — a pool without an explicit AccountRecoverySetting defaults to verified_phone_number (priority 1) then verified_email (priority 2), matching AWS’s default. An admin_only recovery mechanism disables self-service recovery entirely. If the user has no verified attribute matching an eligible mechanism, kumolo returns InvalidParameterException, matching real AWS’s requirement. kumolo does not implement code expiry (ExpiredCodeException), and does not enforce PreventUserExistenceErrors — a missing username always returns UserNotFoundException.

ChangePassword: kumolo does not apply password history policy (PasswordHistoryPolicyViolationException), and does not check the access token’s OAuth scope.

User operations

Operation	Supported
GetUser	✓
UpdateUserAttributes	◐
DeleteUserAttributes	—
DeleteUser	✓
GetUserAttributeVerificationCode	◐
VerifyUserAttribute	◐
GetUserAuthFactors	—
SetUserMFAPreference	◐
SetUserSettings	—
GetUICustomization	—
SetUICustomization	—
UpdateAuthEventFeedback	—

Note

UpdateUserAttributes: real AWS holds a new email/phone_number value pending until verified via VerifyUserAttribute. kumolo has no email/SMS delivery to gate on, so it applies every attribute change immediately. Changing email/phone_number still resets the paired email_verified/phone_number_verified attribute to false and generates a verification code (logged at Info level, same as SignUp).

GetUserAttributeVerificationCode / VerifyUserAttribute: AttributeName is restricted to email or phone_number — the only attributes kumolo tracks a verification code for.

SetUserMFAPreference: only SoftwareTokenMfaSettings is persisted; SMSMfaSettings, EmailMfaSettings, and WebAuthnMfaSettings are accepted but silently ignored. Setting Enabled: true without a prior successful VerifySoftwareToken call is rejected with InvalidParameterException — kumolo requires a registered TOTP secret before it can be made the sign-in requirement. Setting Enabled: false clears the preferred-MFA flag but keeps the registered TOTP secret, so re-enabling doesn’t require another enrollment round trip — except in a pool with MfaConfiguration: "ON", where disabling an already-enrolled user’s MFA is rejected with InvalidParameterException instead: real AWS doesn’t let users disable an MFA method once the pool requires MFA. Enabling remains allowed in an "ON" pool (e.g. pre-registering TOTP before ever signing in with MFA). This rejection only applies once the pool is already "ON": disabling in an OPTIONAL/OFF pool is unconditionally allowed, and if the pool is later switched to "ON", that user’s stored TOTP secret still gets challenged directly via SOFTWARE_TOKEN_MFA on next sign-in rather than forcing a fresh MFA_SETUP enrollment (see MFA_SETUP above).

Admin operations

Operation	Supported
AdminCreateUser	◐
AdminGetUser	✓
AdminSetUserPassword	◐
AdminConfirmSignUp	✓
AdminDeleteUser	✓
AdminDisableUser	✓
AdminEnableUser	✓
AdminUpdateUserAttributes	◐
AdminDeleteUserAttributes	—
AdminResetUserPassword	—
AdminSetUserMFAPreference	—
AdminSetUserSettings	—
AdminListUserAuthEvents	—
AdminUpdateAuthEventFeedback	—
AdminDisableProviderForUser	—
AdminLinkProviderForUser	—

Note

AdminCreateUser: password policy enforcement (minimum length and complexity rules) applies the same as SignUp — see the note above. ForceAliasCreation and DesiredDeliveryMediums are accepted but ignored — no invitation messages are sent.

AdminSetUserPassword: password policy enforcement applies the same as SignUp — see the note above. Password history policy (PasswordHistoryPolicyViolationException) is not applied.

AdminUpdateUserAttributes: same immediate-apply behavior as UpdateUserAttributes. Admins can skip verification-code generation entirely by including email_verified/phone_number_verified set to "true" in the same request.

User listing

Operation	Supported
ListUsers	◐

Note

ListUsers: Filter supports a subset of real AWS’s syntax — AttributeName = "Value" (exact match) or AttributeName ^= "Value" (prefix match) against one of username, sub, cognito:user_status, status (compares against Enabled), email, phone_number, name, given_name, family_name, or preferred_username. Custom attributes and embedded-quote escaping are not supported. AttributesToGet is accepted but ignored — all attributes are always returned.

Group management

Operation	Supported
CreateGroup	✓
GetGroup	✓
UpdateGroup	✓
DeleteGroup	✓
ListGroups	✓
ListUsersInGroup	✓
AdminAddUserToGroup	✓
AdminRemoveUserFromGroup	✓
AdminListGroupsForUser	✓

Device management

Operation	Supported
ConfirmDevice	—
ForgetDevice	—
GetDevice	—
ListDevices	—
UpdateDeviceStatus	—
AdminForgetDevice	—
AdminGetDevice	—
AdminListDevices	—
AdminUpdateDeviceStatus	—

MFA & WebAuthn

Operation	Supported
AssociateSoftwareToken	◐
VerifySoftwareToken	◐
StartWebAuthnRegistration	—
CompleteWebAuthnRegistration	—
DeleteWebAuthnCredential	—
ListWebAuthnCredentials	—

Note

AssociateSoftwareToken / VerifySoftwareToken: accept either AccessToken (an already-signed-in user enrolling MFA from a settings screen) or Session (completing a forced MFA_SETUP challenge from InitiateAuth/RespondToAuthChallenge, see above) — supplying both or neither returns InvalidParameterException. AssociateSoftwareToken generates a Base32-encoded TOTP secret (RFC 4648/6238); the AccessToken flow stores it as pending on the user record, while the Session flow carries it in the (kumolo-specific, signed-JWT) session instead — nothing is written to user storage until RespondToAuthChallenge completes. Calling it again before verifying discards the previous pending secret. VerifySoftwareToken checks the submitted 6-digit code against the pending secret (±1 time step / ±30s clock skew); on success the AccessToken flow promotes it to the user’s active TOTP secret immediately (this only registers the authenticator — call SetUserMFAPreference to enable it for sign-in), while the Session flow returns a new session carrying the now-verified secret for the subsequent RespondToAuthChallenge call. A code mismatch returns CodeMismatchException (HTTP 400) rather than AWS’s Status: "ERROR" response body.

Identity providers

Operation	Supported
CreateIdentityProvider	—
DescribeIdentityProvider	—
UpdateIdentityProvider	—
DeleteIdentityProvider	—
ListIdentityProviders	—
GetIdentityProviderByIdentifier	—

Resource servers

Operation	Supported
CreateResourceServer	—
DescribeResourceServer	—
UpdateResourceServer	—
DeleteResourceServer	—
ListResourceServers	—

User import

Operation	Supported
GetCSVHeader	—
CreateUserImportJob	—
DescribeUserImportJob	—
StartUserImportJob	—
StopUserImportJob	—
ListUserImportJobs	—

Risk configuration

Operation	Supported
DescribeRiskConfiguration	—
SetRiskConfiguration	—

Managed login branding

Operation	Supported
CreateManagedLoginBranding	—
DescribeManagedLoginBranding	—
DescribeManagedLoginBrandingByClient	—
UpdateManagedLoginBranding	—
DeleteManagedLoginBranding	—

Terms

Operation	Supported
CreateTerms	—
DescribeTerms	—
ListTerms	—
UpdateTerms	—
DeleteTerms	—

Tagging

Operation	Supported
TagResource	✓
UntagResource	✓
ListTagsForResource	✓

Quick start

Go

package main

import (
  "context"
  "fmt"

  "github.com/aws/aws-sdk-go-v2/aws"
  "github.com/aws/aws-sdk-go-v2/config"
  "github.com/aws/aws-sdk-go-v2/credentials"
  "github.com/aws/aws-sdk-go-v2/service/cognitoidentityprovider"
  "github.com/aws/aws-sdk-go-v2/service/cognitoidentityprovider/types"
)

func main() {
  cfg, err := config.LoadDefaultConfig(context.Background(),
    config.WithRegion("us-east-1"),
    config.WithCredentialsProvider(
      credentials.NewStaticCredentialsProvider("test", "test", ""),
    ),
  )
  if err != nil {
    panic(err)
  }

  client := cognitoidentityprovider.NewFromConfig(cfg, func(o *cognitoidentityprovider.Options) {
    o.BaseEndpoint = aws.String("http://localhost:5566")
  })

  // Create a user pool
  pool, err := client.CreateUserPool(context.Background(), &cognitoidentityprovider.CreateUserPoolInput{
    PoolName: aws.String("my-pool"),
  })
  if err != nil {
    panic(err)
  }
  userPoolID := pool.UserPool.Id

  // Create a user pool client
  appClient, err := client.CreateUserPoolClient(context.Background(), &cognitoidentityprovider.CreateUserPoolClientInput{
    UserPoolId: userPoolID,
    ClientName: aws.String("my-app"),
    ExplicitAuthFlows: []types.ExplicitAuthFlowsType{
      types.ExplicitAuthFlowsTypeAllowUserPasswordAuth,
    },
  })
  if err != nil {
    panic(err)
  }
  clientID := appClient.UserPoolClient.ClientId

  // Sign up a user (confirmation code is logged to the kumolo server log)
  _, err = client.SignUp(context.Background(), &cognitoidentityprovider.SignUpInput{
    ClientId: clientID,
    Username: aws.String("alice"),
    Password: aws.String("P@ssw0rd!"),
  })
  if err != nil {
    panic(err)
  }

  // Admin confirm so no code retrieval is needed in tests
  _, err = client.AdminConfirmSignUp(context.Background(), &cognitoidentityprovider.AdminConfirmSignUpInput{
    UserPoolId: userPoolID,
    Username:   aws.String("alice"),
  })
  if err != nil {
    panic(err)
  }

  // Authenticate
  auth, err := client.InitiateAuth(context.Background(), &cognitoidentityprovider.InitiateAuthInput{
    ClientId: clientID,
    AuthFlow: types.AuthFlowTypeUserPasswordAuth,
    AuthParameters: map[string]string{
      "USERNAME": "alice",
      "PASSWORD": "P@ssw0rd!",
    },
  })
  if err != nil {
    panic(err)
  }
  fmt.Println("AccessToken:", *auth.AuthenticationResult.AccessToken)
}

Python (boto3)

import boto3

client = boto3.client(
    "cognito-idp",
    region_name="us-east-1",
    endpoint_url="http://localhost:5566",
    aws_access_key_id="test",
    aws_secret_access_key="test",
)

# Create a user pool
pool = client.create_user_pool(PoolName="my-pool")
user_pool_id = pool["UserPool"]["Id"]

# Create a user pool client
app_client = client.create_user_pool_client(
    UserPoolId=user_pool_id,
    ClientName="my-app",
    ExplicitAuthFlows=["ALLOW_USER_PASSWORD_AUTH"],
)
client_id = app_client["UserPoolClient"]["ClientId"]

# Sign up a user
client.sign_up(
    ClientId=client_id,
    Username="alice",
    Password="P@ssw0rd!",
)

# Admin confirm
client.admin_confirm_sign_up(UserPoolId=user_pool_id, Username="alice")

# Authenticate
auth = client.initiate_auth(
    ClientId=client_id,
    AuthFlow="USER_PASSWORD_AUTH",
    AuthParameters={"USERNAME": "alice", "PASSWORD": "P@ssw0rd!"},
)
print("AccessToken:", auth["AuthenticationResult"]["AccessToken"])

AWS CLI

# Create a user pool
POOL_ID=$(aws cognito-idp create-user-pool \
  --pool-name my-pool \
  --endpoint-url http://localhost:5566 \
  --region us-east-1 \
  --query 'UserPool.Id' --output text)

# Create a user pool client
CLIENT_ID=$(aws cognito-idp create-user-pool-client \
  --user-pool-id "$POOL_ID" \
  --client-name my-app \
  --explicit-auth-flows ALLOW_USER_PASSWORD_AUTH \
  --endpoint-url http://localhost:5566 \
  --region us-east-1 \
  --query 'UserPoolClient.ClientId' --output text)

# Sign up a user
aws cognito-idp sign-up \
  --client-id "$CLIENT_ID" \
  --username alice \
  --password 'P@ssw0rd!' \
  --endpoint-url http://localhost:5566 \
  --region us-east-1

# Admin confirm
aws cognito-idp admin-confirm-sign-up \
  --user-pool-id "$POOL_ID" \
  --username alice \
  --endpoint-url http://localhost:5566 \
  --region us-east-1

# Authenticate
aws cognito-idp initiate-auth \
  --client-id "$CLIENT_ID" \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME=alice,PASSWORD='P@ssw0rd!' \
  --endpoint-url http://localhost:5566 \
  --region us-east-1