AWS IAM via SDK: Users, Roles & Policies

Q: How can I test a policy before relying on it?

Use SimulatePrincipalPolicy to check whether a principal would be allowed a given action on a given resource, without performing the action itself.

IAM is the identity and permission layer that authorizes every other AWS call.

This page builds the core pieces from code: a scoped, least-privilege policy, and a role that trusts a service and carries that policy. It then verifies the wiring and cleans up.

Roles are the identity applications should use, so this quickstart focuses on a role rather than a user with static keys.

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import json, boto3
 
iam = boto3.client("iam")
 
# A role that the Lambda service can assume.
trust = {"Version": "2012-10-17", "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "lambda.amazonaws.com"},
    "Action": "sts:AssumeRole"}]}
 
role = iam.create_role(
    RoleName="report-reader",
    AssumeRolePolicyDocument=json.dumps(trust),
)["Role"]
print("role arn:", role["Arn"])

// --- TypeScript (AWS SDK v3) ---
import { IAMClient, CreateRoleCommand } from "@aws-sdk/client-iam";
 
const iam = new IAMClient({});
 
// A role that the Lambda service can assume.
const trust = { Version: "2012-10-17", Statement: [{
  Effect: "Allow",
  Principal: { Service: "lambda.amazonaws.com" },
  Action: "sts:AssumeRole" }] };
 
const { Role } = await iam.send(new CreateRoleCommand({
  RoleName: "report-reader",
  AssumeRolePolicyDocument: JSON.stringify(trust),
}));
console.log("role arn:", Role?.Arn);

When to reach for this:

Giving an application or AWS service exactly the permissions it needs.
Automating role and policy creation as part of provisioning.
Building least-privilege identities for functions, tasks, and instances.
Learning the IAM API before wrapping it in IaC.

Working Example

Create a scoped customer-managed policy, create a role that a service can assume, attach the policy, confirm the attachment, then clean up in the correct order.

# --- Python (boto3) ---
import json, boto3
 
iam = boto3.client("iam")
 
# 1. A least-privilege policy: read one bucket, nothing else.
perm = {"Version": "2012-10-17", "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:GetObject"],
    "Resource": "arn:aws:s3:::reports-bucket/*"}]}
policy = iam.create_policy(
    PolicyName="read-reports-bucket",
    PolicyDocument=json.dumps(perm),
)["Policy"]
 
# 2. A role the Lambda service may assume.
trust = {"Version": "2012-10-17", "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "lambda.amazonaws.com"},
    "Action": "sts:AssumeRole"}]}
iam.create_role(RoleName="report-reader",
    AssumeRolePolicyDocument=json.dumps(trust))
 
# 3. Attach the policy and confirm.
iam.attach_role_policy(RoleName="report-reader",
    PolicyArn=policy["Arn"])
attached = iam.list_attached_role_policies(RoleName="report-reader")
print([p["PolicyName"] for p in attached["AttachedPolicies"]])
 
# 4. Clean up in order: detach, then delete policy and role.
iam.detach_role_policy(RoleName="report-reader", PolicyArn=policy["Arn"])
iam.delete_policy(PolicyArn=policy["Arn"])
iam.delete_role(RoleName="report-reader")

// --- TypeScript (AWS SDK v3) ---
import {
  IAMClient, CreatePolicyCommand, CreateRoleCommand, AttachRolePolicyCommand,
  ListAttachedRolePoliciesCommand, DetachRolePolicyCommand, DeletePolicyCommand, DeleteRoleCommand,
} from "@aws-sdk/client-iam";
 
const iam = new IAMClient({});
 
// 1. A least-privilege policy: read one bucket, nothing else.
const perm = { Version: "2012-10-17", Statement: [{
  Effect: "Allow",
  Action: ["s3:GetObject"],
  Resource: "arn:aws:s3:::reports-bucket/*" }] };
const { Policy } = await iam.send(new CreatePolicyCommand({
  PolicyName: "read-reports-bucket",
  PolicyDocument: JSON.stringify(perm),
}));
 
// 2. A role the Lambda service may assume.
const trust = { Version: "2012-10-17", Statement: [{
  Effect: "Allow",
  Principal: { Service: "lambda.amazonaws.com" },
  Action: "sts:AssumeRole" }] };
await iam.send(new CreateRoleCommand({
  RoleName: "report-reader",
  AssumeRolePolicyDocument: JSON.stringify(trust),
}));
 
// 3. Attach the policy and confirm.
await iam.send(new AttachRolePolicyCommand({ RoleName: "report-reader", PolicyArn: Policy!.Arn }));
const attached = await iam.send(new ListAttachedRolePoliciesCommand({ RoleName: "report-reader" }));
console.log((attached.AttachedPolicies ?? []).map((p) => p.PolicyName));
 
// 4. Clean up in order: detach, then delete policy and role.
await iam.send(new DetachRolePolicyCommand({ RoleName: "report-reader", PolicyArn: Policy!.Arn }));
await iam.send(new DeletePolicyCommand({ PolicyArn: Policy!.Arn }));
await iam.send(new DeleteRoleCommand({ RoleName: "report-reader" }));

What this demonstrates:

A policy is a JSON document of Effect, Action, and Resource - here scoped to one bucket.
A role carries two policy layers: a trust policy (who may assume) and permission policies (what it may do).
AttachRolePolicy binds a reusable customer-managed policy to the role by ARN.
Deletion has an order: detach the policy before deleting the policy or the role.

Deep Dive

The Three Building Blocks

A policy is a permission document. Managed policies are reusable and attachable by ARN; inline policies live inside a single identity.
A role is an identity with no long-lived credentials that a trusted principal assumes to get temporary credentials.
A user is an identity for a person or legacy workload, optionally with long-lived access keys - avoid these for applications.

Trust Policy vs Permission Policy

Every role answers two separate questions, and they are debugged separately.

The trust policy (AssumeRolePolicyDocument) answers who may assume the role - a service, an account, or a specific principal.
The permission policies answer what the role can do once assumed.

A broad permission policy is useless if the trust policy blocks the caller, and vice versa.

Verifying What a Policy Allows

Rather than guessing, simulate a policy decision before you rely on it.

# --- Python (boto3) ---
res = iam.simulate_principal_policy(
    PolicySourceArn="arn:aws:iam::111122223333:role/report-reader",
    ActionNames=["s3:GetObject"],
    ResourceArns=["arn:aws:s3:::reports-bucket/report.pdf"],
)
print(res["EvaluationResults"][0]["EvalDecision"])   # allowed / implicitDeny

// --- TypeScript (AWS SDK v3) ---
import { SimulatePrincipalPolicyCommand } from "@aws-sdk/client-iam";
 
const res = await iam.send(new SimulatePrincipalPolicyCommand({
  PolicySourceArn: "arn:aws:iam::111122223333:role/report-reader",
  ActionNames: ["s3:GetObject"],
  ResourceArns: ["arn:aws:s3:::reports-bucket/report.pdf"],
}));
console.log(res.EvaluationResults?.[0].EvalDecision);   // allowed / implicitDeny

The simulator answers "would this be allowed?" without performing the action, which is ideal for testing least-privilege policies.

Gotchas

Deleting a role or policy still in use - deletion fails while a policy is attached or a role is still referenced. Fix: detach policies first, then delete the policy and the role.
Confusing trust and permission policies - broad permissions do not help if the trust policy blocks the caller. Fix: debug them separately; trust decides who, permissions decide what.
Over-broad policies - "Action": "*" on "Resource": "*" turns any leak into a full compromise. Fix: scope actions and resource ARNs to exactly what the workload needs.
Using a user with access keys for an app - long-lived keys leak and rarely rotate. Fix: create a role and let the service assume it; reserve users for humans or legacy cases.
Waiting on eventual consistency - a freshly created role may not be immediately usable by another service. Fix: retry the dependent call, or use a waiter where one exists.
Reusing one role everywhere - a shared broad role widens the blast radius. Fix: give each workload its own least-privilege role.

Alternatives

Alternative	Use When	Don't Use When
Role + managed policy (this page)	Applications and services needing scoped access	A one-off permission for a single identity
Inline policy on a role/user	A policy that should live and die with one identity	You want to reuse the policy across identities
AWS-managed policy	A common, AWS-maintained permission set fits	You need tightly scoped, custom permissions
IAM user + access keys	No role path exists at all	Any role-based option is available
IAM Identity Center (SSO)	Human and CLI federated access	Machine workloads on AWS compute

FAQs

What is the difference between a policy, a role, and a user?

A policy is a permission document. A role is an assumable identity with no permanent credentials that carries policies. A user is an identity for a person or legacy app, optionally with long-lived keys.

What are the two policies every role has?

A trust policy that says who may assume the role, and one or more permission policies that say what the role can do once assumed. They are configured and debugged separately.

Managed or inline policy?

Use a customer-managed policy when you want to reuse and version a permission set across identities. Use an inline policy when the permission should live and die with a single identity.

Why did my role deletion fail?

A role cannot be deleted while policies are attached (and a policy cannot be deleted while attached to any identity). Detach first, then delete the policy and the role.

How do I scope a policy to least privilege?

List only the specific actions the workload calls, and restrict Resource to the exact ARNs involved. Avoid "*" for actions or resources unless truly required.

How can I test a policy before relying on it?

Use SimulatePrincipalPolicy to check whether a principal would be allowed a given action on a given resource, without performing the action itself.

Should my application use a user or a role?

A role. Applications on EC2, ECS, Lambda, or EKS assume a role and receive rotating temporary credentials, so there is no static key to leak. Reserve users for humans or legacy cases.

What does the trust policy Principal mean?

It names who is allowed to assume the role - a service like lambda.amazonaws.com, an AWS account, or a specific role or user ARN. STS refuses the assume if the caller is not listed.

Why does my new role not work immediately elsewhere?

IAM is eventually consistent. A newly created role or attachment can take a moment to propagate, so a dependent call may need a short retry.

Can one policy attach to many roles?

Yes. That is the point of a customer-managed policy: create it once and attach it by ARN to any number of roles or users, updating it in one place.

Amazon EC2 via SDK: Your First Instance - attach a role to an instance via an instance profile.
AWS Lambda via SDK: Your First Function - the execution role a function assumes.
Amazon S3 via SDK: Buckets & Objects - the resource this page's policy scopes access to.
Core AWS Services Best Practices - least-privilege defaults across services.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

This page builds the core pieces from code: a scoped, least-privilege policy, and a role that trusts a service and carries that policy. It then verifies the wiring and cleans up.

Roles are the identity applications should use, so this quickstart focuses on a role rather than a user with static keys.

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import json, boto3
 
iam = boto3.client("iam")
 
# A role that the Lambda service can assume.
trust = {"Version": "2012-10-17", "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "lambda.amazonaws.com"},
    "Action": "sts:AssumeRole"}]}
 
role = iam.create_role(
    RoleName="report-reader",
    AssumeRolePolicyDocument=json.dumps(trust),
)["Role"]
print("role arn:", role["Arn"])

// --- TypeScript (AWS SDK v3) ---
import { IAMClient, CreateRoleCommand } from "@aws-sdk/client-iam";
 
const iam = new IAMClient({});
 
// A role that the Lambda service can assume.
const trust = { Version: "2012-10-17", Statement: [{
  Effect: "Allow",
  Principal: { Service: "lambda.amazonaws.com" },
  Action: "sts:AssumeRole" }] };
 
const { Role } = await iam.send(new CreateRoleCommand({
  RoleName: "report-reader",
  AssumeRolePolicyDocument: JSON.stringify(trust),
}));
console.log("role arn:", Role?.Arn);

When to reach for this:

Giving an application or AWS service exactly the permissions it needs.
Automating role and policy creation as part of provisioning.
Building least-privilege identities for functions, tasks, and instances.
Learning the IAM API before wrapping it in IaC.

Working Example

Create a scoped customer-managed policy, create a role that a service can assume, attach the policy, confirm the attachment, then clean up in the correct order.

# --- Python (boto3) ---
import json, boto3
 
iam = boto3.client("iam")
 
# 1. A least-privilege policy: read one bucket, nothing else.
perm = {"Version": "2012-10-17", "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:GetObject"],
    "Resource": "arn:aws:s3:::reports-bucket/*"}]}
policy = iam.create_policy(
    PolicyName="read-reports-bucket",
    PolicyDocument=json.dumps(perm),
)["Policy"]
 
# 2. A role the Lambda service may assume.
trust = {"Version": "2012-10-17", "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "lambda.amazonaws.com"},
    "Action": "sts:AssumeRole"}]}
iam.create_role(RoleName="report-reader",
    AssumeRolePolicyDocument=json.dumps(trust))
 
# 3. Attach the policy and confirm.
iam.attach_role_policy(RoleName="report-reader",
    PolicyArn=policy["Arn"])
attached = iam.list_attached_role_policies(RoleName="report-reader")
print([p["PolicyName"] for p in attached["AttachedPolicies"]])
 
# 4. Clean up in order: detach, then delete policy and role.
iam.detach_role_policy(RoleName="report-reader", PolicyArn=policy["Arn"])
iam.delete_policy(PolicyArn=policy["Arn"])
iam.delete_role(RoleName="report-reader")

// --- TypeScript (AWS SDK v3) ---
import {
  IAMClient, CreatePolicyCommand, CreateRoleCommand, AttachRolePolicyCommand,
  ListAttachedRolePoliciesCommand, DetachRolePolicyCommand, DeletePolicyCommand, DeleteRoleCommand,
} from "@aws-sdk/client-iam";
 
const iam = new IAMClient({});
 
// 1. A least-privilege policy: read one bucket, nothing else.
const perm = { Version: "2012-10-17", Statement: [{
  Effect: "Allow",
  Action: ["s3:GetObject"],
  Resource: "arn:aws:s3:::reports-bucket/*" }] };
const { Policy } = await iam.send(new CreatePolicyCommand({
  PolicyName: "read-reports-bucket",
  PolicyDocument: JSON.stringify(perm),
}));
 
// 2. A role the Lambda service may assume.
const trust = { Version: "2012-10-17", Statement: [{
  Effect: "Allow",
  Principal: { Service: "lambda.amazonaws.com" },
  Action: "sts:AssumeRole" }] };
await iam.send(new CreateRoleCommand({
  RoleName: "report-reader",
  AssumeRolePolicyDocument: JSON.stringify(trust),
}));
 
// 3. Attach the policy and confirm.
await iam.send(new AttachRolePolicyCommand({ RoleName: "report-reader", PolicyArn: Policy!.Arn }));
const attached = await iam.send(new ListAttachedRolePoliciesCommand({ RoleName: "report-reader" }));
console.log((attached.AttachedPolicies ?? []).map((p) => p.PolicyName));
 
// 4. Clean up in order: detach, then delete policy and role.
await iam.send(new DetachRolePolicyCommand({ RoleName: "report-reader", PolicyArn: Policy!.Arn }));
await iam.send(new DeletePolicyCommand({ PolicyArn: Policy!.Arn }));
await iam.send(new DeleteRoleCommand({ RoleName: "report-reader" }));

What this demonstrates:

A policy is a JSON document of Effect, Action, and Resource - here scoped to one bucket.
A role carries two policy layers: a trust policy (who may assume) and permission policies (what it may do).
AttachRolePolicy binds a reusable customer-managed policy to the role by ARN.
Deletion has an order: detach the policy before deleting the policy or the role.

Deep Dive

The Three Building Blocks

A policy is a permission document. Managed policies are reusable and attachable by ARN; inline policies live inside a single identity.
A role is an identity with no long-lived credentials that a trusted principal assumes to get temporary credentials.
A user is an identity for a person or legacy workload, optionally with long-lived access keys - avoid these for applications.

Trust Policy vs Permission Policy

Every role answers two separate questions, and they are debugged separately.

The trust policy (AssumeRolePolicyDocument) answers who may assume the role - a service, an account, or a specific principal.
The permission policies answer what the role can do once assumed.

A broad permission policy is useless if the trust policy blocks the caller, and vice versa.

Verifying What a Policy Allows

Rather than guessing, simulate a policy decision before you rely on it.

# --- Python (boto3) ---
res = iam.simulate_principal_policy(
    PolicySourceArn="arn:aws:iam::111122223333:role/report-reader",
    ActionNames=["s3:GetObject"],
    ResourceArns=["arn:aws:s3:::reports-bucket/report.pdf"],
)
print(res["EvaluationResults"][0]["EvalDecision"])   # allowed / implicitDeny

// --- TypeScript (AWS SDK v3) ---
import { SimulatePrincipalPolicyCommand } from "@aws-sdk/client-iam";
 
const res = await iam.send(new SimulatePrincipalPolicyCommand({
  PolicySourceArn: "arn:aws:iam::111122223333:role/report-reader",
  ActionNames: ["s3:GetObject"],
  ResourceArns: ["arn:aws:s3:::reports-bucket/report.pdf"],
}));
console.log(res.EvaluationResults?.[0].EvalDecision);   // allowed / implicitDeny

The simulator answers "would this be allowed?" without performing the action, which is ideal for testing least-privilege policies.

Gotchas

Deleting a role or policy still in use - deletion fails while a policy is attached or a role is still referenced. Fix: detach policies first, then delete the policy and the role.
Confusing trust and permission policies - broad permissions do not help if the trust policy blocks the caller. Fix: debug them separately; trust decides who, permissions decide what.
Over-broad policies - "Action": "*" on "Resource": "*" turns any leak into a full compromise. Fix: scope actions and resource ARNs to exactly what the workload needs.
Using a user with access keys for an app - long-lived keys leak and rarely rotate. Fix: create a role and let the service assume it; reserve users for humans or legacy cases.
Waiting on eventual consistency - a freshly created role may not be immediately usable by another service. Fix: retry the dependent call, or use a waiter where one exists.
Reusing one role everywhere - a shared broad role widens the blast radius. Fix: give each workload its own least-privilege role.

Alternatives

Alternative	Use When	Don't Use When
Role + managed policy (this page)	Applications and services needing scoped access	A one-off permission for a single identity
Inline policy on a role/user	A policy that should live and die with one identity	You want to reuse the policy across identities
AWS-managed policy	A common, AWS-maintained permission set fits	You need tightly scoped, custom permissions
IAM user + access keys	No role path exists at all	Any role-based option is available
IAM Identity Center (SSO)	Human and CLI federated access	Machine workloads on AWS compute

FAQs

What is the difference between a policy, a role, and a user?

What are the two policies every role has?

A trust policy that says who may assume the role, and one or more permission policies that say what the role can do once assumed. They are configured and debugged separately.

Managed or inline policy?

Use a customer-managed policy when you want to reuse and version a permission set across identities. Use an inline policy when the permission should live and die with a single identity.

Why did my role deletion fail?

A role cannot be deleted while policies are attached (and a policy cannot be deleted while attached to any identity). Detach first, then delete the policy and the role.

How do I scope a policy to least privilege?

List only the specific actions the workload calls, and restrict Resource to the exact ARNs involved. Avoid "*" for actions or resources unless truly required.

How can I test a policy before relying on it?

Use SimulatePrincipalPolicy to check whether a principal would be allowed a given action on a given resource, without performing the action itself.

Should my application use a user or a role?

A role. Applications on EC2, ECS, Lambda, or EKS assume a role and receive rotating temporary credentials, so there is no static key to leak. Reserve users for humans or legacy cases.

What does the trust policy Principal mean?

It names who is allowed to assume the role - a service like lambda.amazonaws.com, an AWS account, or a specific role or user ARN. STS refuses the assume if the caller is not listed.

Why does my new role not work immediately elsewhere?

IAM is eventually consistent. A newly created role or attachment can take a moment to propagate, so a dependent call may need a short retry.

Can one policy attach to many roles?

Yes. That is the point of a customer-managed policy: create it once and attach it by ARN to any number of roles or users, updating it in one place.

Amazon EC2 via SDK: Your First Instance - attach a role to an instance via an instance profile.
AWS Lambda via SDK: Your First Function - the execution role a function assumes.
Amazon S3 via SDK: Buckets & Objects - the resource this page's policy scopes access to.
Core AWS Services Best Practices - least-privilege defaults across services.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

AWS IAM via SDK: Users, Roles & Policies

Buscar en la documentación

AWS IAM via SDK: Users, Roles & Policies