Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 70 ยท Identity and access management

IAM Users, Groups and Roles

Learn who can act in AWS: IAM users, groups and roles, trust relationships, STS temporary credentials and why long-lived access keys are a last resort, with a runnable role-assumption emulator.

AWS Identity and Access Management (IAM) answers two questions for every API call: who is asking? and are they allowed? This lesson covers the first question, the identities. The next lessons, starting with Writing IAM Policies, cover the second.

IAM is free, global (it is not tied to a Region) and the foundation of everything else in AWS. A weak IAM setup undermines every other security measure, so it is worth understanding the pieces properly before you build anything. The CLI snippets below are real and read-only; the runnable examples are Python stand-ins that model how roles and temporary credentials behave. They are not the real IAM or STS services.

Principals and identities

A principal is anything that can make a request to AWS: a person, an application, an AWS service or another account. IAM offers these identity types:

  • The root user of the account (see Creating and Securing an Account).
  • IAM users: an identity with long-term credentials, meant for one person or one application.
  • IAM groups: a collection of users, used to give them the same permissions.
  • IAM roles: an identity with permissions but no long-term credentials. Someone or something assumes the role and receives temporary credentials.

Every identity is named by an ARN (Amazon Resource Name), for example arn:aws:iam::123456789012:user/maya or arn:aws:iam::123456789012:role/ReportReader. The account number sits in the middle.

Users and groups

An IAM user has a name and can have a console password and up to two access keys. A user starts with no permissions at all: until a policy is attached, every request is denied.

A group is a convenience, nothing more. You attach policies to the group and every member receives them. A user can be in several groups, and the permissions add up. Groups cannot contain other groups, and a group is not an identity that can make requests, so it cannot appear as a principal in a policy.

Terminal
aws iam create-group --group-name Developers
aws iam attach-group-policy --group-name Developers \
  --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess
aws iam create-user --user-name maya
aws iam add-user-to-group --user-name maya --group-name Developers

For people, modern guidance is to avoid IAM users entirely and use IAM Identity Center (single sign-on with your company directory), as mentioned in Console, CLI and SDKs. IAM users remain useful for a few legacy cases, but think of them as the exception.

Roles and temporary credentials

A role is like a costume with a badge. It has permissions, and whoever is allowed to put it on gets the badge for a limited time. Roles solve three common needs:

  • AWS services acting for you, for example a Lambda function that must write to a table. The function assumes a role; no keys are stored anywhere.
  • Applications on compute, such as an EC2 instance, which receives its role through an instance profile.
  • People and accounts: a user in one account takes a role in another, or a federated user from your identity provider takes a role.

Two policies define a role:

  1. The trust policy says who may assume the role (the trusted principals).
  2. The permissions policies say what the role can do once assumed.

A trust policy that lets the Lambda service use a role looks like this:

JSON
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Service": "lambda.amazonaws.com" },
    "Action": "sts:AssumeRole"
  }]
}

Assuming a role is a call to the AWS Security Token Service (STS):

Terminal
aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/ReportReader \
  --role-session-name maya-reports \
  --duration-seconds 3600

STS answers with an access key ID, a secret access key, a session token and an expiration time. The access key ID of such temporary credentials starts with ASIA, while long-term user keys start with AKIA. The default session lasts one hour; the allowed range is from 15 minutes up to the role's maximum session duration (which can be set as high as 12 hours). When the credentials expire they stop working, which means that a leaked temporary key is useful to an attacker for a limited time only.

sequenceDiagram
    participant U as "Principal (user or service)"
    participant S as STS
    participant R as "Role ReportReader"
    participant X as "AWS service (S3)"
    U->>S: AssumeRole(role)
    S->>R: check trust policy
    R-->>S: principal is trusted
    S-->>U: temporary credentials (expire in 1h)
    U->>X: request signed with temporary credentials
    X-->>U: allowed by the role's permissions

Assuming a role: the trust policy is checked first, then temporary credentials are issued.

Try it: a role-assumption emulator

The emulator below models the same flow. It keeps a trust list and a permission list per role, issues sessions that expire on a simulated clock, and checks every action against the session. The real services also evaluate many other policy types, which the evaluation lesson covers; here we keep to the essentials.

Python Assume a role, use it, watch it expire

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Study the outputs. The role denied the user who was not in its trust list, allowed the permitted action, denied the action outside its permissions, and refused everything once the session expired. The last line shows that a requested duration is capped by what the role allows.

Why access keys are a last resort

Long-term access keys (AKIA...) are the weakest form of credential for three reasons:

  • They do not expire. A key copied into a public repository or pasted into a chat stays valid until someone notices and deletes it.
  • They get copied. Keys live in files, environment variables, CI settings and laptops, and every copy is another place to leak from.
  • They are hard to attribute and rotate. One key shared by a team hides who did what, and rotation means updating every place that holds it.

Prefer these alternatives, roughly in this order:

  1. People: IAM Identity Center sign-in, which gives short-lived credentials.
  2. Code running on AWS: the execution role of the service (Lambda role, ECS task role, EC2 instance profile).
  3. Code outside AWS, for example a CI system: web identity federation or OpenID Connect to assume a role without stored keys (covered in the CI/CD project later).
  4. Only if nothing else works: an IAM user with an access key, kept to the permissions it needs, rotated regularly and deleted when no longer used.

Cross-account access is also a role-based pattern: account B creates a role whose trust policy names account A, and principals in A assume it. Accounts that grant access to third parties usually add an external ID condition in the trust policy, to prevent the "confused deputy" problem in which someone tricks a third party into using its access on their behalf.

The second stand-in audits a set of users and keys the way a security review would: it flags the old keys, the users without MFA and the users who have keys when a role would do.

Python Audit users and access keys

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Creating a role and fixing the usual errors

Creating a role takes two documents: the trust policy (who may assume the role) and one or more permission policies (what the role may do). Read-only CLI:

Terminal
aws iam create-role --role-name ReportReader \
  --assume-role-policy-document file://trust.json
aws iam attach-role-policy --role-name ReportReader \
  --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess
aws sts assume-role --role-arn arn:aws:iam::123456789012:role/ReportReader \
  --role-session-name alice-test

Common problems:

  • EntityAlreadyExists: role names must be unique in the account, and comparing is case-insensitive, so ReportReader and reportreader clash. Choose another name, or update the existing role (update-assume-role-policy) instead of creating it again.
  • MalformedPolicyDocument on create-role: the trust policy JSON is invalid, or its Principal points to an account or role that does not exist.
  • AccessDenied on sts:AssumeRole: a misconfigured trust policy is the most common cause. Either the caller is not listed as a principal, or a Condition (external ID, MFA, source IP) is not met. Also check that the caller's own identity policy allows sts:AssumeRole for that role, unless the trust policy names the caller's exact user or role directly in the same account.
  • Principal shown as AIDA... or AROA...: the trust policy refers to a user or role that was deleted. AWS replaced the name with its unique ID. Update the policy.
  • Web identities: an OIDC provider (for example the one EKS or a CI system provides) uses sts:AssumeRoleWithWebIdentity, and the trust policy should pin the token's aud and sub claims. A trust policy that accepts any subject lets any workflow from that provider assume your role.
  • Session limits: the default session lasts one hour, and a role can allow up to twelve. Role chaining (a role assuming another role) is capped at one hour.

The checker below applies the same logic to a trust policy: is the caller a listed principal, and are the conditions met?

Python Debugging a trust policy

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the trust policy of a role control?

    The trust policy names who may assume the role. Permissions policies on the role say what it may do.
  2. 2. Which is true of IAM groups?

    Groups only collect users to share policies. They cannot be nested and cannot make requests or be principals.
  3. 3. An access key ID starts with ASIA. What does that tell you?

    Temporary STS credentials have access key IDs starting with ASIA, and a session token goes with them. Long-term user keys start with AKIA.
  4. 4. A Lambda function needs to read a DynamoDB table. What is the best way to give it access?

    The function assumes its execution role and receives temporary credentials automatically, so no keys have to be stored.
  5. 5. Why are long-term access keys considered a last resort?

    A long-term key stays valid until it is deleted, and copies spread to files and tools. Temporary credentials limit the damage of a leak.

Summary

  • IAM identities are the root user, users, groups and roles; a new user has no permissions until a policy is attached.
  • Groups only bundle users for shared permissions and cannot be principals.
  • A role has a trust policy (who can assume it) and permissions policies (what it can do); assuming it returns temporary credentials from STS.
  • Prefer SSO for people, execution roles for code on AWS and federation for CI; use long-term keys only as a last resort, rotated and minimal.
  • Cross-account access works by creating a role in one account that trusts the other.

Next: Writing IAM Policies.