AWS IAM ExecModule

Overview

AwsIamModule brings bounded AWS Identity and Access Management operations into ValkyrAI workflows. It inventories IAM users and groups, creates and updates explicitly named identities, permanently deletes reviewed identities, and changes group memberships. The connector uses ValkyrAI's native map ABI and one verified IntegrationAccount; credentials never belong in workflow input.

The connector implements thirteen operations:

• list_users, get_user, create_user, update_user, and delete_user cover IAM user discovery and lifecycle.
• list_groups, get_group, create_group, update_group, and delete_group cover IAM group discovery, member inspection, and lifecycle.
• list_groups_for_user, add_user_to_group, and remove_user_from_group cover explicit group-membership reconciliation.

n8n's AWS IAM node provides the functional workflow reference for user and group resources, operation-driven configuration, AWS credential binding, and searchable entity selection. ValkyrAI adds strict per-operation field allowlists, verified IntegrationAccount state, bounded pagination, explicit confirmation for every mutation, confidential output classification, read-only retries, and deterministic reconciliation after ambiguous provider failures.

Usage

1. Define the exact IAM users, groups, paths, and membership changes the workflow may manage.
2. Create a dedicated least-privilege IAM principal whose policy permits only those operations and resources.
3. Store its access key ID and secret access key in an AWS IntegrationAccount; verify it and keep it in READY status.
4. Add AwsIamModule and bind that account through ExecModuleConfig.authConfig.integrationAccount.
5. Run read operations first to inventory current state and capture exact user or group names.
6. Provide only fields accepted by the selected operation. Unexpected fields fail before AWS access.
7. Set the operation-specific confirmation field to exactly true for every mutation.
8. After a timeout or transport failure, reconcile the exact user, group, or membership before replaying anything.

Never place an AWS access key, secret key, session token, or credentials object in module input. Those fields are rejected before any network request. IAM inventory, paths, identifiers, and membership state are confidential and belong only in ACL-scoped workflow state.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the thirteen documented operations.
marker	string	Optional list field	None	Opaque IAM continuation marker, at most 2,048 characters.
limit	integer	Optional list field	100	Total result bound from 1 through 10,000.
returnAll	boolean	Optional list field	false	Follow pages until limit, exhaustion, or 100 pages.
pathPrefix	string	Optional list_users / list_groups filter	None	Absolute IAM path, beginning and ending with /, at most 512 characters.
userName	string	User, membership, and user-group operations	None	1-64 IAM name characters: letters, digits, _+=,.@-.
newUserName	string	Optional update_user replacement	None	Same rules as userName; at least one update field is required.
groupName	string	Group and membership operations	None	1-128 IAM name characters: letters, digits, _+=,.@-.
newGroupName	string	Optional update_group replacement	None	Same rules as groupName; at least one update field is required.
path	string	Optional user/group create field	Provider root	Absolute IAM path, beginning and ending with /.
newPath	string	Optional user/group update field	Unchanged	Absolute IAM path, beginning and ending with /.
confirmCreate	boolean	create_user, create_group	false	Must be exactly true.
confirmUpdate	boolean	update_user, update_group	false	Must be exactly true.
confirmDelete	boolean	delete_user, delete_group	false	Must be exactly true; deletion is permanent.
confirmMembershipChange	boolean	Add/remove membership	false	Must be exactly true.

get_group is a paginated member read: data contains the group summary and items contains bounded user summaries. list_groups_for_user returns group summaries for one exact user.

Outputs

Every call 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 including pages and retry-safe reads.
resultType	string	Success	User, group, member, or mutation-result family.
items	array	List/member success	Bounded user or group summaries.
count	integer	Items are present	Number of returned summaries.
pages	integer	Paginated success	Provider pages consumed.
hasMore	boolean	Paginated success	Whether AWS returned another marker.
marker	string	Another page exists	Opaque continuation marker.
data	object	Single read or mutation success	Normalized entity or acceptance receipt.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

User summaries contain bounded userName, userId, arn, path, creation/password-use timestamps, and permissions-boundary metadata when AWS returns it. Group summaries contain bounded groupName, groupId, arn, path, and creation time. Mutation receipts contain only the expected resulting state and never credentials or provider exception text.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / IAM
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 for the reviewed workflow:

• User reads: iam:ListUsers and iam:GetUser.
• User lifecycle: iam:CreateUser, iam:UpdateUser, and iam:DeleteUser on approved paths and names.
• Group reads: iam:ListGroups, iam:GetGroup, and iam:ListGroupsForUser.
• Group lifecycle: iam:CreateGroup, iam:UpdateGroup, and iam:DeleteGroup on approved paths and names.
• Membership changes: iam:AddUserToGroup and iam:RemoveUserFromGroup for explicit users and groups.

IAM list actions may require account-level resource scope because AWS does not support resource-level permissions for every list API. Use IAM policy conditions, permission boundaries, service control policies, separate accounts, and operator review to reduce blast radius.

The connector currently supports a long-lived access-key pair. STS session credentials, role assumption, workload identity, access-key lifecycle, console passwords, MFA devices, policies, roles, service-linked roles, instance profiles, tags, permission simulation, credential reports, account aliases, signing certificates, SSH public keys, and server certificates are intentionally deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, name, path, pagination, and safety fields belong in mapped input or module parameters.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-iam-production"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"add_user_to_group\"}"
  }
}

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_users	Lists bounded user summaries, optionally below pathPrefix.	Read-only; each page retries transient failures.
get_user	Reads one exact IAM user and boundary metadata.	Read-only; bounded retry.
create_user	Creates one named user at the optional path.	Confirmed identity mutation; exactly one attempt.
update_user	Renames or moves one exact user.	Confirmed identity mutation; exactly one attempt.
delete_user	Permanently deletes one exact user.	Destructive; confirmation and exactly one attempt.
list_groups	Lists bounded group summaries, optionally below pathPrefix.	Read-only; each page retries transient failures.
get_group	Reads group metadata and bounded member users.	Read-only; opaque pagination and bounded retry.
create_group	Creates one named group at the optional path.	Confirmed identity mutation; exactly one attempt.
update_group	Renames or moves one exact group.	Confirmed identity mutation; exactly one attempt.
delete_group	Permanently deletes one exact empty group.	Destructive; confirmation and exactly one attempt.
list_groups_for_user	Lists bounded groups containing one exact user.	Read-only; opaque pagination and bounded retry.
add_user_to_group	Adds one exact user to one exact group.	Confirmed membership mutation; exactly one attempt.
remove_user_from_group	Removes one exact user from one exact group.	Confirmed membership mutation; exactly one attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/malformed name, path, pagination value, update field, or confirmation.	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_IAM_HTTP_400	Invalid input, existing entity, missing entity, delete conflict, or policy constraint.	Reads may retry only selected transient codes	Inspect the exact IAM entity state and request ID.
AWS_IAM_HTTP_403	IAM, permission-boundary, SCP, or account policy denied the request.	No	Grant only the missing action or revise the reviewed workflow.
AWS_IAM_HTTP_404	User or group no longer exists.	No	Reconcile the exact entity name.
AWS_IAM_HTTP_429 / 500 / 503	Throttle or transient provider pressure.	Reads retry; mutations report ambiguity	Inspect the exact entity or membership before replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reads retry; mutations report ambiguity	Treat provider acceptance as unknown until state is checked.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve operation and request evidence for investigation.

Provider exception messages are never copied into workflow output. This prevents credentials, entity details, policy context, or provider diagnostics from leaking through errors.

Example

Add an existing automation user to a reviewed least-privilege group:

{
  "operation": "add_user_to_group",
  "userName": "workflow-auditor",
  "groupName": "ReadOnlyAuditors",
  "confirmMembershipChange": true
}

Expected result shape:

{
  "status": "success",
  "operation": "add_user_to_group",
  "attempts": 1,
  "resultType": "membership_change",
  "data": {
    "accepted": true,
    "expectedMembership": "present"
  },
  "requestId": "aws-request-reference"
}

The receipt proves only that AWS accepted the request. Verify the result with get_group or list_groups_for_user before treating the membership as current.

Notes

• Pagination: list_users, list_groups, get_group, and list_groups_for_user return one page unless returnAll=true; the connector follows opaque markers with unchanged filters and stops at limit, exhaustion, or 100 pages.
• Rate limits: IAM quotas vary by account and action. Read calls use at most five configured attempts with bounded backoff. Identity and membership mutations never retry automatically.
• API limits: the connector bounds aggregate results at 10,000, pages at 100, provider page requests at 1,000 items, markers at 2,048 characters, names at AWS limits, and paths at 512 characters. AWS can return fewer items than requested even when another marker exists.
• Idempotency: list/get operations are safe to retry. Create, update, delete, add, and remove operations are single-attempt and must be reconciled by exact name after an ambiguous response.
• Destructive behavior: user and group deletion is permanent. AWS rejects deleting users with attached resources or groups with members; this connector does not cascade cleanup.
• Global service: IAM uses AWS's global service endpoint. The connector does not accept a caller-controlled region or endpoint, preventing credential forwarding to an arbitrary host.
• Output privacy: IAM identities, paths, ARNs, boundaries, memberships, and request IDs are classified as confidential workflow output.
• External verification: no live AWS call is made by the repository test suite. Provider behavior requires a separately authorized least-privilege AWS account and reviewed test identities.