User pool configuration, application client setup, and pool-level settings management for administrators configuring Amazon Cognito User Pools.
Create and configure user pools with comprehensive policy and feature settings.
/**
* Create a new user pool
* Establishes a user directory with specified policies and configurations
*/
class CreateUserPoolCommand {
constructor(input: CreateUserPoolCommandInput);
}
interface CreateUserPoolCommandInput {
/** Name of the user pool */
PoolName: string;
/** Password and other security policies */
Policies?: UserPoolPolicyType;
/** Lambda trigger configurations */
LambdaConfig?: LambdaConfigType;
/** Attributes that are auto-verified (email, phone_number) */
AutoVerifiedAttributes?: VerifiedAttributeType[];
/** Attributes that can be used as aliases for username */
AliasAttributes?: AliasAttributeType[];
/** Attributes that can be used as username */
UsernameAttributes?: UsernameAttributeType[];
/** Custom user pool domain prefix */
Domain?: string;
/** SMS configuration for phone verification */
SmsConfiguration?: SmsConfigurationType;
/** Email configuration for email verification */
EmailConfiguration?: EmailConfigurationType;
/** Tags to apply to the user pool */
UserPoolTags?: Record<string, string>;
/** Configuration for admin user creation */
AdminCreateUserConfig?: AdminCreateUserConfigType;
/** Custom attributes schema */
Schema?: SchemaAttributeType[];
/** User pool add-ons (advanced security) */
UserPoolAddOns?: UserPoolAddOnsType;
/** Username configuration */
UsernameConfiguration?: UsernameConfigurationType;
/** Account recovery settings */
AccountRecoverySetting?: AccountRecoverySettingType;
}
interface CreateUserPoolCommandOutput {
/** The created user pool object */
UserPool?: UserPoolType;
}
/**
* Update user pool configuration
* Modify settings for an existing user pool
*/
class UpdateUserPoolCommand {
constructor(input: UpdateUserPoolCommandInput);
}
interface UpdateUserPoolCommandInput {
/** The user pool ID */
UserPoolId: string;
/** Updated password and security policies */
Policies?: UserPoolPolicyType;
/** Updated Lambda trigger configurations */
LambdaConfig?: LambdaConfigType;
/** Updated auto-verified attributes */
AutoVerifiedAttributes?: VerifiedAttributeType[];
/** Updated SMS configuration */
SmsConfiguration?: SmsConfigurationType;
/** Updated email configuration */
EmailConfiguration?: EmailConfigurationType;
/** Updated user pool tags */
UserPoolTags?: Record<string, string>;
/** Updated admin user creation config */
AdminCreateUserConfig?: AdminCreateUserConfigType;
/** Updated user pool add-ons */
UserPoolAddOns?: UserPoolAddOnsType;
/** Updated account recovery settings */
AccountRecoverySetting?: AccountRecoverySettingType;
}
/**
* Get user pool details
* Retrieve complete configuration for a user pool
*/
class DescribeUserPoolCommand {
constructor(input: DescribeUserPoolCommandInput);
}
interface DescribeUserPoolCommandInput {
/** The user pool ID to describe */
UserPoolId: string;
}
interface DescribeUserPoolCommandOutput {
/** Complete user pool configuration */
UserPool?: UserPoolType;
}
/**
* Delete a user pool
* Permanently removes the user pool and all its users
*/
class DeleteUserPoolCommand {
constructor(input: DeleteUserPoolCommandInput);
}
interface DeleteUserPoolCommandInput {
/** The user pool ID to delete */
UserPoolId: string;
}
/**
* List user pools in the account
* Returns all user pools with pagination support
*/
class ListUserPoolsCommand {
constructor(input: ListUserPoolsCommandInput);
}
interface ListUserPoolsCommandInput {
/** Maximum number of user pools to return */
MaxResults: number;
/** Pagination token for retrieving more results */
NextToken?: string;
}Manage application clients that can access the user pool.
/**
* Create a user pool client (app client)
* Defines how applications can interact with the user pool
*/
class CreateUserPoolClientCommand {
constructor(input: CreateUserPoolClientCommandInput);
}
interface CreateUserPoolClientCommandInput {
/** The user pool ID */
UserPoolId: string;
/** Name for the client */
ClientName: string;
/** Generate a client secret (for server-side apps) */
GenerateSecret?: boolean;
/** Refresh token validity period in days */
RefreshTokenValidity?: number;
/** Access token validity period in minutes */
AccessTokenValidity?: number;
/** ID token validity period in minutes */
IdTokenValidity?: number;
/** Token validity time units */
TokenValidityUnits?: TokenValidityUnitsType;
/** Allowed authentication flows */
ExplicitAuthFlows?: ExplicitAuthFlowsType[];
/** Supported identity providers */
SupportedIdentityProviders?: string[];
/** OAuth 2.0 callback URLs */
CallbackURLs?: string[];
/** OAuth 2.0 logout URLs */
LogoutURLs?: string[];
/** Default redirect URI */
DefaultRedirectURI?: string;
/** Allowed OAuth flows */
AllowedOAuthFlows?: OAuthFlowType[];
/** Allowed OAuth scopes */
AllowedOAuthScopes?: string[];
/** Allow OAuth flows in user pool hosted UI */
AllowedOAuthFlowsUserPoolClient?: boolean;
/** Attributes the client can read */
ReadAttributes?: string[];
/** Attributes the client can write */
WriteAttributes?: string[];
/** Analytics configuration */
AnalyticsConfiguration?: AnalyticsConfigurationType;
/** Prevent user existence errors */
PreventUserExistenceErrors?: PreventUserExistenceErrorTypes;
/** Authentication session validity */
AuthSessionValidity?: number;
}
interface CreateUserPoolClientCommandOutput {
/** The created user pool client */
UserPoolClient?: UserPoolClientType;
}
type ExplicitAuthFlowsType =
| "ADMIN_NO_SRP_AUTH"
| "CUSTOM_AUTH_FLOW_ONLY"
| "USER_PASSWORD_AUTH"
| "ALLOW_ADMIN_USER_PASSWORD_AUTH"
| "ALLOW_CUSTOM_AUTH"
| "ALLOW_USER_PASSWORD_AUTH"
| "ALLOW_USER_SRP_AUTH"
| "ALLOW_REFRESH_TOKEN_AUTH";
type OAuthFlowType = "code" | "implicit" | "client_credentials";
/**
* Update user pool client settings
* Modify configuration for an existing client
*/
class UpdateUserPoolClientCommand {
constructor(input: UpdateUserPoolClientCommandInput);
}
interface UpdateUserPoolClientCommandInput {
/** The user pool ID */
UserPoolId: string;
/** The client ID to update */
ClientId: string;
/** Updated client name */
ClientName?: string;
/** Updated refresh token validity */
RefreshTokenValidity?: number;
/** Updated access token validity */
AccessTokenValidity?: number;
/** Updated ID token validity */
IdTokenValidity?: number;
/** Updated explicit auth flows */
ExplicitAuthFlows?: ExplicitAuthFlowsType[];
/** Updated OAuth callback URLs */
CallbackURLs?: string[];
/** Updated OAuth logout URLs */
LogoutURLs?: string[];
/** Updated allowed OAuth flows */
AllowedOAuthFlows?: OAuthFlowType[];
/** Updated allowed OAuth scopes */
AllowedOAuthScopes?: string[];
}
/**
* Get user pool client details
* Retrieve complete configuration for a client
*/
class DescribeUserPoolClientCommand {
constructor(input: DescribeUserPoolClientCommandInput);
}
interface DescribeUserPoolClientCommandInput {
/** The user pool ID */
UserPoolId: string;
/** The client ID to describe */
ClientId: string;
}
/**
* Delete a user pool client
* Removes client access to the user pool
*/
class DeleteUserPoolClientCommand {
constructor(input: DeleteUserPoolClientCommandInput);
}
interface DeleteUserPoolClientCommandInput {
/** The user pool ID */
UserPoolId: string;
/** The client ID to delete */
ClientId: string;
}
/**
* List user pool clients
* Returns all clients for a user pool
*/
class ListUserPoolClientsCommand {
constructor(input: ListUserPoolClientsCommandInput);
}
interface ListUserPoolClientsCommandInput {
/** The user pool ID */
UserPoolId: string;
/** Maximum number of clients to return */
MaxResults?: number;
/** Pagination token for retrieving more results */
NextToken?: string;
}Manage custom domains for hosted UI and OAuth endpoints.
/**
* Create a user pool domain
* Sets up custom domain for hosted UI and OAuth endpoints
*/
class CreateUserPoolDomainCommand {
constructor(input: CreateUserPoolDomainCommandInput);
}
interface CreateUserPoolDomainCommandInput {
/** Domain name or subdomain prefix */
Domain: string;
/** The user pool ID */
UserPoolId: string;
/** Custom domain configuration (for fully custom domains) */
CustomDomainConfig?: CustomDomainConfigType;
}
interface CreateUserPoolDomainCommandOutput {
/** CloudFront distribution domain name */
CloudFrontDomain?: string;
}
/**
* Update user pool domain
* Modify custom domain configuration
*/
class UpdateUserPoolDomainCommand {
constructor(input: UpdateUserPoolDomainCommandInput);
}
interface UpdateUserPoolDomainCommandInput {
/** Domain name to update */
Domain: string;
/** Updated custom domain configuration */
CustomDomainConfig: CustomDomainConfigType;
}
/**
* Get user pool domain details
* Retrieve domain configuration and status
*/
class DescribeUserPoolDomainCommand {
constructor(input: DescribeUserPoolDomainCommandInput);
}
interface DescribeUserPoolDomainCommandInput {
/** Domain name to describe */
Domain: string;
}
interface DescribeUserPoolDomainCommandOutput {
/** Domain configuration details */
DomainDescription?: DomainDescriptionType;
}
/**
* Delete user pool domain
* Removes custom domain configuration
*/
class DeleteUserPoolDomainCommand {
constructor(input: DeleteUserPoolDomainCommandInput);
}
interface DeleteUserPoolDomainCommandInput {
/** Domain name to delete */
Domain: string;
}Configure multi-factor authentication settings at the pool level.
/**
* Set user pool MFA configuration
* Configure pool-wide MFA policies and settings
*/
class SetUserPoolMfaConfigCommand {
constructor(input: SetUserPoolMfaConfigCommandInput);
}
interface SetUserPoolMfaConfigCommandInput {
/** The user pool ID */
UserPoolId: string;
/** SMS MFA configuration */
SmsMfaConfiguration?: SmsMfaConfigType;
/** Software token MFA configuration */
SoftwareTokenMfaConfiguration?: SoftwareTokenMfaConfigType;
/** MFA configuration (OFF, ON, OPTIONAL) */
MfaConfiguration?: UserPoolMfaType;
}
interface SmsMfaConfigType {
/** SMS authentication message */
SmsAuthenticationMessage?: string;
/** SMS configuration */
SmsConfiguration?: SmsConfigurationType;
}
interface SoftwareTokenMfaConfigType {
/** Whether software token MFA is enabled */
Enabled?: boolean;
}
type UserPoolMfaType = "OFF" | "ON" | "OPTIONAL";
/**
* Get user pool MFA configuration
* Retrieve current MFA settings for the pool
*/
class GetUserPoolMfaConfigCommand {
constructor(input: GetUserPoolMfaConfigCommandInput);
}
interface GetUserPoolMfaConfigCommandInput {
/** The user pool ID */
UserPoolId: string;
}
interface GetUserPoolMfaConfigCommandOutput {
/** SMS MFA configuration */
SmsMfaConfiguration?: SmsMfaConfigType;
/** Software token MFA configuration */
SoftwareTokenMfaConfiguration?: SoftwareTokenMfaConfigType;
/** Overall MFA configuration */
MfaConfiguration?: UserPoolMfaType;
}Manage user groups within user pools for role-based access control and user organization.
/**
* Create a new group in the user pool
* Groups can be assigned IAM roles and used for access control
*/
class CreateGroupCommand {
constructor(input: CreateGroupCommandInput);
}
interface CreateGroupCommandInput {
/** Name for the group (must be unique within the user pool) */
GroupName: string;
/** The user pool ID where the group will be created */
UserPoolId: string;
/** Optional description of the group */
Description?: string;
/** IAM role ARN to associate with the group */
RoleArn?: string;
/** Precedence value (higher number = higher precedence) */
Precedence?: number;
}
/**
* Get details about a specific group
* Retrieve group information including role and precedence
*/
class GetGroupCommand {
constructor(input: GetGroupCommandInput);
}
interface GetGroupCommandInput {
/** Name of the group to retrieve */
GroupName: string;
/** The user pool ID containing the group */
UserPoolId: string;
}
/**
* List all groups in a user pool
* Retrieve all groups with optional pagination
*/
class ListGroupsCommand {
constructor(input: ListGroupsCommandInput);
}
interface ListGroupsCommandInput {
/** The user pool ID */
UserPoolId: string;
/** Maximum number of groups to return */
Limit?: number;
/** Pagination token for retrieving next page */
NextToken?: string;
}
/**
* Update group properties
* Modify group description, role, or precedence
*/
class UpdateGroupCommand {
constructor(input: UpdateGroupCommandInput);
}
interface UpdateGroupCommandInput {
/** Name of the group to update */
GroupName: string;
/** The user pool ID containing the group */
UserPoolId: string;
/** Updated description */
Description?: string;
/** Updated IAM role ARN */
RoleArn?: string;
/** Updated precedence value */
Precedence?: number;
}
/**
* Delete a group from the user pool
* Removes the group and its associations
*/
class DeleteGroupCommand {
constructor(input: DeleteGroupCommandInput);
}
interface DeleteGroupCommandInput {
/** Name of the group to delete */
GroupName: string;
/** The user pool ID containing the group */
UserPoolId: string;
}
/**
* List users in a specific group
* Retrieve all users that belong to a group
*/
class ListUsersInGroupCommand {
constructor(input: ListUsersInGroupCommandInput);
}
interface ListUsersInGroupCommandInput {
/** The user pool ID */
UserPoolId: string;
/** Name of the group */
GroupName: string;
/** Maximum number of users to return */
Limit?: number;
/** Pagination token for retrieving next page */
NextToken?: string;
}Manage OAuth 2.0 resource servers for API access control and custom scopes.
/**
* Create a resource server
* Define API resources with custom scopes for OAuth 2.0
*/
class CreateResourceServerCommand {
constructor(input: CreateResourceServerCommandInput);
}
interface CreateResourceServerCommandInput {
/** The user pool ID */
UserPoolId: string;
/** Unique identifier for the resource server */
Identifier: string;
/** Name of the resource server */
Name: string;
/** List of scopes for this resource server */
Scopes?: ResourceServerScopeType[];
}
/**
* Get resource server details
* Retrieve configuration and scopes for a resource server
*/
class DescribeResourceServerCommand {
constructor(input: DescribeResourceServerCommandInput);
}
interface DescribeResourceServerCommandInput {
/** The user pool ID */
UserPoolId: string;
/** Resource server identifier */
Identifier: string;
}
/**
* List all resource servers
* Retrieve all resource servers for a user pool
*/
class ListResourceServersCommand {
constructor(input: ListResourceServersCommandInput);
}
interface ListResourceServersCommandInput {
/** The user pool ID */
UserPoolId: string;
/** Maximum number of resource servers to return */
MaxResults?: number;
/** Pagination token for retrieving next page */
NextToken?: string;
}
/**
* Update resource server configuration
* Modify name and scopes of an existing resource server
*/
class UpdateResourceServerCommand {
constructor(input: UpdateResourceServerCommandInput);
}
interface UpdateResourceServerCommandInput {
/** The user pool ID */
UserPoolId: string;
/** Resource server identifier */
Identifier: string;
/** Updated name for the resource server */
Name: string;
/** Updated scopes list */
Scopes?: ResourceServerScopeType[];
}
/**
* Delete a resource server
* Remove resource server and its associated scopes
*/
class DeleteResourceServerCommand {
constructor(input: DeleteResourceServerCommandInput);
}
interface DeleteResourceServerCommandInput {
/** The user pool ID */
UserPoolId: string;
/** Resource server identifier to delete */
Identifier: string;
}Manage tags on Cognito resources for organization and cost allocation.
/**
* List tags for a Cognito resource
* Retrieve all tags associated with a resource
*/
class ListTagsForResourceCommand {
constructor(input: ListTagsForResourceCommandInput);
}
interface ListTagsForResourceCommandInput {
/** ARN of the Cognito resource */
ResourceArn: string;
}
/**
* Add tags to a Cognito resource
* Apply key-value pairs for organization and billing
*/
class TagResourceCommand {
constructor(input: TagResourceCommandInput);
}
interface TagResourceCommandInput {
/** ARN of the Cognito resource */
ResourceArn: string;
/** Tags to add (key-value pairs) */
Tags: Record<string, string>;
}
/**
* Remove tags from a Cognito resource
* Delete specified tag keys from the resource
*/
class UntagResourceCommand {
constructor(input: UntagResourceCommandInput);
}
interface UntagResourceCommandInput {
/** ARN of the Cognito resource */
ResourceArn: string;
/** List of tag keys to remove */
TagKeys: string[];
}Manage custom attributes and schema for user pools.
/**
* Add custom attributes to user pool schema
* Define additional user attributes beyond standard ones
*/
class AddCustomAttributesCommand {
constructor(input: AddCustomAttributesCommandInput);
}
interface AddCustomAttributesCommandInput {
/** The user pool ID */
UserPoolId: string;
/** Custom attributes to add to the schema */
CustomAttributes: SchemaAttributeType[];
}Complete User Pool Setup Example:
import {
CognitoIdentityProviderClient,
CreateUserPoolCommand,
CreateUserPoolClientCommand,
CreateUserPoolDomainCommand,
SetUserPoolMfaConfigCommand
} from "@aws-sdk/client-cognito-identity-provider";
const client = new CognitoIdentityProviderClient({ region: "us-east-1" });
// 1. Create user pool
const userPool = await client.send(new CreateUserPoolCommand({
PoolName: "MyAppUserPool",
Policies: {
PasswordPolicy: {
MinimumLength: 8,
RequireUppercase: true,
RequireLowercase: true,
RequireNumbers: true,
RequireSymbols: true
}
},
AutoVerifiedAttributes: ["email"],
AliasAttributes: ["email"],
UsernameAttributes: ["email"],
EmailConfiguration: {
EmailSendingAccount: "COGNITO_DEFAULT"
},
Schema: [
{
Name: "email",
AttributeDataType: "String",
Required: true,
Mutable: true
},
{
Name: "name",
AttributeDataType: "String",
Required: true,
Mutable: true
}
],
AccountRecoverySetting: {
RecoveryMechanisms: [
{
Name: "verified_email",
Priority: 1
}
]
}
}));
const userPoolId = userPool.UserPool!.Id!;
// 2. Create app client for web application
const webClient = await client.send(new CreateUserPoolClientCommand({
UserPoolId: userPoolId,
ClientName: "MyWebApp",
GenerateSecret: false, // Public client (SPA)
RefreshTokenValidity: 30,
AccessTokenValidity: 60,
IdTokenValidity: 60,
ExplicitAuthFlows: [
"ALLOW_USER_SRP_AUTH",
"ALLOW_REFRESH_TOKEN_AUTH"
],
SupportedIdentityProviders: ["COGNITO"],
CallbackURLs: ["https://myapp.com/callback"],
LogoutURLs: ["https://myapp.com/logout"],
AllowedOAuthFlows: ["code"],
AllowedOAuthScopes: ["email", "openid", "profile"],
AllowedOAuthFlowsUserPoolClient: true,
PreventUserExistenceErrors: "ENABLED"
}));
// 3. Create app client for mobile application
const mobileClient = await client.send(new CreateUserPoolClientCommand({
UserPoolId: userPoolId,
ClientName: "MyMobileApp",
GenerateSecret: true, // Confidential client
RefreshTokenValidity: 30,
AccessTokenValidity: 60,
IdTokenValidity: 60,
ExplicitAuthFlows: [
"ALLOW_USER_PASSWORD_AUTH",
"ALLOW_USER_SRP_AUTH",
"ALLOW_REFRESH_TOKEN_AUTH"
],
ReadAttributes: ["email", "name", "phone_number"],
WriteAttributes: ["name", "phone_number"]
}));
// 4. Set up custom domain
const domain = await client.send(new CreateUserPoolDomainCommand({
Domain: "auth-myapp", // Creates auth-myapp.auth.us-east-1.amazoncognito.com
UserPoolId: userPoolId
}));
// 5. Configure MFA
await client.send(new SetUserPoolMfaConfigCommand({
UserPoolId: userPoolId,
MfaConfiguration: "OPTIONAL",
SoftwareTokenMfaConfiguration: {
Enabled: true
},
SmsMfaConfiguration: {
SmsAuthenticationMessage: "Your verification code is {####}",
SmsConfiguration: {
SnsCallerArn: "arn:aws:iam::123456789012:role/service-role/CognitoSNSRole"
}
}
}));
console.log("User Pool ID:", userPoolId);
console.log("Web Client ID:", webClient.UserPoolClient!.ClientId);
console.log("Mobile Client ID:", mobileClient.UserPoolClient!.ClientId);
console.log("Domain:", `https://${domain.CloudFrontDomain}`);