AWS Cognito ExecModule

Overview

AwsCognitoModule brings governed Amazon Cognito user-pool administration into ValkyrAI workflows. It covers the user, group, membership, and user-pool operations in n8n's AWS Cognito node while adding verified IntegrationAccount enforcement, exact region and pool scoping, bounded attributes and pagination, read-only retry, single-attempt mutations, explicit permanent-delete confirmation, normalized output, credential redaction, and annotation-backed Workflow Studio discovery.

The connector implements thirteen operations:

• list_groups, get_group, create_group, update_group, and confirmed delete_group.
• list_users, get_user, create_user, update_user, and confirmed delete_user.
• add_user_to_group and remove_user_from_group.
• get_user_pool for reviewed pool discovery.

The module operates only on an existing user pool. It does not create pools, configure hosted UI domains, issue tokens, authenticate end users, manage app clients, reset passwords, or change MFA and security policy.

Usage

1. Create a dedicated AWS IAM principal restricted to the exact Cognito user pool and operations the workflow needs.
2. Store its access key ID and secret access key in an AWS IntegrationAccount, verify the account, and keep it in READY status.
3. Add AwsCognitoModule to a workflow and bind the account through ExecModuleConfig.authConfig.integrationAccount.
4. Select an exact AWS region and a userPoolId beginning with that region.
5. Supply username, groupName, attributes, or pagination fields only when the chosen operation accepts them.
6. Require human or policy review before identity creation, attribute changes, membership changes, or deletion.

Never place AWS credentials, end-user passwords, access tokens, ID tokens, refresh tokens, client secrets, or session tokens in module input. Credential-like input fields are rejected before provider access. A temporary password can be supplied only to create_user; it is not returned or logged.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the thirteen documented operations.
region	string	Every execution	None	AWS region such as us-west-2; custom endpoints are not accepted.
userPoolId	string	Every execution	None	Cognito pool syntax such as us-west-2_example123; the prefix must match region.
username	string	User and membership operations	None	Non-blank, no whitespace/control characters, at most 128 characters.
groupName	string	Group and membership operations	None	Non-blank, no whitespace/control characters, at most 128 characters.
attributes	object	Required for update_user; optional for create_user	{}	One to 50 flat string pairs; names at most 64 and values at most 2,048 characters.
temporaryPassword	string	Optional for create_user	Cognito policy	At most 256 characters; never returned.
suppressMessage	boolean	Optional for create_user	false	When true, asks Cognito not to send its invitation message.
forceAliasCreation	boolean	Optional for create_user	false	Can move a verified email/phone alias under Cognito rules; review carefully.
filter	string	Optional for list_users	None	One Cognito filter expression, at most 256 characters.
paginationToken	string	Optional for list operations	None	Opaque token, at most 2,048 characters; use only with unchanged list criteria.
maxResults	integer	Optional for list operations	60	From 1 through 60. The connector returns one provider page per execution.
description	string	Optional for group create/update	None	At most 2,048 characters.
precedence	integer	Optional for group create/update	None	From 0 through 1,000.
roleArn	string	Optional for group create/update	None	IAM role ARN for the Cognito group.
confirm	boolean	delete_user, delete_group	false	Must be exactly true before permanent deletion.

Operation-specific fields fail closed. For example, filter is rejected outside list_users, pagination fields are rejected outside list operations, attributes are rejected outside user create/update, and group configuration is rejected outside group create/update.

Outputs

Every execution returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls. Reads use at most three; mutations use exactly one.
resultType	string	Success	users, user, groups, group, userPool, membership, or mutation.
items	array	List success	Bounded normalized users or groups.
count	integer	List success	Number of returned items.
paginationToken	string	Another page exists	Opaque Cognito continuation token.
data	object	Non-list success	Normalized resource or mutation receipt.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation and support.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

User output can contain username, status, enabled, timestamps, and up to 50 normalized attributes. Group output can contain its name, description, role ARN, precedence, and timestamps. User-pool output is deliberately limited to identity, name, ARN, state, domains, MFA mode, deletion protection, timestamps, and estimated user count.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / Cognito User Pools
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the actions enabled in the workflow:

• Read: cognito-idp:ListUsers, ListGroups, AdminGetUser, GetGroup, and DescribeUserPool.
• User lifecycle: cognito-idp:AdminCreateUser, AdminUpdateUserAttributes, and AdminDeleteUser.
• Group lifecycle: cognito-idp:CreateGroup, UpdateGroup, and DeleteGroup.
• Membership: cognito-idp:AdminAddUserToGroup and AdminRemoveUserFromGroup.

Scope resource-level grants to the exact user-pool ARN when AWS supports it. The current connector supports a long-lived access-key pair. Temporary session credentials, STS role assumption, workload identity, VPC endpoint overrides, and custom AWS partitions beyond standard, GovCloud, and China region syntax are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, pool, region, and identity fields belong in mapped input or module parameters.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-cognito-production"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"list_users\",\"region\":\"us-west-2\",\"userPoolId\":\"us-west-2_example123\",\"maxResults\":25}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_groups	Returns one bounded page of groups.	Read-only; retries retryable failures up to three attempts.
get_group	Retrieves one exact group.	Read-only; bounded retry.
create_group	Creates a group with optional description, precedence, and role.	Single attempt; reconcile the exact group name before replay.
update_group	Replaces supplied group fields.	Single attempt; reconcile with get_group before replay.
delete_group	Permanently deletes one group after confirm=true.	Destructive, single attempt, no automatic replay.
list_users	Returns one bounded filtered page of users.	Read-only; bounded retry.
get_user	Retrieves one exact user.	Read-only; bounded retry.
create_user	Creates one administrative user and optional attributes.	Single attempt; can send an invitation unless suppressed.
update_user	Writes one or more user attributes.	Single attempt; reconcile with get_user before replay.
delete_user	Permanently deletes one user after confirm=true.	Destructive, single attempt, no automatic replay.
add_user_to_group	Adds an existing user to an existing group.	Single attempt; reconcile membership before replay.
remove_user_from_group	Removes an existing user from a group.	Single attempt; reconcile membership before replay.
get_user_pool	Returns bounded user-pool metadata.	Read-only; bounded retry.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/malformed pool, region, identity, attribute, pagination, group option, or confirmation; unexpected operation field.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_COGNITO_HTTP_400	Invalid pool/resource, alias conflict, password policy, immutable attribute, or Cognito constraint.	Usually no	Inspect the operation, exact identity state, and current pool policy.
AWS_COGNITO_HTTP_403	IAM denies the selected action or user pool.	No	Grant only the missing action on the intended pool.
AWS_COGNITO_HTTP_404	User, group, or pool no longer exists.	No	Reconcile identifiers before deciding whether to create or stop.
AWS_COGNITO_HTTP_429 / 500 / 503	Throttle or transient provider pressure.	Reads retry; mutations report ambiguity	Reconcile mutation state using a read before any replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reads retry; mutations report ambiguity	Treat acceptance as unknown and inspect AWS state before replay.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve the operation, pool, identity, and request evidence.

Provider exception text is never copied into output, preventing credentials, temporary passwords, aliases, or unbounded provider payloads from leaking through workflow errors.

Example

Create a reviewed support identity without sending Cognito's automatic invitation:

{
  "operation": "create_user",
  "region": "us-west-2",
  "userPoolId": "us-west-2_example123",
  "username": "support-agent-1042",
  "attributes": {
    "email": "agent@example.com",
    "email_verified": "true",
    "custom:team": "support"
  },
  "temporaryPassword": "provided-through-an-approved-secret-step",
  "suppressMessage": true,
  "forceAliasCreation": false
}

Expected result shape:

{
  "status": "success",
  "operation": "create_user",
  "attempts": 1,
  "resultType": "user",
  "data": {
    "username": "support-agent-1042",
    "status": "FORCE_CHANGE_PASSWORD",
    "enabled": true,
    "attributes": {
      "email": "agent@example.com",
      "email_verified": "true",
      "custom:team": "support"
    }
  },
  "requestId": "aws-request-reference"
}

The temporary password is deliberately absent from output. A separate reviewed workflow can assign the user to a group after verifying the create receipt.

Notes

• Pagination: list_users and list_groups return one Cognito page. Preserve the returned token with the same pool, filter, and page size; tokens are opaque and may expire.
• Rate limits: Cognito quotas vary by category, account, and region. Read calls use at most three attempts with short bounded backoff. Mutations never retry automatically.
• API limits: ValkyrAI caps each list page at 60, each attribute map at 50 entries, and output to the provider's single bounded page. These constraints are intentionally conservative.
• Idempotency: reads are replay-safe. User/group creation, updates, membership changes, message delivery, alias movement, and deletion can have side effects and are single-attempt.
• Ambiguous writes: if transport fails after AWS accepts a mutation, reconcile the exact username/group through a read or audited AWS event before replaying.
• Destructive behavior: delete_user and delete_group permanently remove identity resources and require confirm=true. The connector does not delete user pools.
• Messaging: create_user may send Cognito's configured invitation. Set suppressMessage=true only when another approved onboarding channel owns delivery.
• Alias movement: forceAliasCreation=true can transfer a verified email or phone alias from another user. Treat it as an identity-impacting change requiring review.
• Security: returned attributes can contain personal data. Keep output within an ACL-scoped workflow and avoid logging entire records.
• Provider verification boundary: deterministic tests cover validation, exact region/pool scope, all operation families, pagination, attribute normalization, password non-echo, retry boundaries, deletion confirmation, provider-error redaction, registration, and metadata. Live AWS behavior remains unverified until an authorized Cognito credential and reviewed test pool are supplied.
• Functional reference: n8n's AWS Cognito node exposes group create/get/list/update/delete, user create/get/list/update/delete, membership add/remove, and user-pool get. ValkyrAI preserves that surface with stronger account, scope, replay, output, and deletion controls.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsCognitoModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS Lambda ExecModule
• AWS DynamoDB ExecModule
• AWS Bedrock ExecModule
• n8n AWS Cognito reference
• Amazon Cognito User Pools API
• Integration Account Console