AWS Identity and Access Management - User Guide

AWS Identity and Access Management - User Guide
AWS Identity and
Access Management
User Guide
AWS Identity and Access Management User Guide
AWS Identity and Access Management: User Guide
AWS Identity and Access Management User Guide
Table of Contents
What Is IAM? ..................................................................................................................................... 1
IAM Features ............................................................................................................................. 1
Accessing IAM ............................................................................................................................ 2
Overview: Users ......................................................................................................................... 3
IAM Users .......................................................................................................................... 3
Federating Existing Users .................................................................................................... 4
Overview: Permissions and Policies ............................................................................................... 5
Policies and Users .............................................................................................................. 5
Policies and Groups ............................................................................................................ 6
Federated Users and Roles .................................................................................................. 7
User-based and Resource-based Policies ............................................................................... 7
Security Features Outside of IAM ................................................................................................. 7
Quick Links to Common Tasks ..................................................................................................... 8
Getting Set Up ................................................................................................................................. 10
Using IAM to Give Users Access to Your AWS Resources ................................................................. 10
Do I Need to Sign Up for IAM? .................................................................................................. 11
Additional Resources ................................................................................................................. 11
Getting Started ................................................................................................................................ 13
Creating an IAM Admin User and Group ...................................................................................... 14
Creating an Administrator IAM User and Group (Console) ...................................................... 15
Creating an IAM User and Group (AWS CLI) ......................................................................... 15
Related Resources ............................................................................................................ 17
How Users Sign In to Your Account ............................................................................................ 17
Tutorials .......................................................................................................................................... 20
Tutorial: Delegate Access to the Billing Console ............................................................................ 20
Prerequisites .................................................................................................................... 21
Step 1: Enable Access to Billing Data on Your AWS Test Account ............................................. 21
Step 2: Create IAM Policies That Grant Permissions to Billing Data .......................................... 21
Step 3: Attach Billing Policies to Your Groups ...................................................................... 22
Step 4: Test Access to the Billing Console ............................................................................ 22
Related Resources ............................................................................................................ 23
Summary ........................................................................................................................ 24
Tutorial: Delegate Access Across AWS Accounts Using Roles ........................................................... 24
Prerequisites .................................................................................................................... 25
Step 1 - Create a Role ...................................................................................................... 25
Step 2 - Grant Access to the Role ....................................................................................... 27
Step 3 - Test Access by Switching Roles .............................................................................. 29
Related Resources ............................................................................................................ 32
Summary ........................................................................................................................ 32
Tutorial: Create a Customer Managed Policy ................................................................................ 32
Prerequisites .................................................................................................................... 33
Step 1: Create the Policy ................................................................................................... 33
Step 2: Attach the Policy ................................................................................................... 34
Step 3: Test User Access .................................................................................................... 34
Related Resources ............................................................................................................ 34
Summary ........................................................................................................................ 34
Best Practices and Use Cases ............................................................................................................. 35
Best Practices .......................................................................................................................... 35
Use AWS Defined Policies to Assign Permissions Whenever Possible ........................................ 35
Use Groups to Assign Permissions to IAM Users .................................................................... 36
Grant Least Privilege ........................................................................................................ 36
Use Access Levels to Review IAM Permissions ....................................................................... 37
Configure a Strong Password Policy for Your Users ............................................................... 37
Use Roles for Applications That Run on Amazon EC2 Instances ............................................... 37
iii
AWS Identity and Access Management User Guide
Delegate by Using Roles Instead of by Sharing Credentials .................................................... 38
Rotate Credentials Regularly .............................................................................................. 38
Remove Unnecessary Credentials ........................................................................................ 38
Use Policy Conditions for Extra Security .............................................................................. 38
Monitor Activity in Your AWS Account ................................................................................. 39
Business Use Cases ................................................................................................................... 39
Initial Setup of Example Corp ............................................................................................ 39
Use Case for IAM with Amazon EC2 .................................................................................... 40
Use Case for IAM with Amazon S3 ...................................................................................... 40
IAM Console and Sign-in Page ........................................................................................................... 43
The IAM User Sign-in Page ........................................................................................................ 43
Controlling User Access to the AWS Management Console ............................................................. 44
Your AWS Account ID and Its Alias ............................................................................................. 45
Finding Your AWS Account ID ............................................................................................ 45
About Account Aliases ...................................................................................................... 46
Creating, Deleting, and Listing an AWS Account Alias ............................................................ 46
IAM Console Search .................................................................................................................. 47
Using IAM Console Search ................................................................................................. 47
Icons in the IAM Console Search Results .............................................................................. 48
Sample Search Phrases ..................................................................................................... 48
Identities ......................................................................................................................................... 50
IAM Users ................................................................................................................................ 50
IAM Groups ............................................................................................................................. 50
IAM Roles ................................................................................................................................ 51
Temporary Credentials .............................................................................................................. 51
When to Create an IAM User (Instead of a Role) ........................................................................... 51
When to Create an IAM Role (Instead of a User) ........................................................................... 51
Users ...................................................................................................................................... 52
How AWS identifies an IAM user ........................................................................................ 52
Users and credentials ........................................................................................................ 52
Users and permissions ...................................................................................................... 53
Users and accounts ........................................................................................................... 53
Users as service accounts .................................................................................................. 54
Adding a User .................................................................................................................. 54
How IAM Users Sign In to AWS .......................................................................................... 57
Managing Users ............................................................................................................... 59
Changing Permissions for a User ........................................................................................ 62
Passwords ....................................................................................................................... 65
Access Keys ..................................................................................................................... 74
Retrieving Lost Passwords or Access Keys ............................................................................ 79
Finding Unused Credentials ............................................................................................... 79
Getting Credential Reports ................................................................................................ 82
Using IAM with AWS CodeCommit: Git Credentials, SSH Keys, and AWS Access Keys ................... 86
Working with Server Certificates ........................................................................................ 87
Groups .................................................................................................................................... 92
Creating Groups ............................................................................................................... 93
Managing Groups ............................................................................................................. 94
Roles ...................................................................................................................................... 97
Terms and Concepts ......................................................................................................... 98
Common Scenarios ......................................................................................................... 100
Identity Providers and Federation ..................................................................................... 105
Service-Linked Roles ....................................................................................................... 139
Creating Roles ................................................................................................................ 146
Using Roles .................................................................................................................... 167
Managing Roles .............................................................................................................. 183
Roles vs. Resource-based Policies ...................................................................................... 191
Temporary Security Credentials ................................................................................................ 193
iv
AWS Identity and Access Management User Guide
AWS STS and AWS Regions .............................................................................................
Common Scenarios for Temporary Credentials ...................................................................
Requesting Temporary Security Credentials ........................................................................
Using Temporary Security Credentials to Request Access to AWS Resources ............................
Controlling Permissions for Temporary Security Credentials .................................................
Activating and Deactivating AWS STS in an AWS Region ......................................................
Sample Applications That Use Temporary Credentials .........................................................
Additional Resources for Temporary Credentials .................................................................
Access Management ........................................................................................................................
Permissions ............................................................................................................................
Identity-Based (IAM) Permissions and Resource-Based Permissions ........................................
Resource Creators Do Not Automatically Have Permissions ...................................................
Granting Permissions Across AWS Accounts ........................................................................
Permissions For One Service to Access Another ..................................................................
Delegating Permissions to Administer IAM Users, Groups, and Credentials ..............................
Policies ..................................................................................................................................
Managed Policies and Inline Policies .................................................................................
Versioning for Managed Policies .......................................................................................
Deprecated AWS Managed Policies ...................................................................................
Controlling Access to Managed Policies .............................................................................
Creating IAM Policies ......................................................................................................
Working with Policies ......................................................................................................
Policy Summaries ...........................................................................................................
Testing IAM Policies ........................................................................................................
Using Policy Validator .....................................................................................................
Service Last Accessed Data ..............................................................................................
Example Policies .............................................................................................................
Additional Resources ...............................................................................................................
Logging IAM Events with AWS CloudTrail ..........................................................................................
Types of IAM Information Logged in CloudTrail ..........................................................................
Examples of Logged Events in CloudTrail Files ...........................................................................
IAM API Event in CloudTrail Log File .................................................................................
AWS STS API Event in CloudTrail Log File ..........................................................................
Sign-in Failure Event in CloudTrail Log File ........................................................................
Sign-in Failure Event Caused by Incorrect User Name ..........................................................
Sign-in Success Event in CloudTrail Log File .......................................................................
Preventing Duplicate Log Entries in CloudTrail ...........................................................................
Troubleshooting IAM .......................................................................................................................
Troubleshooting General Issues ................................................................................................
I lost my access keys. ......................................................................................................
I get "access denied" when I make a request to an AWS service. ............................................
I get "access denied" when I make a request with temporary security credentials. ....................
Policy variables aren't working. ........................................................................................
Changes that I make are not always immediately visible ......................................................
Troubleshoot Policies ..............................................................................................................
More Than One Policy Object ..........................................................................................
More Than One Statement Element ..................................................................................
More Than One Effect, Action, or Resource Element in a Statement Element ...........................
Missing Policy Summary ..................................................................................................
Policy Summary Includes Unrecognized Services, Actions, or Resource Types ..........................
Service Does Not Support IAM Policy Summaries ................................................................
My Policy Does Not Grant the Expected Permissions ...........................................................
Missing Version Element ..................................................................................................
I Can't Attach or Detach a Policy in My IAM Account ...........................................................
Troubleshooting IAM Roles ......................................................................................................
I Can't Assume a Role .....................................................................................................
A New Role Appeared in My IAM Account ..........................................................................
v
193
194
195
204
207
218
220
220
222
222
223
225
225
225
225
232
235
240
243
243
247
250
258
283
292
293
298
321
323
323
326
326
326
330
331
331
332
334
334
334
335
335
335
336
336
337
337
338
340
340
341
342
346
346
346
347
347
AWS Identity and Access Management User Guide
I Can't Edit or Delete a Role in My IAM Account .................................................................. 348
Troubleshooting Amazon EC2 and IAM ...................................................................................... 348
When attempting to launch an instance, I don't see the role I expected to see in the Amazon
EC2 console IAM role list. ................................................................................................ 348
The credentials on my instance are for the wrong role. ........................................................ 349
When I attempt to call the AddRoleToInstanceProfile, I get an AccessDenied error. ................ 349
Amazon EC2: When I attempt to launch an instance with a role, I get an AccessDenied error. ..... 349
I can't access the temporary security credentials on my EC2 instance. .................................... 350
What do the errors from the info document in the IAM subtree mean? .................................. 350
Troubleshooting Amazon S3 and IAM ........................................................................................ 351
How do I grant anonymous access to an Amazon S3 bucket? ................................................ 351
Troubleshooting SAML 2.0 Federation with AWS ......................................................................... 351
Error: Your request included an invalid SAML response. To logout, click here. ......................... 351
Error: RoleSessionName is required in AuthnResponse (Service: AWSSecurityTokenService;
Status Code: 400; Error Code: InvalidIdentityToken) ............................................................ 352
Error: Not authorized to perform sts:AssumeRoleWithSAML (Service:
AWSSecurityTokenService; Status Code: 403; Error Code: AccessDenied) ................................. 352
Error: RoleSessionName in AuthnResponse must match [a-zA-Z_0-9+=,[email protected]]{2,64} (Service:
AWSSecurityTokenService; Status Code: 400; Error Code: InvalidIdentityToken) ....................... 352
Error: Response signature invalid (Service: AWSSecurityTokenService; Status Code: 400; Error
Code: InvalidIdentityToken) .............................................................................................. 353
Error: Failed to assume role: Issuer not present in specified
provider (Service: AWSOpenIdDiscoveryService; Status Code: 400; Error Code:
AuthSamlInvalidSamlResponseException) ........................................................................... 353
Error: Could not parse metadata. ...................................................................................... 353
How to View a SAML Response in Your Browser for Troubleshooting ..................................... 353
Reference ...................................................................................................................................... 356
IAM Identifiers ........................................................................................................................ 356
Friendly Names and Paths ............................................................................................... 356
IAM ARNs ...................................................................................................................... 357
Unique IDs ..................................................................................................................... 359
Limits .................................................................................................................................... 360
IAM Entity Name Limits ................................................................................................... 360
IAM Entity Object Limits .................................................................................................. 361
IAM Entity Character Limits ............................................................................................. 362
AWS Services That Work with IAM ............................................................................................ 363
Compute Services ........................................................................................................... 364
Storage and Content Delivery Services .............................................................................. 365
Database Services ........................................................................................................... 366
Networking and Content Delivery Services ......................................................................... 366
Migration Services .......................................................................................................... 367
Developer Tools and Services ........................................................................................... 367
Management Tools and Services ....................................................................................... 367
Security, Identity, and Compliance Services ........................................................................ 368
Analytics Services ........................................................................................................... 369
Artificial Intelligence ....................................................................................................... 370
Internet of Things .......................................................................................................... 370
Game Development Services ............................................................................................ 371
Mobile Services .............................................................................................................. 371
Application Services ........................................................................................................ 371
Messaging Services ......................................................................................................... 372
Business Productivity ...................................................................................................... 372
Desktop and App Streaming Services ................................................................................ 373
Additional Resources ....................................................................................................... 373
Policy Reference ..................................................................................................................... 373
Element Reference .......................................................................................................... 374
Policy Variables .............................................................................................................. 395
vi
AWS Identity and Access Management User Guide
Conditions with Multiple Key Values .................................................................................
IAM Policy Evaluation Logic .............................................................................................
Policy Grammar ..............................................................................................................
AWS Managed Policies for Job Functions ...........................................................................
Global & IAM Condition Keys ...........................................................................................
Actions and Context Keys for IAM Policies .........................................................................
Actions Grouped by Access Level ......................................................................................
Resources ......................................................................................................................................
Users and Groups ...................................................................................................................
Credentials (Passwords and Access Keys) ...................................................................................
Permissions and Policies ..........................................................................................................
Federation and Delegation .......................................................................................................
IAM and Other AWS Products ..................................................................................................
Using IAM with Amazon EC2 ............................................................................................
Using IAM with Amazon S3 .............................................................................................
Using IAM with Amazon RDS ...........................................................................................
Using IAM with Amazon DynamoDB ..................................................................................
General Security Practices ........................................................................................................
General Resources ..................................................................................................................
Making Query Requests ...................................................................................................................
Endpoints ..............................................................................................................................
HTTPS Required .....................................................................................................................
Signing IAM API Requests ........................................................................................................
AWS Glossary .................................................................................................................................
vii
401
405
410
415
422
430
529
629
629
629
630
630
630
630
630
631
631
631
631
633
633
634
634
635
AWS Identity and Access Management User Guide
IAM Features
What Is IAM?
AWS Identity and Access Management (IAM) is a web service that helps you securely control access to
AWS resources for your users. You use IAM to control who can use your AWS resources (authentication)
and how they can use resources (authorization).
Topics
• IAM Features (p. 1)
• Accessing IAM (p. 2)
• Overview of Identity Management: Users (p. 3)
• Overview of Access Management: Permissions and Policies (p. 5)
• Security Features Outside of IAM (p. 7)
• Quick Links to Common Tasks (p. 8)
IAM Features
IAM gives you the following features:
Shared access to your AWS account
You can grant other people permission to administer and use resources in your AWS account without
having to share your password or access key.
Granular permissions
You can grant different permissions to different people for different resources. For example, you
might allow some users complete access to Amazon Elastic Compute Cloud (Amazon EC2), Amazon
Simple Storage Service (Amazon S3), Amazon DynamoDB, Amazon Redshift, and other AWS services.
For other users, you can allow read-only access to just some S3 buckets, or permission to administer
just some EC2 instances, or to access your billing information but nothing else.
Secure access to AWS resources for applications that run on Amazon EC2
You can use IAM features to securely give applications that run on EC2 instances the credentials that
they need in order to access other AWS resources, like S3 buckets and RDS or DynamoDB databases.
1
AWS Identity and Access Management User Guide
Accessing IAM
Identity federation
You can allow users who already have passwords elsewhere—for example, in your corporate network
or with an Internet identity provider—to get temporary access to your AWS account.
Identity information for assurance
If you use AWS CloudTrail, you receive log records that include information about those who made
requests for resources in your account. That information is based on IAM identities.
PCI DSS Compliance
IAM supports the processing, storage, and transmission of credit card data by a merchant or service
provider, and has been validated as being compliant with Payment Card Industry (PCI) Data Security
Standard (DSS). For more information about PCI DSS, including how to request a copy of the AWS
PCI Compliance Package, see PCI DSS Level 1.
Integrated with many AWS services
For a list of AWS services that work with IAM, see AWS Services That Work with IAM (p. 363).
Eventually Consistent
IAM, like many other AWS services, is eventually consistent. IAM achieves high availability by
replicating data across multiple servers within Amazon's data centers around the world. If a request
to change some data is successful, the change is committed and safely stored. However, the change
must be replicated across IAM, which can take some time. Such changes include creating or updating
users, groups, roles, or policies. We recommend that you do not include such IAM changes in the
critical, high-availability code paths of your application. Instead, make IAM changes in a separate
initialization or setup routine that you run less frequently. Also, be sure to verify that the changes
have been propagated before production workflows depend on them. For more information, see
Changes that I make are not always immediately visible (p. 336).
Accessing IAM
You can work with AWS Identity and Access Management in any of the following ways.
AWS Management Console
The console is a browser-based interface to manage IAM and AWS resources. For more information
about accessing IAM through the console, see The IAM Console and Sign-in Page (p. 43). For a
tutorial that guides you through using the console, see Creating Your First IAM Admin User and
Group (p. 14).
AWS Command Line Tools
You can use the AWS command line tools to issue commands at your system's command line to
perform IAM and AWS tasks; this can be faster and more convenient than using the console. The
command line tools are also useful if you want to build scripts that perform AWS tasks.
AWS provides two sets of command line tools: the AWS Command Line Interface (AWS CLI) and the
AWS Tools for Windows PowerShell. For information about installing and using the AWS CLI, see the
AWS Command Line Interface User Guide. For information about installing and using the Tools for
Windows PowerShell, see the AWS Tools for Windows PowerShell User Guide.
AWS SDKs
AWS provides SDKs (software development kits) that consist of libraries and sample code for various
programming languages and platforms (Java, Python, Ruby, .NET, iOS, Android, etc.). The SDKs
provide a convenient way to create programmatic access to IAM and AWS. For example, the SDKs
take care of tasks such as cryptographically signing requests, managing errors, and retrying requests
automatically. For information about the AWS SDKs, including how to download and install them,
see the Tools for Amazon Web Services page.
2
AWS Identity and Access Management User Guide
Overview: Users
IAM HTTPS API
You can access IAM and AWS programmatically by using the IAM HTTPS API, which lets you issue
HTTPS requests directly to the service. When you use the HTTPS API, you must include code to
digitally sign requests using your credentials. For more information, see Calling the API by Making
HTTP Query Requests (p. 633) and the IAM API Reference.
Overview of Identity Management: Users
For greater security and organization, you can give access to your AWS account to specific users—
identities that you create with custom permissions. You can further simplify access for those users by
federating existing identities into AWS.
Topics
• IAM Users (p. 3)
• Federating Existing Users (p. 4)
IAM Users
The "identity" aspect of AWS Identity and Access Management (IAM) helps you with the question "Who is
that user?", often referred to as authentication. Instead of sharing your root user credentials with others,
you can create individual IAM users within your account that correspond to users in your organization.
IAM users are not separate accounts; they are users within your account. Each user can have its own
password for access to the AWS Management Console. You can also create an individual access key for
each user so that the user can make programmatic requests to work with resources in your account. In
the following figure, the users Brad, Jim, DevApp1, DevApp2, TestApp1, and TestApp2 have been added
to a single AWS account. Each user has its own credentials.
Notice that some of the users are actually applications (for example, DevApp1). An IAM user doesn't
have to represent an actual person; you can create an IAM user in order to generate an access key for an
application that runs in your corporate network and needs AWS access.
3
AWS Identity and Access Management User Guide
Federating Existing Users
We recommend that you create an IAM user for yourself and then assign yourself administrative
permissions for your account. You can then sign in as that user to add more users as needed.
Federating Existing Users
If your users already have a way to be authenticated—for example, by signing in to your corporate
network—you can federate those user identities into AWS. A user who has already logged in replaces his
or her existing identity with a temporary identity in your AWS account. This user can work in the AWS
Management Console. Similarly, an application that the user is working with can make programmatic
requests using permissions that you define.
Federation is particularly useful in these cases:
• Your users already have identities in a corporate directory.
If your corporate directory is compatible with Security Assertion Markup Language 2.0 (SAML
2.0), you can configure your corporate directory to provide single-sign on (SSO) access to the AWS
Management Console for your users. For more information, see Common Scenarios for Temporary
Credentials (p. 194).
If your corporate directory is not compatible with SAML 2.0, you can create an identity broker
application to provide single-sign on (SSO) access to the AWS Management Console for your users. For
more information, see Creating a URL that Enables Federated Users to Access the AWS Management
Console (Custom Federation Broker) (p. 132).
If your corporate directory is Microsoft Active Directory, you can use AWS Directory Service to establish
trust between your corporate directory and your AWS account.
• Your users already have Internet identities.
If you are creating a mobile app or web-based app that can let users identify themselves through an
Internet identity provider like Login with Amazon, Facebook, Google, or any OpenID Connect (OIDC)
compatible identity provider, the app can use federation to access AWS. For more information, see
About Web Identity Federation (p. 106).
Tip
To use identity federation with Internet identity providers, we recommend you use Amazon
Cognito.
The following diagram shows how a user can use IAM to get temporary AWS security credentials to
access resources in your AWS account.
4
AWS Identity and Access Management User Guide
Overview: Permissions and Policies
Overview of Access Management: Permissions and
Policies
The access management portion of AWS Identity and Access Management (IAM) helps you to define what
a user or other entity is allowed to do in an account, often referred to as authorization. Permissions are
granted through policies that are created and then attached to users, groups, or roles.
Policies and Users
By default, IAM users can't access anything in your account. You grant permissions to a user by creating
a policy, which is a document that defines the effect, actions, resources, and optional conditions. The
following example shows a policy that grants permission to perform Amazon DynamoDB actions
(dynamodb:*) on the Books table in the account 123456789012 within the us-west-2 region.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "arn:aws-cn:dynamodb:us-west-2:123456789012:table/Books"
}
When you attach the policy to a user, group, or role, then the IAM entity has those DynamoDB
permissions. Typically, users in your account have multiple policies that together represent the
permissions for that user.
Any actions or resources that are not explicitly allowed are denied by default. For example, if the above
policy is the only policy attached to a user, then that user is allowed to perform DynamoDB actions
on the Books table only. Actions on all other tables are prohibited. Similarly, the user is not allowed to
perform any actions in Amazon EC2, Amazon S3, or in any other AWS service, because permissions to
work with those services are not included in the policy.
The IAM console includes policy summary tables that describe the access level, resources, and conditions
that are allowed or denied for each service in a policy. Policies are summarized in three tables: the
policy summary (p. 259), the service summary (p. 269), and the action summary (p. 273). The
policy summary table includes a list of services. Choose a service there to see the service summary. This
summary table includes a list of the actions and associated permissions for the chosen service. You can
choose an action from that table to view the action summary. This table includes a list of resources and
conditions for the chosen action.
5
AWS Identity and Access Management User Guide
Policies and Groups
You can view policy summaries on the Users page for all policies (managed and inline) that are attached
to that user. View summaries on the Policies page for all managed policies.
For example, the previous policy is summarized in the AWS Management Console as follows:
You can also view the JSON document for the policy. For information about viewing the summary or
JSON document, see Understanding Policy Summaries in the AWS Management Console (p. 258).
Policies and Groups
You can organize IAM users into IAM groups and attach a policy to a group. In that case, individual users
still have their own credentials, but all the users in a group have the permissions that are attached to the
group. Use groups for easier permissions management, and to follow our IAM Best Practices (p. 35).
6
AWS Identity and Access Management User Guide
Federated Users and Roles
Users or groups can have multiple policies attached to them that grant different permissions. In that
case, the users' permissions are calculated based on the combination of policies. But the basic principle
still applies: If the user has not been granted an explicit permission for an action and a resource, the user
does not have those permissions.
Federated Users and Roles
Federated users don't have permanent identities in your AWS account the way that IAM users do.
To assign permissions to federated users, you can create an entity referred to as a role and define
permissions for the role. When a federated user signs in to AWS, the user is associated with the role and
is granted the permissions that are defined in the role. For more information, see Creating a Role for a
Third-Party Identity Provider (Federation) (p. 156).
User-based and Resource-based Policies
In the previous example, you saw a policy that you can attach to a user or to a group. When you create a
policy for a user like that, you specify the actions that are permitted and the resource (EC2 instance, RDS
database, etc.) that the user is allowed to access.
In some cases you can attach a policy to a resource in addition to attaching it to a user or group. For
example, in Amazon S3, you can attach a policy to a bucket. A resource-based policy contains slightly
different information than a user-based policy. In a resource-based policy you specify what actions are
permitted and what resource is affected (just like a user-based policy). However, you also explicitly list
who is allowed access to the resource. (In a user-based policy, the "who" is established by whomever the
policy is attached to.)
The following example shows an S3 bucket policy that allows an IAM user named bob in AWS account
777788889999 to put objects into the bucket called example-bucket.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Principal": {"AWS": "arn:aws-cn:iam::777788889999:user/bob"},
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws-cn:s3:::example-bucket/*"
}
Resource-based policies include a Principal element that specifies who is granted the permissions. In
the preceding example, the Principal element is set to the Amazon Resource Name (ARN) of an IAM
user named bob in AWS account 777788889999. This indicates that the resource (in this case, the S3
bucket) is accessible to that IAM user but no one else.
Security Features Outside of IAM
You use IAM to control access to tasks that are performed using the AWS Management Console, the AWS
Command Line Tools, or service APIs using the AWS SDKs. Some AWS products have other ways to secure
their resources as well. The following list provides some examples, though it is not exhaustive.
Amazon EC2
In Amazon Elastic Compute Cloud you log into an instance with a key pair (for Linux instances) or
using a user name and password (for Microsoft Windows instances).
7
AWS Identity and Access Management User Guide
Quick Links to Common Tasks
For more information, see the following documentation:
• Getting Started with Amazon EC2 Linux Instances in the Amazon EC2 User Guide for Linux
Instances
• Getting Started with Amazon EC2 Windows Instances in the Amazon EC2 User Guide for Windows
Instances
Amazon RDS
In Amazon Relational Database Service you log into the database engine with a user name and
password that are tied to that database.
For more information, see Getting Started with Amazon RDS in the Amazon Relational Database
Service User Guide.
Amazon EC2 and Amazon RDS
In Amazon EC2 and Amazon RDS you use security groups to control traffic to an instance or
database.
For more information, see the following documentation:
• Amazon EC2 Security Groups for Linux Instances in the Amazon EC2 User Guide for Linux Instances
• Amazon EC2 Security Groups for Windows Instances in the Amazon EC2 User Guide for Windows
Instances
• Amazon RDS Security Groups in the Amazon Relational Database Service User Guide
Amazon WorkSpaces
In Amazon WorkSpaces, users sign in to a desktop with a user name and password.
For more information, see Getting Started with Amazon WorkSpaces in the Amazon WorkSpaces
Administration Guide.
Amazon WorkDocs
In Amazon WorkDocs, users get access to shared documents by signing in with a user name and
password.
For more information, see Getting Started with Amazon WorkDocs in the Amazon WorkDocs
Administration Guide.
These access control methods are not part of IAM. IAM lets you control how these AWS products are
administered—creating or terminating an Amazon EC2 instance, setting up new Amazon WorkSpaces
desktops, and so on. That is, IAM helps you control the tasks that are performed by making requests
to Amazon Web Services, and it helps you control access to the AWS Management Console. However,
IAM does not help you manage security for tasks like signing in to an operating system (Amazon EC2),
database (Amazon RDS), desktop (Amazon WorkSpaces), or collaboration site (Amazon WorkDocs).
When you work with a specific AWS product, be sure to read the documentation to learn the security
options for all the resources that belong to that product.
Quick Links to Common Tasks
Use the following links to get help with common tasks associated with IAM.
Sign in as an IAM user
See How IAM Users Sign In to AWS (p. 57).
8
AWS Identity and Access Management User Guide
Quick Links to Common Tasks
Manage passwords for IAM users
You need a password in order to access the AWS Management Console, including access to billing
information.
For an IAM user, see Managing Passwords for IAM Users (p. 68).
Manage permissions for IAM users
You use policies to grant permissions to the IAM users in your AWS account. IAM users have no
permissions when they are created, so you must add permissions to allow them to use AWS
resources.
For more information, see Working with Policies (p. 250).
List the users in your AWS account and get information about their credentials
See Getting Credential Reports for Your AWS Account (p. 82).
Get an access key
You need an access key if you want to make AWS requests using the AWS SDKs, the AWS Command
Line Tools, Tools for Windows PowerShellor the APIs.
Important
You can view and download your secret access key only when you create the access key. You
cannot view or recover a secret access key later. However, if you lose your secret access key,
you can create a new access key.
For your AWS account, see Managing Access Keys for your AWS Account.
For an IAM user, see Managing Access Keys for IAM Users (p. 74).
Get started with all of AWS
This set of documentation deals primarily with the IAM service. To learn about getting started with
AWS and using multiple services to solve a problem such as building and launching your first project,
see the Getting Started Resource Center.
9
AWS Identity and Access Management User Guide
Using IAM to Give Users Access to Your AWS Resources
Getting Set Up
AWS Identity and Access Management (IAM) helps you securely control access to Amazon Web Services
(AWS) and your account resources. IAM can also keep your account credentials private. With IAM, you can
create multiple IAM users under the umbrella of your AWS account or enable temporary access through
identity federation with your corporate directory. In some cases, you can also enable access to resources
across AWS accounts.
Without IAM, however, you must either create multiple AWS accounts—each with its own billing and
subscriptions to AWS products—or your employees must share the security credentials of a single AWS
account. In addition, without IAM, you cannot control the tasks a particular user or system can do and
what AWS resources they might use.
This guide provides a conceptual overview of IAM, describes business use cases, and explains AWS
permissions and policies.
Topics
• Using IAM to Give Users Access to Your AWS Resources (p. 10)
• Do I Need to Sign Up for IAM? (p. 11)
• Additional Resources (p. 11)
Using IAM to Give Users Access to Your AWS
Resources
Here are the ways you can use IAM to control access to your AWS resources.
Type of access
Why would I use it?
Where can I get more information?
Access for
users under
your AWS
account
You want to add users under the
umbrella of your AWS account,
and you want to use IAM to
create users and manage their
permissions.
To learn how to use the AWS Management
Console to create users and to manage their
permissions under your AWS account, see Getting
Started (p. 13).
10
To learn about using the IAM API or AWS
Command Line Interface to create users under
your AWS account, see Creating Your First IAM
Admin User and Group (p. 14).
AWS Identity and Access Management User Guide
Do I Need to Sign Up for IAM?
Type of access
Why would I use it?
Where can I get more information?
For more information about working with
IAM users, see Identities (Users, Groups, and
Roles) (p. 50).
Non-AWS
user access
via identity
federation
between your
authorization
system and
AWS
You have non-AWS users in
your identity and authorization
system, and they need access to
your AWS resources.
Cross-account
You want to share access to
access between certain AWS resources with users
AWS accounts
under other AWS accounts.
To learn how to use security tokens to give your
users access to your AWS account resources
through federation with your corporate directory,
go to Temporary Security Credentials (p. 193).
For information about the AWS Security Token
Service API, go to the AWS Security Token Service
API Reference.
To learn how to use IAM to grant permissions
to other AWS accounts, see Roles Terms and
Concepts (p. 98).
Do I Need to Sign Up for IAM?
If you don't already have an AWS account, you need to create one to use IAM. You don't need to
specifically sign up to use IAM. There is no charge to use IAM.
Note
IAM works only with AWS products that are integrated with IAM. For a list of services that
support IAM, see AWS Services That Work with IAM (p. 363).
To sign up for AWS
1.
Open http://www.amazonaws.cn/, and then choose Create an AWS Account.
Note
2.
This might be unavailable in your browser if you previously signed into the AWS
Management Console. In that case, choose Sign In to the Console, and then choose Create
a new AWS account.
Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone
keypad.
Additional Resources
Here are some resources to help you get things done with IAM.
• Manage your AWS account credentials: AWS Security Credentials in the AWS General Reference
• Get started with and learn more about What Is IAM? (p. 1)
• Set up a command line interface (CLI) to use with IAM. For the cross-platform AWS CLI, see the
AWS Command Line Interface Documentation and IAM CLI reference. You can also manage IAM with
Windows PowerShell; see the AWS Tools for Windows PowerShell Documentation and IAM Windows
PowerShell reference.
• Download an AWS SDK for convenient programmatic access to IAM: Tools for Amazon Web Services
• Get the release notes: Release Notes
• Get the FAQ: AWS Identity and Access Management FAQ
11
AWS Identity and Access Management User Guide
Additional Resources
• Get technical support: AWS Support Center
• Get premium technical support: AWS Premium Support Center
• Find definitions of AWS terms: Amazon Web Services Glossary
• Get community support: IAM Discussion Forums
• Contact AWS: Contact Us
12
AWS Identity and Access Management User Guide
Getting Started
This topic shows you how to give access to your AWS resources by creating AWS Identity and Access
Management (IAM) users under your AWS account. First, you'll learn about IAM concepts you should
understand before you create groups and users, and then you'll walk through how to perform the
necessary tasks using the AWS Management Console. The first task is to set up an administrators group
for your AWS account. Having an administrators group for your AWS account isn't required, but we
strongly recommend it.
Note
This set of documentation deals primarily with the IAM service. To learn about getting started
with AWS and using multiple services to solve a problem such as building and launching your
first project, see the Getting Started Resource Center.
The following figure shows a simple example of an AWS account with three groups. A group is a
collection of users who have similar responsibilities. In this example, one group is for administrators (it's
called Admins). There's also a Developers group and a Test group. Each group has multiple users. Each
user can be in more than one group, although the figure doesn't illustrate that. You can't put groups
inside other groups. You use policies to grant permissions to groups.
13
AWS Identity and Access Management User Guide
Creating an IAM Admin User and Group
In the procedure that follows, you will perform the following tasks:
• Create an Administrators group and give the group permission to access all of your AWS account's
resources.
• Create a user for yourself and add that user to the Administrators group.
• Create a password for your user so you can sign in to the AWS Management Console.
You will grant the Administrators group permission to access all your available AWS account resources.
Available resources are any AWS products you use, or that you are signed up for. Users in the
Administrators group can also access your AWS account information, except for your AWS account's
security credentials.
Topics
• Creating Your First IAM Admin User and Group (p. 14)
• How Users Sign In to Your Account (p. 17)
Creating Your First IAM Admin User and Group
Important
If you arrived at this page trying to enable Amazon Advertising for your application or web site,
see Becoming a Product Advertising API Developer.
Create a new IAM user for each person that requires administrator access. Then make those
users administrators by placing the users into an "Administrators" group to which you attach the
AdministratorAccess managed policy.
14
AWS Identity and Access Management User Guide
Creating an Administrator IAM User and Group (Console)
Thereafter, the users in the administrators group should set up the groups, users, and so on, for the AWS
account.
Creating an Administrator IAM User and Group
(Console)
This procedure describes how to use the AWS Management Console to create an IAM user for yourself
and add that user to a group that has administrative permissions from an attached managed policy.
To create an administrator user for yourself and add the user to an administrators group
(console)
1.
Use your AWS account root user email address and password to sign in as the to the IAM console at
https://console.aws.amazon.com/iam/.
2.
In the navigation pane, choose Users and then choose Add user.
3.
For User name, type a user name, such as Administrator. The name can consist of letters, digits,
and the following characters: plus (+), equal (=), comma (,), period (.), at (@), underscore (_), and
hyphen (-). The name is not case sensitive and can be a maximum of 64 characters in length.
4.
Select the check box next to AWS Management Console access, select Custom password, and then
type your new password in the text box. If you're creating the user for someone other than yourself,
you can optionally select Require password reset to force the user to create a new password when
first signing in.
5.
Choose Next: Permissions.
6.
On the Set permissions for user page, choose Add user to group.
7.
Choose Create group.
8.
In the Create group dialog box, type the name for the new group. The name can consist of letters,
digits, and the following characters: plus (+), equal (=), comma (,), period (.), at (@), underscore (_),
and hyphen (-). The name is not case sensitive and can be a maximum of 128 characters in length.
9.
In the policy list, select the check box next to AdministratorAccess. Then choose Create group.
10. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to
see the group in the list.
11. Choose Next: Review to see the list of group memberships to be added to the new user. When you
are ready to proceed, choose Create user.
You can use this same process to create more groups and users and to give your users access to your AWS
account resources. To learn about using policies that restrict user permissions to specific AWS resources,
see Access Management (p. 222) and Example Policies (p. 298). To add additional users to the group
after it's created, see Adding and Removing Users in an IAM Group (p. 95).
Creating an IAM User and Group (AWS CLI)
If you followed the steps in the previous section, you used the AWS Management Console to set up an
administrators group while creating the a user in your AWS account. This procedure shows an alternative
way to create a group.
Overview: Setting Up an Administrators Group
1. Create a group and give it a name (for example, Admins). For more information, see Creating a Group
(AWS CLI) (p. 16).
2. Attach a policy that gives the group administrative permissions—access to all AWS actions and
resources. For more information, see Attaching a Policy to the Group (AWS CLI) (p. 16).
15
AWS Identity and Access Management User Guide
Creating an IAM User and Group (AWS CLI)
3. Add at least one user to the group. For more information, see Creating an IAM User in Your AWS
Account (p. 54).
Creating a Group (AWS CLI)
This section shows how to create a group in the IAM system.
To create an administrators group (AWS CLI)
1.
Type the aws iam create-group command with the name you've chosen for the group. Optionally,
you can include a path as part of the group name. For more information about paths, see Friendly
Names and Paths (p. 356). The name can consist of letters, digits, and the following characters:
plus (+), equal (=), comma (,), period (.), at (@), underscore (_), and hyphen (-). The name is not case
sensitive and can be a maximum of 128 characters in length.
In this example, you create a group named Admins.
aws iam create-group --group-name Admins
{
"Group": {
"Path": "/",
"CreateDate": "2014-06-05T20:29:53.622Z",
"GroupId":"ABCDEFGHABCDEFGHABCDE",
"Arn": "arn:aws-cn:iam::123456789012:group/Admins",
"GroupName": "Admins"
}
}
2.
Type the aws iam list-groups command to list the groups in your AWS account and confirm the
group was created.
aws iam list-groups
{
"Groups": [
{
"Path": "/",
"CreateDate": "2014-06-05T20:29:53.622Z",
"GroupId":"ABCDEFGHABCDEFGHABCDE",
"Arn": "arn:aws-cn:iam::123456789012:group/Admins",
"GroupName": "Admins"
}
]
}
The response includes the Amazon Resource Name (ARN) for your new group. The ARN is a standard
format that AWS uses to identify resources. The 12-digit number in the ARN is your AWS account ID.
The friendly name you assigned to the group (Admins) appears at the end of the group's ARN.
Attaching a Policy to the Group (AWS CLI)
This section shows how to attach a policy that lets any user in the group perform any action on
any resource in the AWS account. You do this by attaching the AWS managed policy (p. 235)
called AdministratorAccess to the Admins group. For more information about policies, see Access
Management (p. 222).
16
AWS Identity and Access Management User Guide
Related Resources
To add a policy giving full administrator permissions (AWS CLI)
1.
Type the aws iam attach-group-policy command to attach the policy called AdministratorAccess
to your Admins group. The command uses the ARN of the AWS managed policy called
AdministratorAccess.
aws iam attach-group-policy --group-name Admins --policy-arn arn:awscn:iam::aws:policy/AdministratorAccess
If the command is successful, there is no response.
2.
Type the aws iam list-attached-group-policies command to confirm the policy is attached to
the Admins group.
aws iam list-attached-group-policies --group-name Admins
The response lists the names of the policies attached to the Admins group. A response like the
following tells you that the policy named AdministratorAccess has been attached to the Admins
group:
{
}
"AttachedPolicies": [
{
"PolicyName": "AdministratorAccess",
"PolicyArn": "arn:aws-cn:iam::aws:policy/AdministratorAccess"
}
],
"IsTruncated": false
You can confirm the contents of a particular policy with the aws iam get-policy command.
Important
After you have the administrators group set up, you must add at least one user to it. For
more information about adding users to a group, see Creating an IAM User in Your AWS
Account (p. 54).
Related Resources
For related information in the IAM User Guide, see the following resources:
• Service Last Accessed Data (p. 293)
How Users Sign In to Your Account
After you create IAM users and passwords for each, users can sign in to the AWS Management Console
for your AWS account using your account ID or alias, or from a special URL that includes your account ID.
By default, the sign-in URL for your account includes your account ID. You can create a unique sign-in
URL for your account so that the URL includes a name instead of an account ID. For more information,
see Your AWS Account ID and Its Alias (p. 45).
The sign-in endpoint follows this pattern:
https://AWS-account-ID-or-alias.signin.www.amazonaws.cn/console
17
AWS Identity and Access Management User Guide
How Users Sign In to Your Account
You can find the sign-in URL for an account on the IAM console dashboard.
You can also sign in at the following endpoint and enter the account ID or alias manually, instead of it
being embedded in the URL:
https://signin.www.amazonaws.cn/console
Tip
To create a bookmark for your account's unique sign-in page in your web browser, you should
manually enter your account's sign-in URL in the bookmark entry. Don't use your web browser's
"bookmark this page" feature.
IAM users in your account have access only to the AWS resources that you specify in the policy that is
attached to the user or to an IAM group that the user belongs to. To work in the console, users must
have permissions to perform the actions that the console performs, such as listing and creating AWS
resources. For more information, see Access Management (p. 222) and Example Policies (p. 298).
Note
If your organization has an existing identity system, you might want to create a single sign-on
(SSO) option. SSO gives users access to the AWS Management Console for your account without
requiring them to have an IAM user identity. SSO also eliminates the need for users to sign in
to your organization's site and to AWS separately. For more information, see Creating a URL
that Enables Federated Users to Access the AWS Management Console (Custom Federation
Broker) (p. 132).
Logging sign-in details in CloudTrail
If you enable CloudTrail to log sign-in events to your logs, you need to be aware of how CloudTrail
chooses where to log the events.
• If your users sign-in directly to a console, they are redirected to either a global or a regional sign-in
endpoint, based on whether the selected service console supports regions. For example, the main
console home page supports regions, so if you sign in to the following URL:
https://alias.signin.aws.amazon.com/console
you are redirected to a ''default" regional sign-in endpoint https://useast-1.signin.aws.amazon.com, resulting in a regional CloudTrail log entry in that region's log:
On the other hand, the Amazon S3 console does not support regions, so if you sign in to the following
URL
https://alias.signin.aws.amazon.com/console/s3
AWS redirects you to the global sign-in endpoint at https://signin.aws.amazon.com, resulting in a
global CloudTrail log entry.
• You can manually request a certain regional sign-in endpoint by signing in to the region-enabled main
console home page using a URL syntax like the following:
https://alias.signin.aws.amazon.com/console?region=ap-southeast-1
18
AWS Identity and Access Management User Guide
How Users Sign In to Your Account
AWS redirects you to the ap-southeast-1 regional sign-in endpoint and results in a CloudTrail log
event in that region.
For more information about CloudTrail and IAM, see Logging IAM Events with AWS CloudTrail .
If users need programmatic access to work with your account, you can create an access key pair (an
access key ID and a secret access key) for each user, as described in Creating, Modifying, and Viewing
Access Keys (Console) (p. 75).
19
AWS Identity and Access Management User Guide
Tutorial: Delegate Access to the Billing Console
IAM Tutorials
This section contains walkthroughs that present complete end-to-end procedures for common tasks that
you can perform in IAM. They are intended for a lab-type environment, with sample company names,
user names, and so on. Their purpose is to provide general guidance. They are not intended for direct
use in your production environment without careful review and adaptation to the unique aspects of your
organization's environment.
Topics
• Tutorial: Delegate Access to the Billing Console (p. 20)
• Tutorial: Delegate Access Across AWS Accounts Using IAM Roles (p. 24)
• Tutorial: Create and Attach Your First Customer Managed Policy (p. 32)
Tutorial: Delegate Access to the Billing Console
AWS account owners can delegate access to specific IAM users who need to view or manage the AWS
Billing and Cost Management data for an AWS account. The instructions that follow will help you set
up a pretested scenario so you can gain hands-on experience configuring billing permissions, without
concern for affecting your main AWS production account.
This workflow has four basic steps.
Step 1: Enable Access to Billing Data on Your AWS Test Account (p. 21)
By default, only the AWS account owner has access to view and manage billing information. IAM
users cannot access billing data until the account owner provides the user with permission.
Step 2: Create IAM Policies That Grant Permissions to Billing Data (p. 21)
After enabling billing access on your account, you must still explicitly grant access to billing data to
specific IAM users or groups. You grant this access with a customer managed policy.
Step 3: Attach Billing Policies to Your Groups (p. 22)
When you attach a policy to a group, all members of that group receive the complete set of access
permissions that are associated with that policy. In this scenario, you attach the new billing policies
to groups containing only those users who require the billing access.
Step 4: Test Access to the Billing Console (p. 22)
Once you’ve completed the core tasks, you’re ready to test the policy. Testing ensures that the policy
works the way you want it to.
20
AWS Identity and Access Management User Guide
Prerequisites
Prerequisites
Create a test AWS account to use with this tutorial. In this account create two test users and two test
groups as summarized in the following table. Be sure to assign a password to each user so that you can
sign in later in Step 4.
Create user accounts
Create and configure group accounts
FinanceManager
FullAccess
FinanceManager
FinanceUser
ViewAccess
FinanceUser
Step 1: Enable Access to Billing Data on Your AWS
Test Account
Sign into your test account and turn on billing access. For information about how to follow this process
in a production environment, see Activate Access to the AWS Website in the AWS Billing and Cost
Management User Guide.
To enable access to billing data on your AWS test account
1.
2.
3.
4.
Use your AWS account email address and password to sign in to the AWS Management Console as
the AWS account root user.
On the navigation bar, choose your account name, and then choose My Account.
Next to IAM User and Role Access to Billing Information, choose Edit, and then select the check
box to activate IAM access to the Billing and Cost Management pages.
Sign out of the console, and then proceed to Step 2: Create IAM Policies That Grant Permissions to
Billing Data (p. 21).
Step 2: Create IAM Policies That Grant Permissions to
Billing Data
Next, create custom policies that grant both view and full access permissions to the pages within the
Billing and Cost Management console. For general information about IAM permission policies, see
Managed Policies and Inline Policies (p. 235).
To create IAM polices that grant permissions to billing data
1.
2.
Sign in to the AWS Management Console as a user with administrator credentials. For more
information, see Create individual IAM users.
Open the IAM console at https://console.aws.amazon.com/iam/.
3.
4.
5.
6.
7.
In the navigation pane, choose Policies, and then choose Create Policy.
Next to Policy Generator, choose Select.
On the Edit Permissions page, for Effect choose Allow.
For AWS Service, choose AWS Billing.
Follow these steps to create two policies:
Full access
a. For Actions, choose All Actions (*).
21
AWS Identity and Access Management User Guide
Step 3: Attach Billing Policies to Your Groups
b. Choose Add Statement, and then choose Next Step.
c. On the Review Policy page, next to Policy Name, type BillingFullAccess, and then choose
Create Policy to save it.
View-only access
a. Repeat steps 3 through 6 (p. 21).
b. For Actions, choose only those permissions that begin with View.
c. Choose Add Statement, and then choose Next Step.
d. On the Review Policy page, for Policy Name, type BillingViewAccess. Then choose Create
Policy to save it.
To review descriptions for each of the permissions available in IAM policies that grant users access to
the Billing and Cost Management console, see Billing Permissions Descriptions.
Step 3: Attach Billing Policies to Your Groups
Now that you have custom billing policies available, you can attach them to their corresponding groups
that you created earlier. Although you can attach a policy directly to a user or role, we recommend (in
accordance with IAM best practices) that you use groups instead. For more information, see Use groups
to assign permissions to IAM users (p. 36).
To attach billing policies to your groups
1.
In the navigation pane, choose Policies to display the full list of policies available to your AWS
account. To attach each policy to its appropriate group, follow these steps:
Full access
a. In the search box, type BillingFullAccess, and then select the check box next to the policy
name.
b. Choose Policy actions, and then choose Attach.
c. In the search box, type FullAccess, select the check box next to the name of the group, and then
choose Attach policy.
View-only access
a. In the search box, type BillingViewAccess, and then select the check box next to the policy
name.
b. Choose Policy actions, and then choose Attach.
c. For Filter, choose Groups. In the search box, type ViewAccess, select the check box next to the
name of the group, and then choose Attach policy.
2.
Sign out of the console, and then proceed to Step 4: Test Access to the Billing Console (p. 22).
Step 4: Test Access to the Billing Console
You can test user access in a couple of ways. For this tutorial, we recommend that you test access by
signing in as each of the test users so you can see what your users might experience. Another (optional)
way to test user access permissions is to use the IAM policy simulator. Use the following steps if you want
to see another way to view the effective result of these actions.
22
AWS Identity and Access Management User Guide
Related Resources
Select either of the following procedures based on your preferred testing method. In the first one, you
sign in using both test accounts to see the difference between access rights.
To test billing access by signing in with both test user accounts
1.
Use your AWS account ID or account alias, your IAM user name, and your password to sign in to the
IAM console.
Note
For your convenience, the AWS sign-in page uses a browser cookie to remember your IAM
user name and account information. If you previously signed in as a different user, choose
Sign in to a different account near the bottom of the page to return to the main sign-in
page. From there, you can type your AWS account ID or account alias to be redirected to the
IAM user sign-in page for your account.
2.
Sign-in with each account using the steps provided below so you can compare the different user
experiences.
Full access
a. Sign in to your AWS account as the user FinanceManager.
b. On the navigation bar, choose [email protected]<account alias or ID number> , and then
choose Billing & Cost Management.
c. Browse through the pages and choose the various buttons to ensure that you have full modify
permissions.
View-only access
a. Sign in to your AWS account as the user FinanceUser.
b. On the navigation bar, choose [email protected]<account alias or ID number>, and then choose
Billing & Cost Management.
c. Browse through the pages. Notice that you can display costs, reports, and billing data with no
problems. However, if you choose an option to modify a value, you receive an Access Denied
message. For example, on the Preferences page, choose any of the check boxes on the page, and
then choose Save preferences. The console message informs you that you need ModifyBilling
permissions to make changes to that page.
The following optional procedure demonstrates how you could alternatively use the IAM policy simulator
to test your delegated user’s effective permissions to billing pages.
To test billing access by viewing effective permissions in the IAM policy simulator
1.
2.
3.
4.
5.
Open the IAM policy simulator at https://policysim.www.amazonaws.cn/. (If you are not already
signed in to AWS, you are prompted to sign in).
Under Users, Groups, and Roles, select one of the users that is a member of the group you recently
attached the policy to.
Under Policy Simulator, choose Select service, and then choose Billing.
Next to Select actions, choose Select All.
Choose Run Simulation and compare the user’s listed permissions with all possible billing-related
permission options to make sure that the correct rights have been applied.
Related Resources
For related information found in the AWS Billing and Cost Management User Guide, see the following
resources:
23
AWS Identity and Access Management User Guide
Summary
• Activate Access to the AWS Website
• Example 4: Allow full access to AWS services but deny IAM users access to the Billing and Cost
Management console.
• Billing Permissions Descriptions
For related information in the IAM User Guide, see the following resources:
• Managed Policies and Inline Policies (p. 235)
• Controlling User Access to the AWS Management Console (p. 44)
• Attaching a Policy to an IAM Group (p. 95)
Summary
You’ve now successfully completed all of the steps necessary to delegate user access to the Billing and
Cost Management console. As a result, you've seen firsthand what your users billing console experience
will be like and can now proceed to implement this logic in your production environment at your
convenience.
Tutorial: Delegate Access Across AWS Accounts
Using IAM Roles
This tutorial teaches you how to use a role to delegate access to resources that are in different AWS
accounts that you own (Production and Development). You share resources in one account with users in a
different account. By setting up cross-account access in this way, you don't need to create individual IAM
users in each account. In addition, users don't have to sign out of one account and sign into another in
order to access resources that are in different AWS accounts. After configuring the role, you see how to
use the role from the AWS Management Console, the AWS CLI, and the API.
In this tutorial, imagine that the Production account is where live applications are managed, and
the Development account is a sandbox where developers and testers can freely test applications. In
each account, application information is stored in Amazon S3 buckets. You manage IAM users in the
Development account, where you have two IAM groups: Developers and Testers. Users in both groups
have permissions to work in the Development account and access resources there. From time to time, a
developer must update the live applications in the Production account. These applications are stored in
an Amazon S3 bucket called productionapp.
At the end of this tutorial, you have a role in the Production account (the trusting account) that allows
users from the Development account (the trusted account) to access the productionapp bucket in
the Production account. Developers can use the role in the AWS Management Console to access the
productionapp bucket in the Production account. They can also access the bucket by using API calls that
are authenticated by temporary credentials provided by the role. Similar attempts by a Tester to use the
role fail.
This workflow has three basic steps.
24
AWS Identity and Access Management User Guide
Prerequisites
Step 1 - Create a Role (p. 25)
First, you use the AWS Management Console to establish trust between the Production account
(ID number 999999999999) and the Development account (ID number 111111111111). You start
by creating an IAM role named UpdateApp. When you create the role, you define the Development
account as a trusted entity and specify a permissions policy that allows trusted users to update the
productionapp bucket.
Step 2 - Grant Access to the Role (p. 27)
In this step of the tutorial, you modify the IAM group policy so that Testers are denied access to the
UpdateAPP role. Because Testers have PowerUser access in this scenario, we must explicitly deny the
ability to use the role.
Step 3 - Test Access by Switching Roles (p. 29)
Finally, as a Developer, you use the UpdateAPP role to update the productionapp bucket in the
Production account. You see how to access the role through the AWS console, the AWS CLI, and the
API.
Prerequisites
This tutorial assumes that you have the following already in place:
• Two separate AWS accounts that you can use, one to represent the Development account, and one to
represent the Production account.
• Users and groups in the Development account created and configured as follows:
User
Group
Permissions
David
Developers
Theresa
Testers
Both users are able to sign in and use the AWS
Management Console in the Development account.
• You do not need to have any users or groups created in the Production account.
• An Amazon S3 bucket created in the Production account. We call it ProductionApp in this tutorial, but
because S3 bucket names must be globally unique, you must use a bucket with a different name.
Step 1 - Create a Role
To allow users from one AWS account to access resources in another AWS account, create a role that
defines who can access it and what permissions it grants to users that switch to it.
In this step of the tutorial, you create the role in the Production account and specify the Development
account as a trusted entity. You also limit the role's permissions to only read and write access to the
25
AWS Identity and Access Management User Guide
Step 1 - Create a Role
productionapp bucket. Anyone who is granted permission to use the role can read and write to the
productionapp bucket.
Before you can create a role, you need the account ID of the Development AWS account. The account ID
is a unique identifier assigned to each AWS account.
To obtain the Development AWS account ID
1.
Sign in to the AWS Management Console as an administrator of the Development account, and open
the IAM console at https://console.amazonaws.cn/iam/.
2.
In navigation bar, choose Support, and then Support Center. The Account Number is in the upper
right corner immediately below the Support menu. The account ID is a 12-digit number. For this
scenario, we pretend the Development account ID is 111111111111; however, you should use a valid
account ID if you are reconstructing the scenario in your test environment.
To create a role in the Production account that can be used by the Development account
1.
Sign in to the AWS Management Console as an administrator of the Production account, and open
the IAM console.
2.
Before creating the role, prepare the managed policy that defines the permissions that the role
requires. You attach this policy to the role in a later step.
You want to set read and write access to the productionapp bucket. Although AWS provides some
Amazon S3 managed policies, there isn't one that provides read and write access to a single Amazon
S3 bucket. You can create your own policy instead.
3.
4.
5.
In the navigation pane on the left, choose Policies and then choose Create policy.
Next to Create Your Own Policy, choose Select.
Enter read-write-app-bucket for the policy name.
Add the following permissions to the policy document. Ensure that you replace the resource ARN
(arn:aws-cn:s3:::productionapp) with the real one appropriate to your S3 bucket.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListAllMyBuckets",
"Resource": "arn:aws-cn:s3:::*"
},
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetBucketLocation"
],
"Resource": "arn:aws-cn:s3:::productionapp"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": "arn:aws-cn:s3:::productionapp/*"
}
]
26
AWS Identity and Access Management User Guide
Step 2 - Grant Access to the Role
The ListBucket permission allows users to view objects in the productionapp bucket. The
GetObject, PutObject, DeleteObject permissions allows users to view, update, and delete contents
in the productionapp bucket.
6.
Choose Create policy.
The new policy appears in the list of managed policies.
7.
In the navigation pane on the left, choose Roles and then choose Create role.
8.
Choose the Another AWS account role type.
9.
For Account ID, type the Development account ID.
This tutorial uses the example account ID 111111111111 for the Development account. You should
use a valid account ID. If you use an invalid account ID, such as 111111111111, IAM does not let you
create the new role.
10. Choose Next: Permissions to set the permissions that will be associated with the role.
11. Select the box next to the policy that you created previously.
Tip
For Filter, choose Customer managed to filter the list to include only the policies that you
have created. This hides the AWS created policies and makes it much easier to find the one
you're looking for.
Then choose Next: Review.
12. Type UpdateAPP for the role name.
13. (Optional) For Role description, type a description for the new role.
14. After reviewing the role, choose Create role.
The UpdateAPP role appears in the list of roles.
Now you must obtain the role's Amazon Resource Name (ARN), which is a unique identifier for the role.
When you modify the Developers and Testers group's policy, you will specify the role's ARN to grant or
deny permissions.
To obtain the ARN for UpdateAPP
1.
In the navigation pane of the IAM console, choose Roles.
2.
In the list of roles, choose the UpdateAPP role.
3.
In the Summary section of the details pane, copy the Role ARN value.
The Production account has an account ID of 999999999999, so the role ARN is arn:awscn:iam::999999999999:role/UpdateAPP. Ensure that you supply the real AWS account ID for your
'production' account.
At this point, you have established trust between the Production and Development accounts by creating
a role in the Production account that identifies the Development account as a trusted principal. You also
defined what users who switch to the UpdateApp role can do.
Next, modify the permissions for the groups.
Step 2 - Grant Access to the Role
At this point, both Testers and Developers group members have permissions that allow them to freely
test applications in the Development account. Here are the steps required to add permissions to allow
switching to the role.
27
AWS Identity and Access Management User Guide
Step 2 - Grant Access to the Role
To modify the Developers group to allow them to switch to the UpdateApp role
1.
Sign in as an administrator in the Development account, and open the IAM console.
2.
Choose Groups, and then choose Developers.
3.
Choose the Permissions tab, expand the Inline Policies section, and then choose Create Group
Policy. If no inline policy exists yet, then the button does not appear. Instead, choose the link at the
end of "To create one, click here."
4.
Choose Custom Policy and then choose Select button.
5.
Type a policy name like allow-assume-S3-role-in-production.
6.
Add the following policy statement to allow the AssumeRole action on the UpdateAPP role in the
Production account. Be sure that you change PRODUCTION-ACCOUNT-ID in the Resource element to
the actual AWS account ID of the Production account.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws-cn:iam::PRODUCTION-ACCOUNT-ID:role/UpdateAPP"
}
The Allow effect explicitly allows the Developers group access to the UpdateAPP role in the
Production account. Any developer who tries to access the role will succeed.
7.
Choose Apply Policy to add the policy to the Developer group.
In most environments, the following procedure is likely not needed. If, however, you use Power User
permissions, then some groups might already be able to switch roles. The following procedures shows
how to add a "Deny" permission to the Testers group to ensure that they cannot assume the role. If
this procedure is not needed in your environment, then we recommend that you do not add it. "Deny"
permissions make the overall permissions picture more complicated to manage and understand. Use
"Deny" permissions only when there is not a better option.
To modify the Testers group to deny permission to assume the UpdateApp role
1.
Choose Groups, and then choose Testers.
2.
Choose the Permissions tab, expand the Inline Policies section, and then choose Create Group
Policy.
3.
Choose Custom Policy and then choose the Select button.
4.
Type a policy name like deny-assume-S3-role-in-production.
5.
Add the following policy statement to deny the AssumeRole action on the UpdateAPP role. Be sure
that you change PRODUCTION-ACCOUNT-ID in the Resource element to the actual AWS account ID of
the Production account.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Deny",
"Action": "sts:AssumeRole",
"Resource": "arn:aws-cn:iam::PRODUCTION-ACCOUNT-ID:role/UpdateAPP"
}
The Deny effect explicitly denies the Testers group access to the UpdateAPP role in the Production
account. Any tester who tries to access the role will get an access denied message.
28
AWS Identity and Access Management User Guide
Step 3 - Test Access by Switching Roles
6.
Choose Apply Policy to add the policy to the Tester group.
The Developers group now has permissions to use the UpdateAPP role in the Production account. The
Testers group is prevented from using the UpdateAPP role.
Next, you'll learn how David, a developer, can access the productionapp bucket in the Production account
by using the AWS Management Console, the AWS CLI commands, and the AssumeRole API call.
Step 3 - Test Access by Switching Roles
After completing the first two steps of this tutorial, you have a role that grants access to a resource in the
Production account. You also have one group in the Development account whose users are allowed to
use that role. The role is now ready to use. This step discusses how to test switching to that role from the
AWS Management Console, the AWS CLI, and the AWS API.
Important
You can switch to a role only when you are signed in as an IAM user or a federated user.
Additionally, if you launch an Amazon EC2 instance to run an application, the application can
assume a role through its instance profile.
Switch Roles (Console)
If David needs to work with in the Production environment in the AWS Management Console, he can
do so by using Switch Role. He specifies the account ID or alias and the role name, and his permissions
immediately switch to those permitted by the role. He can then use the console to work with the
productionapp bucket, but cannot work with any other resources in Production. While David is using the
role, he also cannot make use of his power-user privileges in the Development account. That's because
only one set of permissions can be in effect at a time.
Important
Switching roles using the AWS Management Console works only with accounts that do not
require an ExternalID. If you grant access to your account to a third party and require an
ExternalID in a Condition element in your permission policy, the third party can access your
account only by using the AWS API or a command line tool. The third party cannot use the
console because it cannot supply a value for ExternalID. For more information about this
scenario, see How to Use an External ID When Granting Access to Your AWS Resources to a Third
Party (p. 149), and How to Enable Cross-Account Access to the AWS Management Console in
the AWS Security Blog.
There are two ways that David can use to enter the Switch Role page:
• David receives a link from his administrator that points to a pre-defined Switch Role configuration.
The link is provided to the administrator on the final page of the Create role wizard or on the Role
Summary page for a cross-account role. Choosing this link takes David to the Switch Role page with
the Account ID and Role name fields already filled in. All David needs to do is choose Switch Role and
he's done.
• The administrator does not send the link in email, but instead sends the Account ID number and Role
Name values. David must manually enter them to switch roles. This is illustrated in the following
procedure.
To assume a role
1.
David signs into the AWS console using his normal user that is in the Development group.
2.
He chooses the link that his administrator sent to him in email. This takes him to the Switch Role
page with the account ID or alias and the role name information already filled in.
29
AWS Identity and Access Management User Guide
Step 3 - Test Access by Switching Roles
—or—
He chooses his name (the Identity menu) on the navigation bar, and then chooses Switch Role.
If this is the first time David tries to access the Switch Role page this way, he will first land on a firstrun Switch Role page. This page provides additional information on how switching roles can enable
users to manage resources across AWS accounts. David must choose the Switch Role button on this
page to complete the rest of this procedure.
3.
Next, in order to access the role, David must manually type the Production account ID number
(999999999999) and the role name (UpdateApp).
Also, to help him stay aware of which role (and associated permissions) are currently active, he types
PRODUCTION in the Display Name text box, selects the red color option, and then chooses Switch
Role.
4.
David can now use the Amazon S3 console to work with the Amazon S3 bucket, or any other
resource to which the UpdateApp role has permissions.
5.
When he is done with the work he needs to do, David can return to his original permissions. To do
that, he chooses the PRODUCTION role display name on the navigation bar and then chooses Back
to David @ 111111111111.
6.
The next time David wants to switch roles and chooses the Identity menu in the navigation bar, he
sees the PRODUCTION entry still there from last time. He can simply choose that entry to switch
roles immediately without having to reenter the account ID and role name.
Switch Roles (AWS CLI)
If David needs to work in the Production environment at the command line, he can do so by using the
AWS CLI. He runs the aws sts assume-role command and passes the role ARN to get temporary security
credentials for that role. He then configures those credentials in environment variables so subsequent
AWS CLI commands work using the role's permissions. While David is using the role, he cannot use his
power-user privileges in the Development account because only one set of permissions can be in effect
at a time.
Note that all access keys and tokens are examples only and cannot be used as shown. Replace with the
appropriate values from your live environment.
To assume a role
1.
David opens a command prompt window, and confirms that the AWS CLI client is working by
running the command:
aws help
Note
David's default environment uses the David user credentials from his default profile that he
created with the aws configure command. For more information, see Configuring the AWS
Command Line Interface in the AWS Command Line Interface User Guide.
2.
He begins the switch role process by running the following command to switch to the UpdateApp
role in the Production account. He got the role ARN from the administrator that created the role.
The command requires that you provide a session name as well, you can choose any text you like for
that.
aws sts assume-role --role-arn "arn:aws-cn:iam::999999999999:role/UpdateApp" --rolesession-name "David-ProdUpdate"
30
AWS Identity and Access Management User Guide
Step 3 - Test Access by Switching Roles
David then sees the following in the output:
{
"Credentials": {
"SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"SessionToken": "AQoDYXdzEGcaEXAMPLE2gsYULo
+Im5ZEXAMPLEeYjs1M2FUIgIJx9tQqNMBEXAMPLE
CvSRyh0FW7jEXAMPLEW+vE/7s1HRpXviG7b+qYf4nD00EXAMPLEmj4wxS04L/
uZEXAMPLECihzFB5lTYLto9dyBgSDy
EXAMPLE9/
g7QRUhZp4bqbEXAMPLENwGPyOj59pFA4lNKCIkVgkREXAMPLEjlzxQ7y52gekeVEXAMPLEDiB9ST3Uuysg
sKdEXAMPLE1TVastU1A0SKFEXAMPLEiywCC/Cs8EXAMPLEpZgOs+6hz4AP4KEXAMPLERbASP
+4eZScEXAMPLEsnf87e
NhyDHq6ikBQ==",
"Expiration": "2014-12-11T23:08:07Z",
"AccessKeyId": "AKIAIOSFODNN7EXAMPLE"
}
}
3.
David sees the three pieces that he needs in the Credentials section of the output.
• AccessKeyId
• SecretAccessKey
• SessionToken
David needs to configure the AWS CLI environment to use these parameters in subsequent calls.
For information about the various ways to configure your credentials, see Configuring the AWS
Command Line Interface. You cannot use the aws configure command because it does not support
capturing the session token. However, you can manually type the information into a configuration
file. Because these are temporary credentials with a relatively short expiration time, it is easiest to
add them to the environment of your current command line session.
4.
To add the three values to the environment, David cuts and pastes the output of the previous step
into the following commands. Note that you might want to cut and paste into a simple text editor to
address line wrap issues in the output of the session token. It must be added as a single long string,
even though it is shown line wrapped here for clarity.
set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
set AWS_SESSION_TOKEN=AQoDYXdzEGcaEXAMPLE2gsYULo
+Im5ZEXAMPLEeYjs1M2FUIgIJx9tQqNMBEXAMPLECvS
Ryh0FW7jEXAMPLEW+vE/7s1HRpXviG7b+qYf4nD00EXAMPLEmj4wxS04L/
uZEXAMPLECihzFB5lTYLto9dyBgSDyEXA
MPLEKEY9/
g7QRUhZp4bqbEXAMPLENwGPyOj59pFA4lNKCIkVgkREXAMPLEjlzxQ7y52gekeVEXAMPLEDiB9ST3UusKd
EXAMPLE1TVastU1A0SKFEXAMPLEiywCC/Cs8EXAMPLEpZgOs+6hz4AP4KEXAMPLERbASP
+4eZScEXAMPLENhykxiHen
DHq6ikBQ==
At this point, any following commands run under the permissions of the role identified by those
credentials. In David's case, the UpdateApp role.
5.
Run the command to access the resources in the Production account. In this example, David simply
lists the contents of his S3 bucket with the following command.
aws s3 ls s3://productionapp
Because Amazon S3 bucket names are universally unique, there is no need to specify the account
ID that owns the bucket. To access resources for other AWS services, refer to the AWS CLI
31
AWS Identity and Access Management User Guide
Related Resources
documentation for that service for the commands and syntax that are required to reference its
resources.
Using AssumeRole (AWS API)
When David needs to make an update to the Production account from code, he makes an AssumeRole
call to assume the UpdateAPP role. The call returns temporary credentials that he can use to access the
productionapp bucket in the Production account. With those credentials, David can make API calls to
update the productionapp bucket. However, he cannot make API calls to access any other resources in
the Production account, even though he has power-user permissions in the Development account.
To assume a role
1.
David calls AssumeRole as part of an application. He must specify the UpdateAPP ARN: arn:awscn:iam::999999999999:role/UpdateAPP.
The response from the AssumeRole call includes the temporary credentials with an AccessKeyId, a
SecretAccessKey, and an Expiration time that indicates when the credentials expire and you must
request new ones.
2.
With the temporary credentials, David makes an s3:PutObject call to update the productionapp
bucket. He would pass the credentials to the API call as the AuthParams parameter. Because the
temporary role credentials have only read and write access to the productionapp bucket, any other
actions in the Production account are denied.
For a code example (using Python), see Switching to an IAM Role (API) (p. 176).
Related Resources
• For more information about IAM users and groups, see Identities (Users, Groups, and Roles) (p. 50) .
• For more information about Amazon S3 buckets, see Create a Bucket in the Amazon Simple Storage
Service Getting Started Guide.
Summary
You have completed the cross-account API access tutorial. You created a role to establish trust with
another account and defined what actions trusted entities can take. Then, you modified a group policy to
control which IAM users can access the role. As a result, developers from the Development account can
make updates to the productionapp bucket in the Production account by using temporary credentials.
Tutorial: Create and Attach Your First Customer
Managed Policy
In this tutorial, you use the AWS Management Console to create a customer-managed policy (p. 237)
and then attach that policy to an IAM user in your AWS account. The policy you create allows an IAM test
user to sign in directly to the AWS Management Console with read only permissions.
This workflow has three basic steps:
32
AWS Identity and Access Management User Guide
Prerequisites
Step 1: Create the Policy (p. 33)
By default, IAM users do not have permissions to do anything. They cannot access the AWS
Management Console or manage the data within unless you allow it. In this step, you create a
customer managed policy that allows any attached user to sign-in to the console.
Step 2: Attach the Policy (p. 34)
When you attach a policy to a user, the user inherits all of the access permissions that are associated
with that policy. In this step, you attach the new policy to a test user account.
Step 3: Test User Access (p. 34)
Once the policy is attached, you can sign in as the user and test the policy.
Prerequisites
To perform the steps in this tutorial, you need to already have the following:
• An AWS account that you can sign in to as an IAM user with administrative permissions.
• A test IAM user that has no permissions assigned or group memberships as follows:
User Name
Group
Permissions
PolicyUser
<none>
<none>
Step 1: Create the Policy
In this step, you create a customer managed policy that allows any attached user to sign in to the AWS
Management Console with read-only access to IAM data.
To create the policy for your test user
1.
2.
Sign in to the IAM console at https://console.amazonaws.cn/iam/ with your user that has
administrator permissions.
In the navigation pane, choose Policies.
3.
4.
In the content pane, choose Create Policy.
Next to Create Your Own Policy, choose Select.
5.
6.
For Policy Name, type UsersReadOnlyAccessToIAMConsole.
For Policy Document, paste the following policy.
{
}
7.
"Version": "2012-10-17",
"Statement": [ {
"Effect": "Allow",
"Action": [
"iam:GenerateCredentialReport",
"iam:Get*",
"iam:List*"
],
"Resource": "*"
} ]
Choose Validate Policy and ensure that no errors display in a red box at the top of the screen.
Correct any that are reported.
33
AWS Identity and Access Management User Guide
Step 2: Attach the Policy
Note
8.
If Use autoformatting for policy editing is selected, the policy is reformatted whenever
you open a policy or choose Validate Policy.
Choose Create Policy.
You now have a policy ready to attach.
Step 2: Attach the Policy
Next you attach the policy you just created to your test IAM user.
To attach the policy to your test user
1.
In the IAM console, in the navigation pane, choose Policies.
2.
At the top of the policy list, in the search box, start typing UsersReadOnlyAccesstoIAMConsole until
you can see your policy, and then check the box next to UsersReadOnlyAccessToIAMConsole in the
list.
3.
4.
Choose the Policy actions button, and then chose Attach.
For Filter, choose Users.
5.
In the search box, start typing PolicyUser until that user is visible on the list, and then check the box
next to that user in the list.
Choose Attach Policy.
6.
You have attached the policy to your IAM test user, which means that user now has read-only access to
the IAM console.
Step 3: Test User Access
For this tutorial, we recommend that you test access by signing in as the test user so you can observe the
results and see what your users might experience.
To test access by signing in with your test user account
1.
2.
Sign in to the IAM console at https://console.amazonaws.cn/iam/ with your PolicyUser test user.
Browse through the pages of the console and try to create a new user or group. Notice that
PolicyUser can display data but cannot create or modify existing IAM data.
Related Resources
For related information in the IAM User Guide, see the following resources:
• Managed Policies and Inline Policies (p. 235)
• Controlling User Access to the AWS Management Console (p. 44)
Summary
You’ve now successfully completed all of the steps necessary to create and attach a customer managed
policy. As a result, you are able to sign in to the IAM console with your test account and have seen
firsthand what the experience would be like for your users.
34
AWS Identity and Access Management User Guide
Best Practices
IAM Best Practices and Use Cases
To get the greatest benefits from IAM, take time to learn the recommended best practices. One way to
do this is to see how IAM is used in real-world scenarios to work with other AWS services.
Topics
• IAM Best Practices (p. 35)
• Business Use Cases (p. 39)
IAM Best Practices
To help secure your AWS resources, follow these recommendations for the AWS Identity and Access
Management (IAM) service.
Topics
• Use AWS Defined Policies to Assign Permissions Whenever Possible (p. 35)
• Use Groups to Assign Permissions to IAM Users (p. 36)
• Grant Least Privilege (p. 36)
• Use Access Levels to Review IAM Permissions (p. 37)
• Configure a Strong Password Policy for Your Users (p. 37)
• Use Roles for Applications That Run on Amazon EC2 Instances (p. 37)
• Delegate by Using Roles Instead of by Sharing Credentials (p. 38)
• Rotate Credentials Regularly (p. 38)
• Remove Unnecessary Credentials (p. 38)
• Use Policy Conditions for Extra Security (p. 38)
• Monitor Activity in Your AWS Account (p. 39)
Use AWS Defined Policies to Assign Permissions
Whenever Possible
We recommend that you use the managed policies that are created and maintained by AWS to grant
permissions whenever possible. A key advantage of using these policies is that they are maintained and
updated by AWS as new services or new APIs are introduced.
35
AWS Identity and Access Management User Guide
Use Groups to Assign Permissions to IAM Users
AWS-managed policies are designed to support common tasks. They typically provide access to a single
service or a limited set of actions. For more information about AWS managed policies, see AWS Managed
Policies (p. 236).
AWS managed policies for job functions can span multiple services and align with common job functions
in the IT industry. For a list and descriptions of job function policies, see AWS Managed Policies for Job
Functions (p. 415).
Use Groups to Assign Permissions to IAM Users
Instead of defining permissions for individual IAM users, it's usually more convenient to create groups
that relate to job functions (administrators, developers, accounting, etc.). Next, define the relevant
permissions for each group. Finally, assign IAM users to those groups. All the users in an IAM group
inherit the permissions assigned to the group. That way, you can make changes for everyone in a group
in just one place. As people move around in your company, you can simply change what IAM group their
IAM user belongs to.
For more information, see the following:
• Creating Your First IAM Admin User and Group (p. 14)
• Managing IAM Groups (p. 94)
Grant Least Privilege
When you create IAM policies, follow the standard security advice of granting least privilege—that is,
granting only the permissions required to perform a task. Determine what users need to do and then
craft policies for them that let the users perform only those tasks.
Start with a minimum set of permissions and grant additional permissions as necessary. Doing so is more
secure than starting with permissions that are too lenient and then trying to tighten them later.
Defining the right set of permissions requires some research. Determine what is required for the specific
task, what actions a particular service supports, and what permissions are required in order to perform
those actions. To have access levels help you determine what permissions are required, see Use Access
Levels to Review IAM Permissions (p. 37).
One feature that can help with this is the Access Advisor tab. This tab is available on the IAM console
details page whenever you inspect a user, group, role, or policy. The tab includes information about
which services are actually used by a user, group, role, or by anyone that uses a policy. You can use this
information to identify unnecessary permissions so that you can refine your IAM policies to better adhere
to the principle of least privilege. For more information, see Service Last Accessed Data (p. 293).
For more information, see the following:
• Access Management (p. 222)
• Policy topics for individual services, which provide examples of how to write policies for servicespecific resources. Examples:
• Authentication and Access Control for Amazon DynamoDB in the Amazon DynamoDB Developer
Guide
• Using Bucket Policies and User Policies in the Amazon Simple Storage Service Developer Guide
• Access Control List (ACL) Overview in the Amazon Simple Storage Service Developer Guide
36
AWS Identity and Access Management User Guide
Use Access Levels to Review IAM Permissions
Use Access Levels to Review IAM Permissions
To improve the security of your AWS account, you should regularly review and monitor each of your IAM
policies. Make sure that your policies grant the least privilege (p. 36) that is needed to perform only
the necessary actions.
When you review a policy, you can view the policy summary (p. 258) that includes a summary of the
access level for each service within that policy. AWS categorizes each service action into one of four
access levels based on what each action does: List, Read, Write, or Permissions management. You can use
these access levels to determine which actions to include in your policies.
For example, in the Amazon S3 service, you might want to allow a large group of users to access List
and Read actions. Such actions permit those users to list the buckets and get objects in Amazon S3.
However, you should allow only a small group of users to access the Amazon S3 Write actions to delete
buckets or put objects into an S3 bucket. Additionally, you should restrict permissions to allow only
administrators to access the Amazon S3 Permissions management actions. This ensures that only a
limited number of people can manage bucket policies in Amazon S3. This is especially important for
Permissions management actions in IAM and AWS Organizations services.
Important
Before you create or edit policies based on these access levels, review the definitions for each
access level. Make sure that the actions you want are categorized the way you expect. To learn
about each AWS access level and to view a list of actions that belong to each action level for a
specific service, see AWS IAM Policy Actions Grouped by Access Level (p. 529).
To see the access levels for a policy, you must first locate the policy's summary. The policy summary is
included on the Policies page for managed policies, and on the Users page for policies that are attached
to a user. For more information, see Policy Summary (List of Services) (p. 259).
Within a policy summary, the Access level column shows that the policy provides Full or Limited access
to one or more of the four AWS access levels for the service. Alternately, it might show that the policy
provides Full access to all the actions within the service. You can use the information within this Access
level column to understand the level of access that the policy provides. You can then take action to make
your AWS account more secure. For details and examples of the access level summary, see Understanding
Access Level Summaries Within Policy Summaries (p. 267).
Configure a Strong Password Policy for Your Users
If you allow users to change their own passwords, require that they create strong passwords and
that they rotate their passwords periodically. On the Account Settings page of the IAM console, you
can create a password policy for your account. You can use the password policy to define password
requirements, such as minimum length, whether it requires non-alphabetic characters, how frequently it
must be rotated, and so on.
For more information, see Setting an Account Password Policy for IAM Users (p. 65).
Use Roles for Applications That Run on Amazon EC2
Instances
Applications that run on an Amazon EC2 instance need credentials in order to access other AWS services.
To provide credentials to the application in a secure way, use IAM roles. A role is an entity that has its
own set of permissions, but that isn't a user or group. Roles also don't have their own permanent set
of credentials the way IAM users do. In the case of Amazon EC2, IAM dynamically provides temporary
credentials to the EC2 instance, and these credentials are automatically rotated for you.
37
AWS Identity and Access Management User Guide
Delegate by Using Roles Instead of by Sharing Credentials
When you launch an EC2 instance, you can specify a role for the instance as a launch parameter.
Applications that run on the EC2 instance can use the role's credentials when they access AWS resources.
The role's permissions determine what the application is allowed to do.
For more information, see Using an IAM Role to Grant Permissions to Applications Running on Amazon
EC2 Instances (p. 177).
Delegate by Using Roles Instead of by Sharing
Credentials
You might need to allow users from another AWS account to access resources in your AWS account. If so,
don't share security credentials, such as access keys, between accounts. Instead, use IAM roles. You can
define a role that specifies what permissions the IAM users in the other account are allowed. You can also
designate which AWS accounts have the IAM users that are allowed to assume the role.
For more information, see Roles Terms and Concepts (p. 98).
Rotate Credentials Regularly
Change your own passwords and access keys regularly, and make sure that all IAM users in your account
do as well. That way, if a password or access key is compromised without your knowledge, you limit
how long the credentials can be used to access your resources. You can apply a password policy to your
account to require all your IAM users to rotate their passwords, and you can choose how often they must
do so.
For more information about setting a password policy in your account, see Setting an Account Password
Policy for IAM Users (p. 65).
For more information about rotating access keys for IAM users, see Rotating Access Keys (p. 77).
Remove Unnecessary Credentials
Remove IAM user credentials (that is, passwords and access keys) that are not needed. For example,
an IAM user that is used for an application does not need a password (passwords are necessary only to
sign in to AWS websites). Similarly, if a user does not and will never use access keys, there's no reason
for the user to have them. Passwords and access keys that have not been used recently might be good
candidates for removal. You can find unused passwords or access keys using the console, using the API,
or by downloading the credentials report.
For more information about finding IAM user credentials that have not been used recently, see Finding
Unused Credentials (p. 79).
For more information about deleting passwords for an IAM user, see Managing Passwords for IAM
Users (p. 68).
For more information about deactivating or deleting access keys for an IAM user, see Managing Access
Keys for IAM Users (p. 74).
For more information about IAM credential reports, see Getting Credential Reports for Your AWS
Account (p. 82).
Use Policy Conditions for Extra Security
To the extent that it's practical, define the conditions under which your IAM policies allow access to
a resource. For example, you can write conditions to specify a range of allowable IP addresses that a
38
AWS Identity and Access Management User Guide
Monitor Activity in Your AWS Account
request must come from. You can also specify that a request is allowed only within a specified date range
or time range. You can also set conditions that require the use of SSL.
For more information, see Condition (p. 385) in the IAM Policy Elements Reference.
Monitor Activity in Your AWS Account
You can use logging features in AWS to determine the actions users have taken in your account and the
resources that were used. The log files show the time and date of actions, the source IP for an action,
which actions failed due to inadequate permissions, and more.
Logging features are available in the following AWS services:
• Amazon CloudFront – Logs user requests that CloudFront receives. For more information, see Access
Logs in the Amazon CloudFront Developer Guide.
• AWS CloudTrail – Logs AWS API calls and related events made by or on behalf of an AWS account. For
more information, see the AWS CloudTrail User Guide.
• Amazon CloudWatch – Monitors your AWS Cloud resources and the applications you run on AWS. You
can set alarms in CloudWatch based on metrics that you define. For more information, see the Amazon
CloudWatch User Guide.
• AWS Config – Provides detailed historical information about the configuration of your AWS resources,
including your IAM users, groups, roles, and policies. For example, you can use AWS Config to
determine the permissions that belonged to a user or group at a specific time. For more information,
see the AWS Config Developer Guide.
• Amazon Simple Storage Service (Amazon S3) – Logs access requests to your Amazon S3 buckets. For
more information, see Server Access Logging in the Amazon Simple Storage Service Developer Guide.
Business Use Cases
A simple business use case for IAM can help you understand basic ways you might implement the service
to control the AWS access that your users have. The use case is described in general terms, without the
mechanics of how you'd use the IAM API to achieve the results you want.
This use case looks at two typical ways a fictional company called Example Corp might use IAM. The first
scenario considers Amazon Elastic Compute Cloud (Amazon EC2). The second considers Amazon Simple
Storage Service (Amazon S3).
For more information about using IAM with other services from AWS, see AWS Services That Work with
IAM (p. 363).
Topics
• Initial Setup of Example Corp (p. 39)
• Use Case for IAM with Amazon EC2 (p. 40)
• Use Case for IAM with Amazon S3 (p. 40)
Initial Setup of Example Corp
Joe is the founder of Example Corp. Upon starting the company, he creates his own AWS account
and uses AWS products by himself. Then he hires employees to work as developers, admins, testers,
managers, and system administrators.
Joe uses the AWS Management Console to create a group called Admins. He gives the Admins group
permissions to perform all actions on all the AWS account's resources using the AWS managed policy
39
AWS Identity and Access Management User Guide
Use Case for IAM with Amazon EC2
AdministratorAccess. For a step-by-step guide to creating an Administrators group and an IAM user for
yourself, then adding your user to the Administrators group, see Creating Your First IAM Admin User and
Group (p. 14).
Joe also creates a group called AllUsers so that he can easily apply any account-wide permissions to all
users in the AWS account. He adds himself to the group. He then creates a group called Developers, a
group called Testers, a group called Managers, and a group called SysAdmins. He creates users for each
of his employees, and puts the users in their respective groups. He also adds them all to the AllUsers
group. For information about creating groups, see Creating IAM Groups (p. 93). For information about
creating users, see Creating an IAM User in Your AWS Account (p. 54). For information about adding
users to groups, see Managing IAM Groups (p. 94).
Use Case for IAM with Amazon EC2
A company like Example Corp typically uses IAM to interact with services like Amazon EC2. To
understand this part of the use case, you need a basic understanding of Amazon EC2. For more
information about Amazon EC2, go to the Amazon EC2 User Guide for Linux Instances.
Amazon EC2 Permissions for the Groups
To provide "perimeter" control, Joe attaches a policy to the AllUsers group. This policy denies any AWS
request from a user if the originating IP address is outside Example Corp's corporate network.
At Example Corp, different groups require different permissions:
• System Administrators – Need permission to create and manage AMIs, instances, snapshots, volumes,
security groups, and so on. Joe attaches a policy to the SysAdmins group that gives members of the
group permission to use all the Amazon EC2 actions.
• Developers – Need the ability to work with instances only. Joe therefore attaches a policy to the
Developers group that allows developers to call DescribeInstances, RunInstances, StopInstances,
StartInstances, and TerminateInstances.
Note
Amazon EC2 uses SSH keys, Windows passwords, and security groups to control who has
access to the operating system of specific Amazon EC2 instances. There's no method in the
IAM system to allow or deny access to the operating system of a specific instance.
• Managers – Should not be able to perform any Amazon EC2 actions except listing the Amazon EC2
resources currently available. Therefore, Joe attaches a policy to the Managers group that only lets
them call Amazon EC2 "Describe" APIs.
For examples of what these policies might look like, see Example Policies (p. 298) and Using AWS
Identity and Access Management in the Amazon EC2 User Guide for Linux Instances.
User's Role Change
At some point, one of the developers, Don, changes roles and becomes a manager. Joe moves Don from
the Developers group to the Managers group. Now that he's in the Managers group, Don's ability to
interact with Amazon EC2 instances is limited. He can't launch or start instances. He also can't stop or
terminate existing instances, even if he was the user who launched or started the instance. He can list
only the instances that Example Corp users have launched.
Use Case for IAM with Amazon S3
Companies like Example Corp would also typically use IAM with Amazon S3. Joe has created an Amazon
S3 bucket for the company called example_bucket.
40
AWS Identity and Access Management User Guide
Use Case for IAM with Amazon S3
Creation of Other Users and Groups
As employees, Don and Mary each need to be able to create their own data in the company's bucket.
They also need to read and write shared data that all developers work on. To enable this, Joe logically
arranges the data in example_bucket using an Amazon S3 key prefix scheme as shown in the following
figure.
/example_bucket
/home
/don
/mary
/share
/developers
/managers
Joe divides the master /example_bucket into a set of home directories for each employee, and a shared
area for groups of developers and managers.
Now Joe creates a set of policies to assign permissions to the users and groups:
• Home directory access for Don – Joe attaches a policy to Don that lets him read, write, and list any
objects with the Amazon S3 key prefix /example_bucket/home/don/
• Home directory access for Mary – Joe attaches a policy to Mary that lets her read, write, and list any
objects with the Amazon S3 key prefix /example_bucket/home/mary/
• Shared directory access for the Developers group – Joe attaches a policy to the group that lets
developers read, write, and list any objects in /example_bucket/share/developers/
• Shared directory access for the Managers group – Joe attaches a policy to the group that lets
managers read, write, and list objects in /example_bucket/share/managers/
Note
Amazon S3 doesn't automatically give a user who creates a bucket or object permission to
perform other actions on that bucket or object. Therefore, in your IAM policies, you must
explicitly give users permission to use the Amazon S3 resources they create.
For examples of what these policies might look like, see Access Control in the Amazon Simple Storage
Service Developer Guide. For information on how policies are evaluated at run time, see IAM Policy
Evaluation Logic (p. 405).
User's Role Change
At some point, one of the developers, Don, changes roles and becomes a manager. We assume that he
no longer needs access to the documents in the share/developers directory. Joe, as an admin, moves
Don to the Managers group and out of the Developers group. With just that simple reassignment, Don
automatically gets all permissions granted to the Managers group, but can no longer access data in the
share/developers directory.
Integration with a Third-Party Business
Organizations often work with partner companies, consultants, and contractors. Example Corp has a
partner called the Widget Company, and a Widget Company employee named Natalie needs to put data
into a bucket for Example Corp's use. Joe creates a group called WidgetCo and a user named Natalie and
adds Natalie to the WidgetCo group. Joe also creates a special bucket called example_partner_bucket for
Natalie to use.
Joe updates existing policies or adds new ones to accommodate the partner Widget Company. For
example, Joe can create a new policy that denies members of the WidgetCo group the ability to use any
41
AWS Identity and Access Management User Guide
Use Case for IAM with Amazon S3
actions other than write. This policy would be necessary only if there's a broad policy that gives all users
access to a wide set of Amazon S3 actions.
42
AWS Identity and Access Management User Guide
The IAM User Sign-in Page
The IAM Console and Sign-in Page
The AWS Management Console provides a web-based way to administer AWS services. You can sign
in to the console and create, list, and perform other tasks with AWS services for your account. These
tasks might include starting and stopping Amazon EC2 instances and Amazon RDS databases, creating
Amazon DynamoDB tables, creating IAM users, and so on.
When you first create an Amazon Web Services (AWS) account, you begin with a single sign-in identity
that has complete access to all AWS services and resources in the account. This identity is called the AWS
account root user and is accessed by signing in with the email address and password that you used to
create the account.
Important
We strongly recommend that you do not use the root user for your everyday tasks, even the
administrative ones. Instead, adhere to the best practice of using the root user only to create
your first IAM user. Then securely lock away the root user credentials and use them to perform
only a few account and service management tasks. To view the tasks that require you to sign
in as the root user, see AWS Tasks That Require Root User. For a tutorial on how to set up an
administrator for daily use, see Creating Your First IAM Admin User and Group (p. 14).
This section provides information about the AWS Management Console sign-in page. It explains how to
create a unique sign-in URL for IAM users in your account, and how to sign in as the root user.
Note
If your organization has an existing identity system, you might want to create a single sign-on
(SSO) option. SSO gives users access to the AWS Management Console for your account without
requiring them to have an IAM user identity. SSO also eliminates the need for users to sign in
to your organization's site and to AWS separately. For more information, see Creating a URL
that Enables Federated Users to Access the AWS Management Console (Custom Federation
Broker) (p. 132).
The IAM User Sign-in Page
To use the AWS Management Console, IAM users must provide their account ID or account alias in
addition to their user name and password. When you, as an administrator, create an IAM user in the
console (p. 55), you must send the sign-in credentials to that user, including the user name and the
URL to the account sign-in page.
43
AWS Identity and Access Management User Guide
Controlling User Access to the AWS Management Console
Important
Depending on how you set up the IAM user, provide all users with a temporary password
for their first sign-in. For detailed information about passwords , see Managing
Passwords (p. 65).
Your unique account sign-in page URL is created automatically when you begin using IAM. You do not
have to do anything to use this sign-in page.
https://My_AWS_Account_ID.signin.www.amazonaws.cn/console/
You can also customize the account sign-in URL for your account if you want the URL to contain
your company name (or other friendly identifier) instead of your AWS account ID number. For more
information about creating an account alias, see Your AWS Account ID and Its Alias (p. 45).
Tip
To create a bookmark for your account sign-in page in your web browser, you should manually
type the sign-in URL for your account in the bookmark entry. Do not use your web browser
bookmark feature because redirects can obscure the sign-in URL.
You can find the URL for your account sign-in page anytime by viewing the dashboard of the IAM
console.
IAM users can also sign in at the following general sign-in endpoint and type an account ID or account
alias manually:
https://console.amazonaws.cn/
Note
To find your AWS account ID number on the AWS Management Console, choose Support on the
navigation bar on the upper-right, and then choose Support Center. Your currently signed-in
account ID appears in the upper-right corner below the Support menu.
For convenience, the AWS sign-in page uses a browser cookie to remember the IAM user name and
account information. The next time the user goes to any page in the AWS Management Console, the
console uses the cookie to redirect the user to the account sign-in page.
Controlling User Access to the AWS Management
Console
Users who sign in to your AWS account through the sign-in page can access your AWS resources through
the AWS Management Console to the extent that you grant them permission. The following list shows
44
AWS Identity and Access Management User Guide
Your AWS Account ID and Its Alias
the ways you can grant users access to your AWS account resources through the AWS Management
Console. It also shows how users can access other AWS account features through the AWS website.
Note
There is no charge to use IAM.
The AWS Management Console
You create a password for each user who needs access to the AWS Management Console. Users
access the console via your IAM-enabled AWS account sign-in page. For information about accessing
the sign-in page, see The IAM Console and Sign-in Page (p. 43). For information about creating
passwords, see Managing Passwords (p. 65).
Your AWS resources, such as Amazon EC2 instances, Amazon S3 buckets, and so on
Even if your users have passwords, they still need permission to access your AWS resources. When
you create a user, that user has no permissions by default. To give your users the permissions
they need, you attach policies to them. If you have many users who will be performing the
same tasks with the same resources, you can assign those users to a group, then assign the
permissions to that group. For information about creating users and groups, see Identities (Users,
Groups, and Roles) (p. 50). For information about using policies to set permissions, see Access
Management (p. 222).
AWS Discussion Forums
Anyone can read the posts on the AWS Discussion Forums. Users who want to post questions or
comments to the AWS Discussion Forum can do so using their user name. The first time a user posts
to the AWS Discussion Forum, the user is prompted to enter a nickname and email address for use
only by that user in the AWS Discussion Forums.
Your AWS account billing and usage information
You can grant users access your AWS account billing and usage information. For more information,
see Controlling Access to Your Billing Information in the AWS Billing and Cost Management User
Guide.
Your AWS account profile information
Users cannot access your AWS account profile information.
Your AWS account security credentials
Users cannot access your AWS account security credentials.
Note
IAM policies control access regardless of the interface. For example, you could provide a user
with a password to access the AWS Management Console, and the policies for that user (or
any groups the user belongs to) would control what the user can do in the AWS Management
Console. Or, you could provide the user with AWS access keys for making API calls to AWS, and
the policies would control which actions the user could call through a library or client that uses
those access keys for authentication.
Your AWS Account ID and Its Alias
Finding Your AWS Account ID
To find your AWS account ID number on the AWS Management Console, choose Support on the
navigation bar on the upper-right, and then choose Support Center. Your currently signed-in account ID
appears in the upper-right corner below the Support menu.
45
AWS Identity and Access Management User Guide
About Account Aliases
About Account Aliases
If you want the URL for your sign-in page to contain your company name (or other friendly identifier)
instead of your AWS account ID, you can create an alias for your AWS account ID. This section provides
information about AWS account aliases and lists the API actions you use to create an alias.
Your sign-in page URL has the following format, by default.
https://Your_AWS_Account_ID.signin.www.amazonaws.cn/console/
If you create an AWS account alias for your AWS account ID, your sign-in page URL will look like the
following example.
https://Your_Alias.signin.www.amazonaws.cn/console/
Note
The original URL containing your AWS account ID remains active and can be used after you
create your AWS account alias.
Tip
To create a bookmark for your account sign-in page in your web browser, you should manually
type the sign-in URL in the bookmark entry. Don't use your web browser's "bookmark this page"
feature.
Creating, Deleting, and Listing an AWS Account Alias
You can use the AWS Management Console, the IAM API, or the command line interface to create or
delete your AWS account alias.
Important
Your AWS account can have only one alias. If you create a new alias for your AWS account, the
new alias overwrites the old alias, and the URL containing the old alias stops working.
AWS Management Console
To create or remove an account alias
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
3.
4.
5.
On the navigation pane, select Dashboard.
Find the IAM users sign-in link, and click Customize to the right of the link.
Type the name you want to use for your alias, then click Yes, Create.
To remove the alias, click Customize, and then click Yes, Delete. The sign-in URL reverts to using
your AWS account ID.
API or CLI
To create an alias for your AWS Management Console sign-in page URL
46
AWS Identity and Access Management User Guide
IAM Console Search
• AWS CLI: aws iam create-account-alias
• Tools for Windows PowerShell: New-IAMAccountAlias
• AWS API: CreateAccountAlias
To delete an AWS account ID alias
• AWS CLI:aws iam delete-account-alias
• Tools for Windows PowerShell: Remove-IAMAccountAlias
• AWS API: DeleteAccountAlias
To display your AWS account ID alias
• AWS CLI: aws iam list-account-aliases
• Tools for Windows PowerShell: Get-IAMAccountAlias.html
• AWS API: ListAccountAliases
Note
The account alias must be unique across all Amazon Web Services products. It must contain only
digits, lowercase letters, and hyphens. For more information on limitations on AWS account
entities, see Limitations on IAM Entities and Objects (p. 360).
IAM Console Search
As you navigate through the IAM Management Console to manage various IAM resources, you often need
to locate access keys or browse to the deeply nested IAM resources to find items you need to work with.
A faster option is to use the IAM console search page to locate access keys related to your account, IAM
entities (such as users, groups, roles, identity providers), policies by name, and more.
The IAM console search feature can locate any of the following:
• IAM entity names that match your search keywords (for users, groups, roles, identity providers, and
policies)
• AWS documentation topic names that match your search keywords
• Tasks that match your search keywords
Every line in the search result is an active link. For example, you can choose the user name in the search
result, which takes you to that user's detail page. Or you can choose an action link, for example Create
user, to go to the Create User page.
Note
Access key search requires you to type the full access key ID in the search box. The search result
shows the user associated with that key. From there you can navigate directly to that user's
page, where you can manage their access key.
Using IAM Console Search
Use the Search page in the IAM console to find items related to that account.
To search for items in the IAM console
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
47
AWS Identity and Access Management User Guide
Icons in the IAM Console Search Results
2.
In the navigation pane, choose Search.
3.
In the Search box, type your search keyword(s).
4.
Choose a link in the search results list to navigate to the corresponding part of the console or
documentation.
Icons in the IAM Console Search Results
The following icons identify the types of items that are found by a search:
Icon
Description
IAM users
IAM groups
IAM roles
IAM policies
Tasks such as "create user" or "attach policy"
Results from the keyword delete
IAM documentation
Sample Search Phrases
You can use the following phrases in the IAM search. Replace terms in italics with the names of actual
IAM users, groups, roles, access keys, policies, or identity providers respectively that you want to locate.
• user_name or group_name or role_name or policy_name or identity_provider_name
• access_key
• add user user_name to groups or add users to group group_name
• remove user user_name from groups
• delete user_name or delete group_name or delete role_name, or delete policy_name, or
delete identity_provider_name
• manage access keys user_name
• manage signing certificates user_name
• users
• manage password for user_name
• create role
48
AWS Identity and Access Management User Guide
Sample Search Phrases
• password policy
• edit trust policy for role role_name
• show policy document for role role_name
• attach policy to role_name
• create managed policy
• create user
• create group
• attach policy to group_name
• attach entities to policy_name
• detach entities to policy_name
• what is IAM
• how do I create an IAM user
• how do I use IAM console
• what is a user or what is a group, or what is a policy, or what is a role, or what is an
identity provider
49
AWS Identity and Access Management User Guide
IAM Users
Identities (Users, Groups, and Roles)
This section describes IAM identities, which you create to provide authentication for people and processes
in your AWS account. This section also describes IAM groups, which are collections of IAM users that
you can manage as a unit. Identities represent the user, and can be authenticated and then authorized
to perform actions in AWS. Each of these can be associated with one or more policies (p. 222) to
determine what actions a user, role, or member of a group can do with which AWS resources and under
what conditions.
IAM Users (p. 52)
An IAM user (p. 52) is an entity that you create in AWS. The IAM user represents the person or service
who uses the IAM user to interact with AWS. A primary use for IAM users is to give people the ability to
sign in to the AWS Management Console for interactive tasks and to make programmatic requests to
AWS services using the API or CLI. A user in AWS consists of a name, a password to sign into the AWS
Management Console, and up to two access keys that can be used with the API or CLI. When you create
an IAM user, you grant it permissions by making it a member of a group that has appropriate permission
policies attached (recommended), or by directly attaching policies to the user. You can also clone the
permissions of an existing IAM user, which automatically makes the new user a member of the same
groups and attaches all the same policies.
IAM Groups (p. 92)
An IAM group (p. 92) is a collection of IAM users. You can use groups to specify permissions for a
collection of users, which can make those permissions easier to manage for those users. For example,
you could have a group called Admins and give that group the types of permissions that administrators
typically need. Any user in that group automatically has the permissions that are assigned to the group.
If a new user joins your organization and should have administrator privileges, you can assign the
appropriate permissions by adding the user to that group. Similarly, if a person changes jobs in your
organization, instead of editing that user's permissions, you can remove him or her from the old groups
and add him or her to the appropriate new groups. Note that a group is not truly an identity because
it cannot be identified as a Principal in an access policy. It is only a way to attach policies to multiple
users at one time.
50
AWS Identity and Access Management User Guide
IAM Roles
IAM Roles (p. 97)
An IAM role (p. 97) is very similar to a user, in that it is an identity with permission policies that
determine what the identity can and cannot do in AWS. However, a role does not have any credentials
(password or access keys) associated with it. Instead of being uniquely associated with one person, a role
is intended to be assumable by anyone who needs it. An IAM user can assume a role to temporarily take
on different permissions for a specific task. A role can be assigned to a federated user (p. 105) who
signs in by using an external identity provider instead of IAM. AWS uses details passed by the identity
provider to determine which role is mapped to the federated user.
Temporary Credentials (p. 193)
Temporary credentials are primarily used with IAM roles, but there are also other uses. You can request
temporary credentials that have a more restricted set of permissions than your standard IAM user.
This prevents you from accidentally performing tasks that are not permitted by the more restricted
credentials. A benefit of temporary credentials is that they expire automatically after a set period of
time. You have control over the duration that the credentials are valid.
When to Create an IAM User (Instead of a Role)
Because an IAM user is just an identity with specific permissions in your account, you might not need
to create an IAM user for every occasion on which you need credentials. In many cases, you can take
advantage of IAM roles and their temporary security credentials instead of using the long-term
credentials associated with an IAM user.
• Other people in your group need to work in your AWS account, and your group is using no other
identity mechanism.
Create IAM users for the individuals who need access to your AWS resources, assign appropriate
permissions to each user, and give each user his or her own credentials. We strongly recommend that
you never share credentials among multiple users.
• You want to use the command-line interface (CLI) to work with AWS.
The CLI needs credentials that it can use to make calls to AWS. Create an IAM user and give that user
permissions to run the CLI commands you need. Then configure the CLI on your computer to use the
access key credentials associated with that IAM user.
When to Create an IAM Role (Instead of a User)
Create an IAM role in the following situations:
You're creating an application that runs on an Amazon Elastic Compute Cloud (Amazon EC2) instance
and that application makes requests to AWS.
Don't create an IAM user and pass the user's credentials to the application or embed the credentials
in the application. Instead, create an IAM role that you attach to the EC2 instance to give
applications running on the instance temporary security credentials. The credentials have the
permissions specified in the policies attached to the role. For details, see Using an IAM Role to Grant
Permissions to Applications Running on Amazon EC2 Instances (p. 177).
51
AWS Identity and Access Management User Guide
Users
You're creating an app that runs on a mobile phone and that makes requests to AWS.
Don't create an IAM user and distribute the user's access key with the app. Instead, use an identity
provider like Login with Amazon, Amazon Cognito, Facebook, or Google to authenticate users and
map the users to an IAM role. The app can use the role to get temporary security credentials that
have the permissions specified by the policies attached to the role. For more information, see the
following:
• Amazon Cognito Overview in the AWS Mobile SDK for Android Developer Guide
• Amazon Cognito Overview in the AWS Mobile SDK for iOS Developer Guide
• About Web Identity Federation (p. 106)
Users in your company are authenticated in your corporate network and want to be able to use AWS
without having to sign in again—that is, you want to allow users to federate into AWS.
Don't create IAM users. Configure a federation relationship between your enterprise identity system
and AWS. You can do this in two ways:
• If your company's identity system is compatible with SAML 2.0, you can establish trust between
your company's identity system and AWS. For more information, see About SAML 2.0-based
Federation (p. 112).
• Create and use a custom proxy server that translates user identities from the enterprise into IAM
roles that provide temporary AWS security credentials. For more information, see Creating a
URL that Enables Federated Users to Access the AWS Management Console (Custom Federation
Broker) (p. 132).
IAM Users
An IAM user is an entity that you create in AWS to represent the person or service that uses it to interact
with AWS. A user in AWS consists of a name and credentials.
Important
If you arrived at this page while trying to enable Amazon Advertising for your application or web
site, see Becoming a Product Advertising API Developer.
How AWS identifies an IAM user
When you create a user, IAM creates these ways to identify that user:
• A "friendly name" for the user, which is the name that you specified when you created the user, such as
Bob or Alice. These are the names you see in the AWS Management Console.
• An Amazon Resource Name (ARN) for the user. You use the ARN when you need to uniquely identify
the user across all of AWS, such as when you specify the user as a Principal in an IAM policy for an
Amazon S3 bucket. An ARN for an IAM user might look like the following:
arn:aws-cn:iam::account-ID-without-hyphens:user/Bob
• A unique identifier for the user. This ID is returned only when you use the API, Tools for Windows
PowerShell, or AWS CLI to create the user; you do not see this ID in the console.
For more information about these identifiers, see IAM Identifiers (p. 356).
Users and credentials
You can access AWS in different ways depending on the user credentials:
• Console password (p. 65): A password that the user can type to sign in to interactive sessions such
as the AWS Management Console.
52
AWS Identity and Access Management User Guide
Users and permissions
• Access keys (p. 74): A combination of an access key ID and a secret access key. You can assign two to
a user at a time. These can be used to make programmatic calls to AWS when using the API in program
code or at a command prompt when using the AWS CLI or the AWS PowerShell tools.
• SSH keys for use with AWS CodeCommit (p. 86): An SSH public key in the OpenSSH format that
can be used to authenticate with AWS CodeCommit.
• Server certificates (p. 87): SSL/TLS certificates that you can use to authenticate with some AWS
services. We recommend that you use AWS Certificate Manager (ACM) to provision, manage, and
deploy your server certificates. Use IAM only when you must support HTTPS connections in a region
that is not supported by ACM. To learn which regions support ACM, see the AWS Certificate Manager
section of the AWS General Reference.
By default, a brand new IAM user has no password and no access key (neither an access key ID nor a
secret access key)—no credentials of any kind. You must create the type of credentials for an IAM user
based on what the user will be doing.
Take advantage of the following options to administer passwords and access keys:
• Manage passwords for your IAM users (p. 65). Create and change the passwords that permit
access to the AWS Management Console. Set a password policy to enforce a minimum password
complexity. Allow users to change their own passwords.
• Manage access keys for your IAM users (p. 74). Create and update access keys for programmatic
access to the resources in your account.
• Find unused passwords and access keys (p. 79). Anyone who has a password or access keys for
your account or an IAM user in your account has access to your AWS resources. The security best
practice is to remove passwords and access keys when users no longer need them.
• Download a credential report for your account (p. 82). You can generate and download a
credential report that lists all IAM users in your account and the status of their various credentials,
including passwords, and access keys. For passwords and access keys, the credential report shows how
recently the password or access key has been used.
Users and permissions
By default, a brand new IAM user has no permissions (p. 222) to do anything. The user is not authorized
to perform any AWS actions or to access any AWS resources. An advantage of having individual IAM users
is that you can assign permissions individually to each user. You might assign administrative permissions
to a few users, who then can administer your AWS resources and can even create and manage other IAM
users. In most cases, however, you want to limit a user's permissions to just the tasks (AWS actions) and
resources that the user needs for his or her job. Imagine a user named Dave. When you create the IAM
user Dave, you create a password for that user and attach permissions to the IAM user that let him launch
a specific Amazon EC2 instance and read (GET) information from a table in an Amazon RDS database.
For procedures on how to create users and grant them initial credentials and permissions, see Creating
an IAM User in Your AWS Account (p. 54). For procedures on how to change the permissions for
existing users, see Changing Permissions for an IAM User (p. 62). For procedures on how to change
the user's password or access keys, see Managing Passwords (p. 65) and Managing Access Keys for IAM
Users (p. 74).
Users and accounts
Each IAM user is associated with one and only one AWS account. Because users are defined within your
AWS account, they don't need to have a payment method on file with AWS. Any AWS activity performed
by users in your account is billed to your account.
There's a limit to the number of IAM users you can have in an AWS account. For more information, see
Limitations on IAM Entities and Objects (p. 360).
53
AWS Identity and Access Management User Guide
Users as service accounts
Users as service accounts
An IAM user doesn't necessarily have to represent an actual person. An IAM user is really just an identity
with associated credentials and permissions. You might create an IAM user to represent an application
that needs credentials in order to make requests to AWS. This is typically referred to as a "service
account." An application might have its own service account in your AWS account, and its own set of
permissions, the same way that processes have their own service accounts defined in an operating
system like Windows or Linux.
Creating an IAM User in Your AWS Account
You can create one or more IAM users in your AWS account. You might create an IAM user when someone
joins your organization, or when you have a new application that needs to make API calls to AWS.
Important
If you arrived at this page trying to enable Amazon Advertising for your application or website,
see Becoming a Product Advertising API Developer.
If you arrived at this page from the IAM console, it is possible that your account does not include
IAM users, even though you are logged in. You could be signed in as the AWS account root user,
using a role, or signed in with temporary credentials. To learn more about these IAM identities,
see Identities (Users, Groups, and Roles) (p. 50).
Topics
• Creating IAM Users (Console) (p. 55)
• Creating IAM Users (AWS CLI, Tools for Windows PowerShell, or IAM HTTP API) (p. 56)
In outline, the process of creating a user and making it usable for work tasks consists of these steps:
1. Create the user in the AWS Management Console or from an AWS CLI, Tools for Windows PowerShell,
or IAM API command. If you create the user in the AWS Management Console, then steps 1–4 are
handled automatically. If you create the users programmatically, then you must perform each of those
steps individually.
2. Create credentials for the user, depending on the type of access the user requires:
• Programmatic access: The IAM user might need to make API calls or use the AWS CLI or the Tools
for Windows PowerShell. In that case, create an access key (an access key ID and a secret access key)
for that user.
AWS Management Console access: If the user needs to access AWS resources from the AWS
Management Console, create a password for the user (p. 68).
As a best practice, do not create credentials of a certain type for a user who will never need that kind
of access. For example, for a user who requires access through the AWS Management Console only, do
not create access keys.
3. Give the user permissions to perform the required tasks by adding the user to one or more groups.
You can grant permissions by attaching IAM permission policies directly to the user. However, we
recommend instead that you put your users in groups and manage permissions through policies that
are attached to those groups.
4. Provide the user with the necessary sign-in information. This includes the password and the URL for
the account sign-in webpage where the user enters those credentials. For more information, see How
IAM Users Sign In to AWS (p. 57).
5. (Optional) Give users permissions to manage their own security credentials. (By default, users do not
have permissions to manage their own credentials.) For more information, see Permitting IAM Users to
Change Their Own Passwords (p. 71).
54
AWS Identity and Access Management User Guide
Adding a User
For information about the permissions that you need in order to create a user, see Delegating
Permissions to Administer IAM Users, Groups, and Credentials (p. 225).
Creating IAM Users (Console)
To create one or more IAM users from the AWS Management Console
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Users and then choose Add user.
3.
Type the user name for the new user. This is the sign-in name for AWS. If you want to add more than
one user at the same time, choose Add another user for each additional user and type their user
names. You can add up to 10 users at one time.
Note
User names can be a combination of up to 64 letters, digits, and these characters: plus (+),
equal (=), comma (,), period (.), at sign (@), and hyphen (-). Names must be unique within
an account. They are not distinguished by case. For example, you cannot create two users
named TESTUSER and testuser. For more information about limitations on IAM entities, see
Limitations on IAM Entities and Objects (p. 360).
4.
Select the type of access this set of users will have. You can select programmatic access, access to
the AWS Management Console, or both.
• Select Programmatic access if the users require access to the API, AWS CLI, or Tools for Windows
PowerShell. This creates an access key for each new user. You can view or download the access
keys when you get to the Final page.
• Select AWS Management Console access if the users require access to the AWS Management
Console. This creates a password for each new user.
1.
For Console password type, choose one of the following:
• Autogenerated password. Each user gets a randomly generated password that meets the
current password policy in effect (if any). You can view or download the passwords when
you get to the Final page.
• Custom password. Each user is assigned the password that you type in the box.
2.
(Optional) We recommend that you choose Require password reset to ensure that users are
forced to change their password the first time they sign in.
Note
If you have not enabled the account-wide password policy setting Allow users to
change their own password, then selecting Require password reset automatically
attaches an AWS managed policy named IAMUserChangePassword to the new users
that grants them permission to change their own passwords.
5.
Choose Next: Permissions.
6.
On the Set permissions page, specify how you want to assign permissions to this set of new users.
Choose one of the following three options:
55
AWS Identity and Access Management User Guide
Adding a User
• Add user to group. Choose this option if you have groups with appropriate permission policies
already created and want to assign the users to those groups. IAM displays a list of all currently
defined groups, along with their attached policies. You can select one or more existing groups, or
choose Create group to create a new group. For more information, see Changing Permissions for
an IAM User (p. 62).
• Copy permissions from existing user. Choose this option to copy all of the group memberships,
attached managed policies, and embedded inline policies from an existing user to the new users.
IAM displays a list of currently defined users. Select the one whose permissions most closely
match the needs of your new users. Each new user gets the same group memberships and
attached policies as the selected user.
• Attach existing policies to user directly Choose this option to select from existing managed
policies or to create new managed policies that are attached to the new users. IAM displays a list
of currently defined managed policies, both AWS and customer-defined. Select the policies that
you want to attach to the new users or choose Create policy to create a new policy from scratch.
For more information, see step 4 in the procedure Create a Policy (p. 248).
7.
Choose Next: Review to see all of the choices you made up to this point. When you are ready to
proceed, choose Create user.
8.
To view the users' access keys (access key IDs and secret access keys), choose Show next to each
password and secret access key that you want to see. To save the access keys, choose Download .csv
and then save the file to a safe location.
Important
This is your only opportunity to view or download the secret access keys, and you must
provide this information to your users before they can use the AWS API. Save the user's new
access key ID and secret access key in a safe and secure place. You will not have access to
the secret keys again after this step.
9.
Provide each user with his or her credentials. On the final page you can choose Send email next
to each user. Your local mail client opens with a draft that you can customize and send. The email
template includes the following details to each user:
• User name
• URL to the account sign-in webpage. Use the following example, substituting the correct account
ID number or account alias:
https://AWS-account-ID or alias.signin.aws.amazon.com/console
For more information, see How IAM Users Sign In to AWS (p. 57).
Important
The user's password is not included in the generated email. You must provide them to the
customer in a way that complies with your organization's security guidelines.
10. (Optional) Grant the users permission to manage their own security credentials. For more
information, see Allow Users to Manage Their Own Passwords, Access Keys, and SSH Keys (p. 228).
Creating IAM Users (AWS CLI, Tools for Windows PowerShell, or
IAM HTTP API)
To create an IAM user from the AWS CLI, Tools for Windows PowerShell, or IAM HTTP API
1.
Create a user.
56
AWS Identity and Access Management User Guide
How IAM Users Sign In to AWS
• AWS CLI: aws iam create-user
• Tools for Windows PowerShell: New-IAMUser
• IAM API: CreateUser
2.
(Optional) Give the user access to the AWS Management Console. This requires a password. You
must also give the user the URL of your account's sign-in page. (p. 57)
• AWS CLI: aws iam create-login-profile
• Tools for Windows PowerShell: New-IAMLoginProfile
• IAM API: CreateLoginProfile
3.
(Optional) Give the user programmatic access. This requires access keys.
• AWS CLI: aws iam create-access-key
• Tools for Windows PowerShell: New-IAMAccessKey
• IAM API: CreateAccessKey
Important
This is your only opportunity to view or download the secret access keys, and you must
provide this information to your users before they can use the AWS API. Save the user's
new access key ID and secret access key in a safe and secure place. You will not have
access to the secret keys again after this step.
4.
Add the user to one or more groups. The groups that you specify should have attached policies that
grant the appropriate permissions for the user.
• AWS CLI: aws iam add-user-to-group
• Tools for Windows PowerShell: Add-IAMUserToGroup
• IAM API: AddUserToGroup
5.
(Optional) Attach a policy to the user Attach a policy that defines the user's permissions. Note: We
recommend that you manage user permissions by adding the user to a group and attaching a policy
to the group instead of attaching directly to a user.
• AWS CLI: aws iam attach-user-policy
• Tools for Windows PowerShell: Register-IAMUserPolicy
• IAM API: AttachUserPolicy
6.
(Optional) Give the user permission to manage his or her own security credentials. For more
information, see Allow Users to Manage Their Own Passwords, Access Keys, and SSH Keys (p. 228).
How IAM Users Sign In to AWS
To sign in to the AWS Management Console as an IAM user, you must provide your account ID or account
alias in addition to your user name and password. When your administrator created your IAM user in the
console (p. 55), they should have sent you your sign-in credentials, including your user name and the
URL to your account sign-in page that includes your account ID or account alias.
https://My_AWS_Account_ID.signin.www.amazonaws.cn/console/
Tip
To create a bookmark for your account sign-in page in your web browser, you should manually
type the sign-in URL for your account in the bookmark entry. Do not use your web browser
bookmark feature because redirects can obscure the sign-in URL.
You can also sign in at the following general sign-in endpoint and type your account ID or account alias
manually:
57
AWS Identity and Access Management User Guide
How IAM Users Sign In to AWS
https://console.amazonaws.cn/
For convenience, the AWS sign-in page uses a browser cookie to remember the IAM user name and
account information. The next time the user goes to any page in the AWS Management Console, the
console uses the cookie to redirect the user to the account sign-in page.
You have access only to the AWS resources that your administrator specifies in the policy that is attached
to your IAM user identity. To work in the console, you must have permissions to perform the actions
that the console performs, such as listing and creating AWS resources. For more information, see Access
Management (p. 222) and Example Policies (p. 298).
Note
If your organization has an existing identity system, you might want to create a single sign-on
(SSO) option. SSO gives users access to the AWS Management Console for your account without
requiring them to have an IAM user identity. SSO also eliminates the need for users to sign in
to your organization's site and to AWS separately. For more information, see Creating a URL
that Enables Federated Users to Access the AWS Management Console (Custom Federation
Broker) (p. 132).
Logging sign-in details in CloudTrail
If you enable CloudTrail to log sign-in events to your logs, you need to be aware of how CloudTrail
chooses where to log the events.
• If your users sign-in directly to a console, they are redirected to either a global or a regional sign-in
endpoint, based on whether the selected service console supports regions. For example, the main
console home page supports regions, so if you sign in to the following URL:
https://alias.signin.aws.amazon.com/console
you are redirected to a regional sign-in endpoint such as https://us-east-2.signin.aws.amazon.com,
resulting in a regional CloudTrail log entry in the user's region's log:
On the other hand, the Amazon S3 console does not support regions, so if you sign in to the following
URL
https://alias.signin.aws.amazon.com/console/s3
AWS redirects you to the global sign-in endpoint at https://signin.aws.amazon.com, resulting in a
global CloudTrail log entry.
• You can manually request a certain regional sign-in endpoint by signing in to the region-enabled main
console home page using a URL syntax like the following:
https://alias.signin.aws.amazon.com/console?region=ap-southeast-1
AWS redirects you to the ap-southeast-1 regional sign-in endpoint and results in a regional CloudTrail
log event.
For more information about CloudTrail and IAM, see Logging IAM Events with AWS CloudTrail .
If users need programmatic access to work with your account, you can create an access key pair (an
access key ID and a secret access key) for each user, as described in Creating, Modifying, and Viewing
Access Keys (Console) (p. 75).
58
AWS Identity and Access Management User Guide
Managing Users
Managing IAM Users
Amazon Web Services offers multiple tools for managing the IAM users in your AWS account.
Topics
• Listing IAM Users (p. 59)
• Renaming an IAM User (p. 59)
• Deleting an IAM User (p. 60)
Listing IAM Users
You can list the IAM users in your AWS account or in a specific IAM group, and list all the groups that
a user is in. For information about the permissions that you need in order to list users, see Delegating
Permissions to Administer IAM Users, Groups, and Credentials (p. 225).
To list all the users in the account
• AWS Management Console: In the navigation pane, choose Users. The console displays the users in
your AWS account.
• AWS CLI: aws iam list-users
• Tools for Windows PowerShell: Get-IAMUsers
• AWS API: ListUsers
To list the users in a specific group
• AWS Management Console: In the navigation pane, choose Groups, choose the name of the group, and
then choose the Users tab.
• AWS CLI: aws iam get-group
• Tools for Windows PowerShell: Get-IAMGroup
• AWS API: GetGroup
To list all the groups that a user is in
• AWS Management Console: In the navigation pane, choose Users, choose the user name, and then
choose the Groups tab.
• AWS CLI: aws iam list-groups-for-user
• Tools for Windows PowerShell: Get-IAMGroupForUser
• AWS API: ListGroupsForUser
Renaming an IAM User
To change a user's name or path, you must use the AWS CLI, Tools for Windows PowerShell, or AWS
API. There is no option in the console to rename a user. For information about the permissions that
you need in order to rename a user, see Delegating Permissions to Administer IAM Users, Groups, and
Credentials (p. 225).
When you change a user's name or path, the following happens:
• Any policies attached to the user stay with the user under the new name.
• The user stays in the same groups under the new name.
59
AWS Identity and Access Management User Guide
Managing Users
• The unique ID for the user remains the same. For more information about unique IDs, see Unique
IDs (p. 359).
• Any resource or role policies that refer to the user as a principal (the user is being granted access) are
automatically updated to use the new name or path. For example, any queue-based policies in Amazon
SQS or resource-based policies in Amazon S3 are automatically updated to use the new name and
path.
IAM does not automatically update policies that refer to the user as a resource to use the new name or
path; you must manually do that. For example, imagine that user Bob has a policy attached to him that
lets him manage his security credentials. If an administrator renames Bob to Robert, the administrator
also needs to update that policy to change the resource from this:
arn:aws-cn:iam::111122223333:user/division_abc/subdivision_xyz/Bob
to this:
arn:aws-cn:iam::111122223333:user/division_abc/subdivision_xyz/Robert
This is true also if an administrator changes the path; the administrator needs to update the policy to
reflect the new path for the user.
To rename a user
• AWS CLI: aws iam update-user
• Tools for Windows PowerShell: Update-IAMUser
• AWS API: UpdateUser
Deleting an IAM User
You might delete an IAM user from your account if someone quits your company. If the user is only
temporarily away from your company, you can disable the user's credentials instead of deleting the user
entirely from the AWS account. That way, you can prevent the user from accessing the AWS account's
resources during the absence but you can re-enable the user later.
For more information about disabling credentials, see Managing Access Keys for IAM Users (p. 74). For
information about the permissions that you need in order to delete a user, see Delegating Permissions to
Administer IAM Users, Groups, and Credentials (p. 225).
Topics
• Deleting an IAM User (AWS Management Console) (p. 60)
• Deleting an IAM User (AWS CLI and Tools for Windows PowerShell) (p. 61)
Deleting an IAM User (AWS Management Console)
When you use the AWS Management Console to delete an IAM user, IAM automatically deletes the
following information for you:
• The user
• Any group memberships—that is, the user is removed from any IAM groups that the user was a
member of
• Any password associated with the user
• Any access keys belonging to the user
60
AWS Identity and Access Management User Guide
Managing Users
• All inline policies embedded in the user (policies that are applied to a user via group permissions are
not affected)
Note
Any managed policies attached to the user are detached from the user when the user is
deleted. Managed policies are not deleted when you delete a user.
To use the AWS Management Console to delete an IAM user
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Users, and then select the check box next to the user name that you
want to delete, not the name or row itself.
3.
At the top of the page, choose Delete user.
4.
In the confirmation dialog box, wait for the service last accessed data to load before you review the
data. The dialog box shows when each of the selected users last accessed an AWS service. If you
attempt to delete a user that has been active within the last 30 days, you must select an additional
check box to confirm that you want to delete the active user. If you want to proceed, choose Yes,
Delete.
Deleting an IAM User (AWS CLI and Tools for Windows PowerShell)
Unlike the AWS Management Console, when you delete a user with the AWS CLI or Tools for Windows
PowerShell you have to delete the items attached to the user manually. This procedure illustrates the
process. For a complete PowerShell code snippet, see the example in Remove-IAMUser.
To use the AWS CLI to delete a user from your account
1.
Delete the user's keys and certificates. This helps ensure that the user can't access your AWS
account's resources anymore. Note that when you delete a security credential, it's gone forever and
can't be retrieved.
aws iam delete-access-key and aws iam delete-signing-certificate
2.
Delete the user's password, if the user has one.
aws iam delete-login-profile
3.
Detach any policies that are attached to the user.
aws iam list-attached-user-policies (to list the policies attached to the user) and aws iam detachuser-policy (to detach the policies)
4.
Get a list of any groups the user was in, and remove the user from those groups.
aws iam list-groups-for-user and aws iam remove-user-from-group
5.
Delete the user.
aws iam delete-user
To use the Tools for Windows PowerShell to delete a user from your account
1.
Delete the user's keys and certificates. This helps ensure that the user can't access your AWS
account's resources anymore. Note that when you delete a security credential, it's gone forever and
can't be retrieved.
Remove-IAMAccessKey and Remove-IAMSigningCertificate
2.
Delete the user's password, if the user has one.
61
AWS Identity and Access Management User Guide
Changing Permissions for a User
Remove-IAMLoginProfile
3.
Detach any policies that are attached to the user.
Get-IAMAttachedUserPolicies (to list the policies attached to the user) and Remove-IAMUserPolicy
(to detach the policies).
4.
Get a list of any groups the user was in, and remove the user from those groups.
Get-IAMGroupForUser and Remove-IAMUserFromGroup.
5.
Delete the user.
Remove-IAMUser
Changing Permissions for an IAM User
You can change the permissions for an IAM user in your AWS account by changing its group
memberships or by attaching and detaching managed policies. A user gets its permissions through one
of the following methods:
Group membership
• Add or remove a user from a group.
• Add, remove, or edit a managed policy attached to the group. This policy can be customer-created
and managed, or it can be an AWS managed policy.
• Add, remove, or edit a group's inline policies. This kind of policy is always customer-created.
Direct policy attachment
• Add, remove, or edit a managed policy attached directly to a user. This policy can be customercreated and managed or it can be an AWS managed policy.
• Add, remove, or edit a user's inline policies. This kind of policy is always customer-created.
For information about the permissions that you need in order to modify the permissions for a user, see
Delegating Permissions to Administer IAM Users, Groups, and Credentials (p. 225).
Adding Permissions to a New or Existing User (Console)
You can change permissions associated with a user through one of three techniques:
• Add user to group (p. 62). Make the user a member of a group that already has policies attached.
Every member of the group receives the permissions granted by the group's policies.
• Copy permissions from existing user (p. 63). Copy all group memberships and attached managed
policies as well as all inline policies embedded in the source user.
• Attach policies directly to user (p. 64). Attach a managed policy directly to the user. As a best
practice (p. 36), we recommend that you instead attach your policies to a group and then make users
members of the appropriate groups.
Adding Permissions by Adding the User to a Group
To add permissions to a user by adding the user to a group
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Users.
62
AWS Identity and Access Management User Guide
Changing Permissions for a User
3.
Review the current group memberships for users in the Groups column of the console. If necessary,
add the column to the users table by completing the following steps:
1.
Above the table on the far right, choose the settings symbol (
).
2. In the Manage Columns dialog box, select the Groups column. Optionally, you can also clear the
check box for any column headings that you do not want to appear in the users table.
3. Choose Close to return to the list of users.
The Groups column tells you to which groups the user belongs. The field includes the group names
for up to two groups. If the user is a member of three or more groups, the first two groups are
shown (ordered.alphabetically), and the number of additional group memberships is included. For
example, if the user belongs to Group A, Group B, Group C, and Group D, then the field contains the
value Group A, Group B + 2 more. To see the total number of groups to which the user belongs, you
can add the Group count column to the users table.
4.
Choose the name of the user whose permissions you want to modify.
5.
Choose the Permissions tab, and then choose Add permissions. Under Grant permissions choose
Add user to group.
6.
Select the check box for each group that you want the user to join. The list shows each group's name
and the policies that the user receives if made a member of that group. The permissions in each
selected group apply to the user as soon as you complete the process.
7.
(Optional) In addition to selecting from existing groups, you can choose Create group to define a
new group:
a.
For Group name, type a name for your new group.
Note
Group names can be a combination of up to 128 letters, digits, and these characters:
plus (+), equal (=), comma (,), period (.), at sign (@), and hyphen (-). Names must be
unique within an account. They are not distinguished by case. For example, you cannot
create two groups named TESTGROUP and testgroup. For more information about
limitations on IAM entities, see Limitations on IAM Entities and Objects (p. 360).
8.
b.
Select one or more check boxes for the managed policies that you want to attach to the group.
You can also create a new managed policy by choosing Create policy. If you do, return to this
browser tab or window when the new policy is done; choose Refresh; and then choose the new
policy to attach it to your group. For more information, see Creating a New Policy (p. 247).
c.
Choose Create group.
d.
Back in the list of groups, select the check box for your new group.
Choose Next: Review to see the list of group memberships to be added to the user. Then choose
Add permissions.
The new permissions affect the user immediately.
Adding Permissions by Copying from Another User
To add permissions to a user by copying permissions from another user
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
Choose Users in the navigation pane, choose the name of the user whose permissions you want to
modify, and then choose the Permissions tab.
3.
Choose Add permissions, and then under Grant permissions choose Copy permissions from
existing user. The list displays available users along with their group memberships and attached
policies. If the full list of groups or policies don't fit on one line, you can choose the link for and n
63
AWS Identity and Access Management User Guide
Changing Permissions for a User
more. Doing that opens a new browser tab and see the full list of policies (Permissions tab) and
groups (Groups tab).
4.
Select the radio button next to the user whose permissions you want to copy.
5.
Choose Next: Review to see the list of changes that are to be made to the user. Then choose Add
permissions.
The new permissions affect the user immediately.
Adding Permissions by Attaching Policies Directly to the User
To add permissions to a user by directly attaching managed policies
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
Choose Users in the navigation pane, choose the name of the user whose permissions you want to
modify, and then choose the Permissions tab.
3.
Choose Add permissions, and then under Grant permissions, choose Attach existing policies
directly to user.
4.
Select one or more check boxes for the managed policies that you want to attach to the group. You
can also create a new managed policy by choosing Create policy. If you do, return to this browser
tab or window when the new policy is done. Choose Refresh; and then select the check box for the
new policy to attach it to your user. For more information, see Creating a New Policy (p. 247).
5.
Choose Next: Review to see the list of policies that are to be attached to the user. Then choose Add
permissions.
The new permissions affect the user immediately.
Removing Permissions from an Existing User (Console)
To revoke permissions for IAM users
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Users, choose the name of the user whose permissions you want to
modify, and then choose the Permissions tab.
The Permissions tab displays each policy that applies to the user, and how the user gets that policy.
3.
If you want to revoke permissions by removing an existing policy, view the Policy type to
understand how the user is getting that policy before choosing X to remove the policy:
• If the policy applies because of group membership, then choosing X removes the user from the
group. Because you might have multiple policies attached from a single group, if you remove
a user from a group, the user loses access to all policies that it received through that group
membership..
• If the policy is a managed policy attached directly to the user, then choosing X detaches the policy
from the user. This does not affect the policy itself or any other entity that the policy might be
attached to.
• If the policy is an inline embedded policy, then choosing X removes the policy from IAM. Inline
policies that are attached directly to a user exist only on that user.
64
AWS Identity and Access Management User Guide
Passwords
Adding and Removing Permissions from a User (AWS API, AWS
CLI, Tools for Windows PowerShell)
To add or remove permissions programmatically, you must add or remove the group memberships,
attach or detach the managed policies, or add or delete the inline policies. For more information, see the
following topics:
• Adding and Removing Users in an IAM Group (p. 95)
• Working with Managed Policies Using the AWS CLI or the IAM API (p. 254)
• Working with Inline Policies (AWS API, AWS CLI) (p. 257)
Managing Passwords
You can manage passwords for IAM users in your account. IAM users need passwords in order to access
the AWS Management Console. Users do not need passwords to access AWS resources programmatically
by using the AWS CLI, Tools for Windows PowerShell, the AWS SDKs or APIs. For those environments,
users need access keys (p. 74) instead.
Topics
• Setting an Account Password Policy for IAM Users (p. 65)
• Managing Passwords for IAM Users (p. 68)
• Permitting IAM Users to Change Their Own Passwords (p. 71)
• How IAM Users Change Their Own Password (p. 73)
Setting an Account Password Policy for IAM Users
You can set a password policy on your AWS account to specify complexity requirements and mandatory
rotation periods for your IAM users' passwords.
You can use a password policy to do these things:
• Set a minimum password length.
• Require specific character types, including uppercase letters, lowercase letters, numbers, and nonalphanumeric characters. Be sure to remind your users that passwords are case sensitive.
• Allow all IAM users to change their own passwords.
Note
When you allow your IAM users to change their own passwords, IAM automatically allows
them to view the password policy. IAM users need permission to view the account's password
policy in order to create a password that complies with the policy.
• Require IAM users to change their password after a specified period of time (enable password
expiration).
• Prevent IAM users from reusing previous passwords.
• Force IAM users to contact an account administrator when the user has allowed his or her password to
expire.
Important
The password settings described here apply only to passwords assigned to IAM users and do not
affect any access keys they might have. If a password expires, the user cannot sign-in to the AWS
Management Console. However, if the user has valid access keys, then the user can still run any
AWS CLI or Tools for Windows PowerShell commands or call any APIs through an application
that the user's permissions allow.
65
AWS Identity and Access Management User Guide
Passwords
When you create or change a password policy, most of the password policy settings are enforced the
next time your users change their passwords, but some of the settings are enforced immediately. For
example:
• When you set minimum length and character type requirements, the settings are enforced the next
time your users change their passwords. Users are not forced to change their existing passwords, even
if the existing passwords do not adhere to the updated password policy.
• When you set a password expiration period, the expiration period is enforced immediately. For
example, when you set a password expiration period of 90 days, all IAM users that currently have an
existing password that is more than 90 days old are forced to change their password at next sign-in.
For information about the permissions that you need in order to set a password policy, see Permitting
IAM Users to Change Their Own Passwords (p. 71).
The options currently available do not allow you to create what is commonly called a "lockout policy"
that locks a user out of the account after a specified number of failed sign-in attempts.
Topics
• Password Policy Options (p. 66)
• Setting a Password Policy (AWS Management Console) (p. 67)
• Setting a Password Policy (AWS CLI, Tools for Windows PowerShell, or AWS API) (p. 68)
Password Policy Options
The following list describes the options that are available when you configure a password policy for your
account.
Minimum password length
You can specify the minimum number of characters allowed in an IAM user password. You can enter
any number from 6 to 128.
Require at least one uppercase letter
You can require that IAM user passwords contain at least one uppercase character from the ISO basic
Latin alphabet (A to Z).
Require at least one lowercase letter
You can require that IAM user passwords contain at least one lowercase character from the ISO basic
Latin alphabet (a to z).
Require at least one number
You can require that IAM user passwords contain at least one numeric character (0 to 9).
Require at least one nonalphanumeric character
You can require that IAM user passwords contain at least one of the following nonalphanumeric
characters:
! @ # $ % ^ & * ( ) _ + - = [ ] { } | '
Allow users to change their own password
You can permit all IAM users in your account to use the IAM console to change their own passwords,
as described in Permitting IAM Users to Change Their Own Passwords (p. 71).
Alternatively, you can let only some users manage passwords, either for themselves or for others.
To do so, you clear the Allow users to change their own password check box. For more information
about using policies to limit who can manage passwords, see Permitting IAM Users to Change Their
Own Passwords (p. 71).
66
AWS Identity and Access Management User Guide
Passwords
Note
When you allow your IAM users to change their own passwords, IAM automatically allows
them to view the password policy. IAM users need permission to view the account's
password policy in order to create a password that complies with the policy.
Enable password expiration
You can set IAM user passwords to be valid for only the specified number of days. You specify the
number of days that passwords remain valid after they are set. For example, when you enable
password expiration and set the password expiration period to 90 days, an IAM user can use a
password for up to 90 days. After 90 days, the password expires and the IAM user must set a new
password before accessing the AWS Management Console. You can choose a password expiration
period between 1 and 1095 days, inclusive.
Note
The AWS Management Console warns IAM users when they are within 15 days of password
expiration. IAM users can change their password at any time (as long as they have been
given permission to do so). When they set a new password, the rotation period for that
password starts over. An IAM user can have only one valid password at a time.
Prevent password reuse
You can prevent IAM users from reusing a specified number of previous passwords. You can set the
number of previous passwords from 1 to 24, inclusive.
Password expiration requires administrator reset
You can prevent IAM users from choosing a new password after their current password has expired.
For example, if the password policy specifies a password expiration period, but an IAM user fails to
choose a new password before the expiration period ends, the IAM user cannot set a new password.
In that case, the IAM user must request a password reset from an account administrator in order to
regain access to the AWS Management Console. If you leave this check box cleared and an IAM user
allows his or her password to expire, the user will be required to set a new password before accessing
the AWS Management Console.
Warning
Before you enable this option, be sure that your AWS account has more than one user with
administrative permissions (that is, permission to reset IAM user passwords) or that your
administrators also have access keys that enable them to use the AWS CLI or Tools for
Windows PowerShell separately from the AWS Management Console. When this option is
enabled and one administrator's password expires, a second administrator is required to
sign-in to the console to reset the expired password of the first administrator. However, if
the administrator with the expired password has valid access keys then he or she can run
an AWS CLI or Tools for Windows PowerShell command to reset his or her own password.
The requirement for a second administrator applies only if a password expires and the first
administrator has no access keys.
Setting a Password Policy (AWS Management Console)
You can use the AWS Management Console to create, change, or delete a password policy. As part of
managing the password policy, you can let all users manage their own passwords.
To create or change a password policy
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, click Account Settings.
3.
In the Password Policy section, select the options you want to apply to your password policy.
4.
Click Apply Password Policy.
67
AWS Identity and Access Management User Guide
Passwords
To delete a password policy
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, click Account Settings, and then in the Password Policy section, click Delete
Password Policy.
Setting a Password Policy (AWS CLI, Tools for Windows PowerShell, or AWS API)
To manage an account password policy from the AWS CLI, Tools for Windows PowerShell, or AWS APIs,
use the following commands:
To create or change a password policy
• AWS CLI: aws iam update-account-password-policy
• Tools for Windows PowerShell: Update-IAMAccountPasswordPolicy
• AWS API: UpdateAccountPasswordPolicy
To retrieve the password policy
• AWS CLI: aws iam get-account-password-policy
• Tools for Windows PowerShell: Get-IAMAccountPasswordPolicy
• AWS API: GetAccountPasswordPolicy
To delete a password policy
• AWS CLI: aws iam delete-account-password-policy
• Tools for Windows PowerShell: Remove-IAMAccountPasswordPolicy
• AWS APII: DeleteAccountPasswordPolicy
Managing Passwords for IAM Users
IAM users who use the AWS Management Console to work with AWS resources must have a password in
order to sign in. You can create, change, or delete a password for an IAM user in your AWS account.
After you have assigned a password to a user, the user can sign in to the AWS Management Console
using the sign-in URL for your account, which looks like this:
https://12-digit-AWS-account-ID or alias.signin.aws.amazon.com/console
For more information about how IAM users sign in to the AWS Management Console, see The IAM
Console and Sign-in Page (p. 43).
In addition to manually creating individual passwords for your IAM users, you can create a password
policy that applies to all IAM user passwords in your AWS account.
You can use a password policy to do these things:
• Set a minimum password length.
• Require specific character types, including uppercase letters, lowercase letters, numbers, and nonalphanumeric characters. Be sure to remind your users that passwords are case sensitive.
• Allow all IAM users to change their own passwords.
68
AWS Identity and Access Management User Guide
Passwords
Note
When you allow your IAM users to change their own passwords, IAM automatically allows
them to view the password policy. IAM users need permission to view the account's password
policy in order to create a password that complies with the policy.
• Require IAM users to change their password after a specified period of time (enable password
expiration).
• Prevent IAM users from reusing previous passwords.
• Force IAM users to contact an account administrator when the user has allowed his or her password to
expire.
For information about managing your account's password policy, see Setting an Account Password Policy
for IAM Users (p. 65).
Even if your users have their own passwords, they still need permissions to access your AWS resources.
By default, a user has no permissions. To give your users the permissions they need, you assign policies
to them or to the groups they belong to. For information about creating users and groups, see Identities
(Users, Groups, and Roles) (p. 50). For information about using policies to set permissions, see
Changing Permissions for an IAM User (p. 62).
You can grant users permission to change their own passwords. For more information, see Permitting
IAM Users to Change Their Own Passwords (p. 71). For information about how users access your
account sign-in page, see The IAM Console and Sign-in Page (p. 43).
Topics
• Creating, Changing, or Deleting an IAM User Password (Console) (p. 69)
• Creating, Changing, or Deleting an IAM User Password (API, CLI, PowerShell) (p. 71)
Creating, Changing, or Deleting an IAM User Password (Console)
You can use the AWS Management Console to manage passwords for your IAM users.
When users leave your organization or no longer need AWS access, it is important to find the credentials
that they were using and ensure that they are no longer operational. Ideally, you delete credentials if
they are no longer needed. You can always recreate them at a later date if the need arises. At the very
least you should change the credentials so that the former users no longer have access.
To add a password for an IAM user
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Users.
3.
Choose the name of the user whose password you want to create.
4.
Choose the Security credentials tab, and then under Sign-in credentials, choose Manage password
next to Console password.
5.
In Manage console access, for Console access choose Enable if not already selected. If console
access is disabled, then no password is needed.
6.
For Set password, choose whether to have IAM generate a password or create a custom password:
• To have IAM generate a password, choose Autogenerated password.
• To create a custom password, choose Custom password, and type the password.
Note
The password that you create must meet the account's password policy (p. 65), if one
is currently set.
69
AWS Identity and Access Management User Guide
Passwords
7.
To require the user to create a new password when signing in, choose Require password reset. Then
choose Apply.
Important
If you select the Require password reset option, make sure that the user has permission
to change his or her password. For more information, see Permitting IAM Users to Change
Their Own Passwords (p. 71).
8.
If you choose the option to autogenerate a password, choose Show in the New password dialog box.
This lets you view the password so you can share it with the user.
Important
For security reasons, you cannot access the password after completing this step, but you can
create a new password at any time.
To change the password for an IAM user
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Users.
3.
Choose the name of the user whose password you want to change.
4.
Choose the Security credentials tab, and then under Sign-in credentials, choose Manage password
next to Console password.
5.
In Manage console access, for Console access choose Enable if not already selected. If console
access is disabled, then no password is needed.
6.
For Set password, choose whether to have IAM generate a password or create a custom password:
• To have IAM generate a password, choose Autogenerated password.
• To create a custom password, choose Custom password, and type the password.
Note
The password that you create must meet the account's password policy (p. 65), if one
is currently set.
7.
To require the user to create a new password when signing in, choose Require password reset. Then
choose Apply.
Important
If you select the Require password reset option, make sure that the user has permission
to change his or her password. For more information, see Permitting IAM Users to Change
Their Own Passwords (p. 71).
8.
If you choose the option to autogenerate a password, choose Show in the New password dialog box.
This lets you view the password so you can share it with the user.
Important
For security reasons, you cannot access the password after completing this step, but you can
create a new password at any time.
To delete an IAM user's password
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Users.
3.
Choose the name of the user whose password you want to delete.
4.
Choose the Security credentials tab, and then under Sign-in credentials, choose Manage password
next to Console password.
5.
For Console access, choose Disable, and then choose Apply.
70
AWS Identity and Access Management User Guide
Passwords
Important
When you remove a user's password, the user can no longer sign in to the AWS Management
Console. If the user has active access keys, they continue to function and allow access through
the AWS CLI, Tools for Windows PowerShell, or AWS API function calls.
Creating, Changing, or Deleting an IAM User Password (API, CLI, PowerShell)
To manage passwords for IAM users, use the following commands:
To create a password
• AWS CLI: aws iam create-login-profile
• Tools for Windows PowerShell: New-IAMLoginProfile
• AWS API: CreateLoginProfile
To determine whether a user has a password
• AWS CLI: aws iam get-login-profile
• Tools for Windows PowerShell: Get-IAMLoginProfile
• AWS API: GetLoginProfile
To determine when a user's password was last used
• AWS CLI: aws iam get-user
• Tools for Windows PowerShell: Get-IAMUser
• AWS API: GetUser
To change a user's password
• AWS CLI: aws iam update-login-profile
• Tools for Windows PowerShell: Update-IAMLoginProfile
• AWS API: UpdateLoginProfile
To delete a user's password
• AWS CLI: aws iam delete-login-profile
• Tools for Windows PowerShell: Remove-IAMLoginProfile
• AWS API: DeleteLoginProfile
Note
You can use the AWS CLI, Tools for Windows PowerShell, or AWS API to delete a user from your
AWS account. However, you must first delete the password as a separate step in the process
of removing the user. For more information, see Deleting an IAM User (AWS CLI and Tools for
Windows PowerShell) (p. 61).
Permitting IAM Users to Change Their Own Passwords
You can grant IAM users the permission to change their own passwords for signing in to the AWS
Management Console. You can do this in one of two ways:
• Allow all IAM users in the account to change their own passwords (p. 72).
71
AWS Identity and Access Management User Guide
Passwords
• Allow only selected IAM users to change their own passwords (p. 72). In this scenario, you disable
the option for all users to change their own passwords and you use an IAM policy to grant permissions
to only some users to change their own passwords and optionally other credentials like their own
access keys.
Important
We recommend that you set a password policy (p. 65) so that users create strong passwords.
To allow all IAM users change their own passwords
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, click Account Settings.
3.
In the Password Policy section, select Allow users to change their own password, and then click
Apply Password Policy.
4.
Point users to the following instructions that show how they can change their passwords: How IAM
Users Change Their Own Password (p. 73).
For information about the AWS CLI, Tools for Windows PowerShell, and API commands that you can use
to change the account's password policy (which includes letting all users change their own passwords),
see Setting a Password Policy (AWS CLI, Tools for Windows PowerShell, or AWS API) (p. 68).
To allow selected IAM users change their own passwords
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, click Account Settings.
3.
In the Account Settings section, make sure that Allow users to change their own password is not
selected. If this check box is selected, all users can change their own passwords. (See the previous
procedure.)
4.
Create the users who should be able to change their own password, if they do not already exist. For
details, see Creating an IAM User in Your AWS Account (p. 54).
5.
Create an IAM group for the users who should be allowed to change their passwords, and then add
the users from the previous step to the group. For details, see Creating Your First IAM Admin User
and Group (p. 14) and Managing IAM Groups (p. 94).
This step is optional, but it's a best practice to use groups to manage permissions so that you can
add and remove users and change the permissions for the group as a whole.
6.
Assign the following policy to the group. For details, see Working with Policies (p. 250).
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:GetAccountPasswordPolicy",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "iam:ChangePassword",
"Resource": "arn:aws-cn:iam::account-id-without-hyphens:user/${aws:username}"
}
]
72
AWS Identity and Access Management User Guide
Passwords
This policy grants access to the ChangePassword action, which lets users change only their own
passwords from the console, the AWS CLI, Tools for Windows PowerShell, or the API. It also grants
access to the GetAccountPasswordPolicy action, which lets the user view the current password
policy; this permission is required so that the user can display the Change Password page in the
console. The user must be able to read the current password policy to ensure the changed password
meets the requirements of the policy.
7.
Point users to the following instructions that show how they can change their passwords: How IAM
Users Change Their Own Password (p. 73).
For More Information
For more information on managing credentials, see the following topics:
• Permitting IAM Users to Change Their Own Passwords (p. 71)
• Managing Passwords (p. 65)
• Setting an Account Password Policy for IAM Users (p. 65)
• Working with Policies (p. 250)
• How IAM Users Change Their Own Password (p. 73)
How IAM Users Change Their Own Password
If IAM users have been granted permission to change their own passwords, they can use a special page in
the AWS Management Console to do this. They can also use the command line interface or the IAM API.
For information about the permissions that users need in order to change their own passwords, see
Permitting IAM Users to Change Their Own Passwords (p. 71).
Topics
• How IAM Users Change Their Own Password (AWS Management Console) (p. 73)
• How IAM Users Change Their Own Password (AWS CLI, Tools for Windows PowerShell, or AWS
API) (p. 74)
How IAM Users Change Their Own Password (AWS Management Console)
The following procedure describes how IAM users can use the AWS Management Console to change their
own password.
To use the console to change your own password as an IAM user
1.
Use your AWS account ID or account alias, your IAM user name, and your password to sign in to the
IAM console.
Note
For your convenience, the AWS sign-in page uses a browser cookie to remember your IAM
user name and account information. If you previously signed in as a different user, choose
Sign in to a different account near the bottom of the page to return to the main sign-in
page. From there, you can type your AWS account ID or account alias to be redirected to the
IAM user sign-in page for your account.
To get your AWS account ID, contact your administrator.
2.
In the navigation bar on the upper right, choose your user name, and then choose Security
Credentials.
73
AWS Identity and Access Management User Guide
Access Keys
3.
For Current password, type your current password. Type a new password in the New password and
Confirm new password boxes. Then click Submit.
Note
If the account has a password policy, the new password must meet the requirements
of that policy. For more information, see Setting an Account Password Policy for IAM
Users (p. 65).
How IAM Users Change Their Own Password (AWS CLI, Tools for Windows
PowerShell, or AWS API)
The following procedure describes how IAM users can use the AWS CLI, Tools for Windows PowerShell, or
AWS API to change their own password.
To change your own IAM password, use the following commands
• AWS CLI: aws iam change-password
• Tools for Windows PowerShell: Edit-IAMPassword
• AWS API: ChangePassword
Managing Access Keys for IAM Users
Note
If you found this topic because you are trying to configure the Product Advertising API to sell
Amazon products on your website, see these topics:
• Getting Started with the Product Advertising API
• Getting Started as a Product Advertising API Developer
Users need their own access keys to make programmatic calls to AWS from the AWS Command Line
Interface (AWS CLI), Tools for Windows PowerShell, the AWS SDKs, or direct HTTP calls using the APIs for
individual AWS services. To fill this need, you can create, modify, view, or rotate access keys (access key
IDs and secret access keys) for IAM users.
When you create an access key, IAM returns the access key ID and secret access key. You should save
these in a secure location and give them to the user.
74
AWS Identity and Access Management User Guide
Access Keys
Important
To ensure the security of your AWS account, the secret access key is accessible only at the time
you create it. If a secret access key is lost, you must delete the access key for the associated
user and create a new key. For more details, see Retrieving Your Lost or Forgotten Passwords or
Access Keys (p. 79).
By default, when you create an access key, its status is Active, which means the user can use the access
key for AWS CLI, Tools for Windows PowerShell, and API calls. Each user can have two active access keys,
which is useful when you must rotate the user's access keys. You can disable a user's access key, which
means it can't be used for API calls. You might do this while you're rotating keys or to revoke API access
for a user.
You can delete an access key at any time. However, when you delete an access key, it's gone forever and
cannot be retrieved. (You can always create new keys.)
You can give your users permission to list, rotate, and manage their own keys. For more information, see
Allow Users to Manage Their Own Passwords, Access Keys, and SSH Keys (p. 228).
For more information about the credentials used with AWS and IAM, see Temporary Security
Credentials (p. 193), and Types of Security Credentials in the Amazon Web Services General Reference.
Topics
• Creating, Modifying, and Viewing Access Keys (Console) (p. 75)
• Creating, Modifying, and Viewing Access Keys (API, CLI, PowerShell) (p. 76)
• Rotating Access Keys (p. 77)
Creating, Modifying, and Viewing Access Keys (Console)
You can use the AWS Management Console to manage the access keys of IAM users.
To list the access key IDs for multiple users
1.
2.
3.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
In the navigation pane, choose Users.
If necessary, add the Access key ID column to the users table by completing the following steps:
a.
b.
c.
4.
Above the table on the far right, choose the settings icon (
).
In Manage Columns, select Access key ID.
Choose Close to return to the list of users.
The Access key ID column includes the access key IDs. You can use this information to view and copy
the access keys for users with one or two access keys. The column also shows whether the access key
is (Active) or (Inactive). The column displays None for users with no access key.
Note
Only the user's access key ID and status is visible. The secret access key can only be retrieved
when the key is created.
To find which user owns a specific access key
1.
2.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
In the navigation pane, choose Users.
3.
In the search box, type or paste the access key ID of the user you want to find.
75
AWS Identity and Access Management User Guide
Access Keys
4.
If necessary, add the Access key ID column to the users table by completing the following steps:
a.
Above the table on the far right, choose the settings icon (
).
b.
In Manage Columns, select Access key ID.
c.
Choose Close to return to the list of users and confirm that the filtered user owns the specified
access key.
To list a user's access keys
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Users.
3.
Choose the name of the intended user, and then choose the Security Credentials tab. The user's
access keys and the status of each key is displayed.
Note
Only the user's access key ID is visible. The secret access key can only be retrieved when the
key is created.
To create, modify, or delete a user's access keys
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Users.
3.
Choose the name of the desired user, and then choose the Security Credentials tab.
4.
If needed, expand the Access Keys section and do any of the following:
• To create an access key, choose Create Access Key. Then choose Download Credentials to save
the access key ID and secret access key to a CSV file on your computer. Store the file in a secure
location. You will not have access to the secret access key again after this dialog box closes. After
you have downloaded the CSV file, choose Close.
• To disable an active access key, choose Make Inactive.
• To reenable an inactive access key, choose Make Active.
• To delete an access key, choose Delete and then choose Delete to confirm.
Creating, Modifying, and Viewing Access Keys (API, CLI,
PowerShell)
To manage a user's access keys from the AWS CLI, Tools for Windows PowerShell, or the AWS API, use the
following commands:
To create an access key
• AWS CLI: aws iam create-access-key
• Tools for Windows PowerShell: New-IAMAccessKey
• AWS API: CreateAccessKey
To disable or reenable an access key
• AWS CLI: aws iam update-access-key
76
AWS Identity and Access Management User Guide
Access Keys
• Tools for Windows PowerShell: Update-IAMAccessKey
• AWS API: UpdateAccessKey
To list a user's access keys
• AWS CLI: aws iam list-access-keys
• Tools for Windows PowerShell: Get-IAMAccessKey
• AWS API: ListAccessKeys
To determine when an access key was most recently used
• AWS CLI: aws iam get-access-key-last-used
• Tools for Windows PowerShell: Get-IAMAccessKeyLastUsed
• AWS API: GetAccessKeyLastUsed
To delete an access key
• AWS CLI: aws iam delete-access-key
• Tools for Windows PowerShell: Remove-IAMAccessKey
• AWS API: DeleteAccessKey
Rotating Access Keys
As a security best practice, we recommend that you, an administrator, regularly rotate (change) the
access keys for IAM users in your account. If your users have the necessary permissions, they can rotate
their own access keys. For information about how to give your users permissions to rotate their own
access keys, see Allow Users to Manage Their Own Passwords, Access Keys, and SSH Keys (p. 228).
You can also apply a password policy to your account to require that all of your IAM users periodically
rotate their passwords. You can choose how often they must do so. For more information, see Setting an
Account Password Policy for IAM Users (p. 65).
To determine when access keys needs rotating (console)
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Users.
3.
If necessary, add the Access key age column to the users table by completing the following steps:
a.
4.
Above the table on the far right, choose the settings icon (
b.
In Manage Columns, select Access key age.
c.
Choose Close to return to the list of users.
).
The Access key age column shows the number of days since the oldest active access key was created.
You can use this information to find users with access keys that need rotating. The column displays
None for users with no access key.
To rotate access keys without interrupting your applications (console)
The following steps describe the general process for rotating an access key without interrupting your
applications. These steps show the AWS CLI, Tools for Windows PowerShell and AWS API commands
77
AWS Identity and Access Management User Guide
Access Keys
for rotating access keys. You can also perform these tasks using the console; for details, see Creating,
Modifying, and Viewing Access Keys (Console) (p. 75), in the section above.
1.
While the first access key is still active, create a second access key, which is active by default. At this
point, the user has two active access keys.
a.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
b.
In the navigation pane, choose Users.
c.
Choose the name of the intended user, and then choose the Security Credentials tab.
d.
Choose Create Access Key and then choose Download Credentials to save the access key ID and
secret access key to a .csv file on your computer. Store the file in a secure location. You will not
have access to the secret access key again after this closes. After you have downloaded the .csv
file, choose Close.
2.
Update all applications and tools to use the new access key.
3.
Determine whether the first access key is still in use by reviewing the Last used column for the
oldest access key. One approach is to wait several days and then check the old access key for any use
before proceeding.
4.
Even if the Last used column value indicates that the old key has never been used, we recommend
that you do not immediately delete the first access key. Instead, choose Make inactive to deactivate
the first access key.
5.
Use only the new access key to confirm that your applications are working. Any applications and
tools that still use the original access key will stop working at this point because they no longer
have access to AWS resources. If you find such an application or tool, you can choose Make active to
reenable the first access key. Then return to Step 3 (p. 78) and update this application to use the
new key.
6.
After you wait some period of time to ensure that all applications and tools have been updated, you
can delete the first access key:
a.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
b.
In the navigation pane, choose Users.
c.
Choose the name of the intended user, and then choose the Security Credentials tab.
d.
Choose Create Access Key, choose Delete, and then choose Delete to confirm.
To rotate access keys without interrupting your applications (API, CLI, PowerShell)
1.
While the first access key is still active, create a second access key, which is active by default. At this
point, the user has two active access keys.
• AWS CLI: aws iam create-access-key
• Tools for Windows PowerShell: New-IAMAccessKey
• AWS API: CreateAccessKey
2.
Update all applications and tools to use the new access key.
3.
Determine whether the first access key is still in use:
• AWS CLI: aws iam get-access-key-last-used
• Tools for Windows PowerShell: Get-IAMAccessKeyLastUsed
• AWS API: GetAccessKeyLastUsed
One approach is to wait several days and then check the old access key for any use before
proceeding.
78
AWS Identity and Access Management User Guide
Retrieving Lost Passwords or Access Keys
4.
Even if step Step 3 indicates no use of the old key, we recommend that you do not immediately
delete the first access key. Instead, change the state of the first access key to Inactive.
• AWS CLI: aws iam update-access-key
• Tools for Windows PowerShell: Update-IAMAccessKey
• AWS API: UpdateAccessKey
5.
Use only the new access key to confirm that your applications are working. Any applications and
tools that still use the original access key will stop working at this point because they no longer
have access to AWS resources. If you find such an application or tool, you can switch its state back to
Active to reenable the first access key. Then return to step Step 2 and update this application to use
the new key.
6.
After you wait some period of time to ensure that all applications and tools have been updated, you
can delete the first access key.
• AWS CLI: aws iam delete-access-key
• Tools for Windows PowerShell: Remove-IAMAccessKey
• AWS API: DeleteAccessKey
For more information, see the following:
• How to Rotate Access Keys for IAM Users. This entry on the AWS Security Blog provides more
information on key rotation.
• IAM Best Practices (p. 35). This page provides general recommendations for helping to secure your
AWS resources.
Retrieving Your Lost or Forgotten Passwords or
Access Keys
For security reasons, you cannot retrieve console passwords or the secret access key part of an access
key pair after you create it. If you lose one of these, it cannot be recovered and you must have your
administrator reset your password or create a new access key for you, as appropriate.
If you have the permissions needed to create your own access keys, you can find instructions for creating
a new one at Creating, Modifying, and Viewing Access Keys (Console) (p. 75).
You should follow best practice (p. 38) and periodically change your password and AWS access keys.
In AWS, you change access keys by rotating them. This means that you create a new one, configure
your application(s) to use the new key, and then delete the old one. You are allowed to have two
access key pairs active at the same time for just this reason. For more information, see Rotating Access
Keys (p. 77).
Finding Unused Credentials
To increase the security of your AWS account, remove IAM user credentials (that is, passwords and access
keys) that are not needed. For example, when users leave your organization or no longer need AWS
access, find the credentials that they were using and ensure that they are no longer operational. Ideally,
you delete credentials if they are no longer needed. You can always recreate them at a later date if the
need arises. At the very least you should change the password or deactivate the access keys so that the
former users no longer have access.
Of course, the definition of unused can vary and usually means a credential that has not been used
within a specified period of time.
79
AWS Identity and Access Management User Guide
Finding Unused Credentials
Finding Unused Passwords
You can use the AWS Management Console to view password usage information for your users. If you
have a large number of users, you can use the console to download a credential report with information
about when each user last used their console password. You can also access the information from the
AWS CLI, Tools for Windows PowerShell, or the IAM API.
To find unused passwords (console)
1.
2.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
In the navigation pane, choose Users.
3.
If necessary, add the Console last sign-in column to the users table:
a.
Above the table on the far right, choose the settings icon (
b.
In Manage Columns, select Console last sign-in.
c.
Choose Close to return to the list of users.
).
The Console last sign-in column shows the number of days since the user last signed in to AWS
through the console. You can use this information to find users with passwords who have not signed
in for more than a specified period of time. The column displays Never for users with passwords that
have never signed in. None indicates users with no passwords. Passwords that have not been used
recently might be good candidates for removal.
4.
To find unused passwords by downloading the credentials report (console)
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
3.
In the navigation pane, choose Credential report.
Choose Download Report to download a comma-separated value (CSV) file named
status_reports_<date>T<time>.csv. The fifth column contains the password_last_used column
with the dates or one of the following:
• N/A – Users that do not have a password assigned at all.
• no_information – Users that have not used their password since IAM began tracking password age
on October 20, 2014.
To find unused passwords (API, CLI, PowerShell)
You can use the following commands to find unused passwords:
• AWS CLI –aws iam list-users returns a list of users, each with a PasswordLastUsed value. If the value
is missing, then the user either has no password or the password has not been used since IAM began
tracking password age on October 20, 2014.
• Tools for Windows PowerShell – Get-IAMUsers returns a collection of User objects, each of which has
a PasswordLastUsed property. If the property value is 1/1/0001 12:00:00 AM, then the user either has
no password or the password has not been used since IAM began tracking password age on October
20, 2014.
• IAM API – ListUsers returns a collection of users, each of which has a <PasswordLastUsed> value. If
the value is missing, then the user either has no password or the password has not been used since
IAM began tracking password age on October 20, 2014.
80
AWS Identity and Access Management User Guide
Finding Unused Credentials
For information about the commands to download the credentials report, see Getting Credential
Reports (AWS CLI, Tools for Windows PowerShell, or IAM API) (p. 85).
Finding Unused Access Keys
You can use the AWS Management Console to view access key usage information for your users. If you
have a large number of users, you can use the console to download a credentials report to find when
each user last used their access keys. You can also access the information from the AWS CLI, Tools for
Windows PowerShell, or the IAM API.
To find unused access keys (console)
1.
2.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
In the navigation pane, choose Users.
3.
If necessary, add the Access key last used column to the users table:
a.
4.
Above the table on the far right, choose the settings icon (
b.
In Manage Columns, select Access key last used.
c.
Choose Close to return to the list of users.
).
The Access key last used column shows the number of days since the user last accessed AWS
programmatically. You can use this information to find users with access keys that have not been
used for more than a specified period of time. The column displays None for users with no access
keys. Access keys that have not been used recently might be good candidates for removal.
To find unused access keys by downloading the credentials report (console)
1.
2.
3.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
In the navigation pane, choose Credential Report.
Choose Download Report to download a comma-separated value (CSV) file named
status_reports_<date>T<time>.csv. Columns 11 through 13 contain the last used date, region,
and service information for access key 1. Columns 16 through 18 contain the same information for
access key 2. The value is N/A if the user does not have an access key or the user has not used the
access key since IAM began tracking access key age on April 22, 2015.
To find unused access keys (API, CLI, PowerShell)
You can use the following commands to find unused access keys:
AWS CLI
• aws iam list-access-keys returns information about the access keys for a user, including the
AccessKeyID.
• aws iam get-access-key-last-used takes an access key ID and returns output that includes the
LastUsedDate, the Region in which the access key was last used, and the ServiceName of the last
service requested. If the LastUsedDate field is missing, then the access key has not been used since
IAM began tracking access key age on April 22, 2015.
Tools for Windows PowerShell
• Get-IAMAccessKey returns a collection of access key objects associated with the specified user.
Each object has an AccessKeyId property.
81
AWS Identity and Access Management User Guide
Getting Credential Reports
• Get-IAMAccessKeyLastUsed takes an access key ID and returns an object with an
AccessKeyLastUsed property object. The methods of that object include the LastUsedDate, the
Region in which the access key was last used, and the ServiceName of the last service requested.
If the property value is 1/1/0001 12:00:00 AM, then the access key has not been used since IAM
began tracking access key age on April 22, 2015.
IAM API
• ListAccessKeys returns a list of AccessKeyID values for access keys that are associated with the
specified user.
• GetAccessKeyLastUsed takes an access key ID and returns a collection of values. Included are the
LastUsedDate, the Region in which the access key was last used, and the ServiceName of the last
service requested. If the value is missing, then user either has no access key or the access key has
not been used since IAM began tracking access key age on April 22, 2015.
For information about the commands to download the credentials report, see Getting Credential Reports
(AWS CLI, Tools for Windows PowerShell, or IAM API) (p. 85)
Getting Credential Reports for Your AWS Account
You can generate and download a credential report that lists all users in your account and the status of
their various credentials, including passwords, and access keys. You can get a credential report from the
AWS Management Console, the AWS SDKs and Command Line Tools, or the IAM API.
You can use credential reports to assist in your auditing and compliance efforts. You can use the report
to audit the effects of credential lifecycle requirements, such as password and access key rotation. You
can provide the report to an external auditor, or grant permissions to an auditor so that he or she can
download the report directly.
You can generate a credential report as often as once every four hours. When you request a report, IAM
first checks whether a report for the AWS account has been generated within the past four hours. If so,
the most recent report is downloaded. If the most recent report for the account is more than four hours
old, or if there are no previous reports for the account, IAM generates and downloads a new report.
Required Permissions
• To create a credential report: GenerateCredentialReport
• To download the report: GetCredentialReport
Understanding the Report Format
Credential reports are formatted as comma-separated values (CSV) files. You can open CSV files with
common spreadsheet software to perform analysis, or you can build an application that consumes the
CSV files programmatically and performs custom analysis.
The CSV file contains the following columns:
user
The friendly name of the user.
arn
The Amazon Resource Name (ARN) of the user. For more information about ARNs, see IAM
ARNs (p. 357).
82
AWS Identity and Access Management User Guide
Getting Credential Reports
user_creation_time
The date and time when the user was created, in ISO 8601 date-time format.
password_enabled
When the user has a password, this value is TRUE. Otherwise it is FALSE.
password_last_used
The date and time when the IAM user's password was last used to sign in to an AWS website, in
ISO 8601 date-time format. AWS websites that capture a user's last sign-in time are the AWS
Management Console, the AWS Discussion Forums, and the AWS Marketplace. When a password is
used more than once in a 5-minute span, only the first use is recorded in this field.
• The value in this field is no_information in these cases:
• The user's password has never been used.
• There is no sign-in data associated with the password, such as when user's password has not
been used after IAM started tracking this information on October 20, 2014.
• The value in this field is N/A (not applicable) when the user does not have a password.
password_last_changed
The date and time when the user's password was last set, in ISO 8601 date-time format. If the user
does not have a password, the value in this field is N/A (not applicable).
password_next_rotation
When the account has a password policy that requires password rotation, this field contains the date
and time, in ISO 8601 date-time format, when the user is required to set a new password.
access_key_1_active
When the user has an access key and the access key's status is Active, this value is TRUE. Otherwise it
is FALSE.
access_key_1_last_rotated
The date and time, in ISO 8601 date-time format, when the user's access key was created or last
changed. If the user does not have an active access key, the value in this field is N/A (not applicable).
access_key_1_last_used_date
The date and time, in ISO 8601 date-time format, when the user's access key was most recently used
to sign an AWS API request. When an access key is used more than once in a 15-minute span, only
the first use is recorded in this field.
The value in this field is N/A (not applicable) in these cases:
• The user does not have an access key.
• The access key has never been used.
• The access key has not been used after IAM started tracking this information on April 22, 2015.
access_key_1_last_used_region
The AWS region in which the access key was most recently used. When an access key is used more
than once in a 15-minute span, only the first use is recorded in this field.
The value in this field is N/A (not applicable) in these cases:
• The user does not have an access key.
• The access key has never been used.
• The access key was last used before IAM started tracking this information on April 22, 2015.
83
AWS Identity and Access Management User Guide
Getting Credential Reports
• The last used service is not region-specific, such as Amazon Simple Storage Service (Amazon S3).
access_key_1_last_used_service
The AWS service that was most recently accessed with the access key. The value in this field uses the
service's namespace—for example, s3 for Amazon S3 and ec2 for Amazon Elastic Compute Cloud
(Amazon EC2). When an access key is used more than once in a 15-minute span, only the first use is
recorded in this field.
The value in this field is N/A (not applicable) in these cases:
• The user does not have an access key.
• The access key has never been used.
• The access key was last used before IAM started tracking this information on April 22, 2015.
access_key_2_active
When the user has a second access key and the second key's status is Active, this value is TRUE.
Otherwise it is FALSE.
Note
Users can have up to two access keys, to make rotation easier. For more information about
rotating access keys, see Rotating Access Keys (p. 77).
access_key_2_last_rotated
The date and time, in ISO 8601 date-time format, when the user's second access key was created or
last changed. If the user does not have a second active access key, the value in this field is N/A (not
applicable).
access_key_2_last_used_date
The date and time, in ISO 8601 date-time format, when the user's second access key was most
recently used to sign an AWS API request. When an access key is used more than once in a 15-minute
span, only the first use is recorded in this field.
The value in this field is N/A (not applicable) in these cases:
• The user does not have a second access key.
• The user's second access key has never been used.
• The user's second access key was last used before IAM started tracking this information on April
22, 2015.
access_key_2_last_used_region
The AWS region in which the user's second access key was most recently used. When an access key is
used more than once in a 15-minute span, only the first use is recorded in this field. The value in this
field is N/A (not applicable) in these cases:
• The user does not have a second access key.
• The user's second access key has never been used.
• The user's second access key was last used before IAM started tracking this information on April
22, 2015.
• The last used service is not region-specific, such as Amazon S3.
access_key_2_last_used_service
The AWS service that was most recently accessed with the user's second access key. The value in
this field uses the service's namespace—for example, s3 for Amazon S3 and ec2 for Amazon Elastic
Compute Cloud (Amazon EC2). When an access key is used more than once in a 15-minute span, only
the first use is recorded in this field. The value in this field is N/A (not applicable) in these cases:
• The user does not have a second access key.
84
AWS Identity and Access Management User Guide
Getting Credential Reports
• The user's second access key has never been used.
• The user's second access key was last used before IAM started tracking this information on April
22, 2015.
cert_1_active
When the user has an X.509 signing certificate and that certificate's status is Active, this value is
TRUE. Otherwise it is FALSE.
cert_1_last_rotated
The date and time, in ISO 8601 date-time format, when the user's signing certificate was created or
last changed. If the user does not have an active signing certificate, the value in this field is N/A (not
applicable).
cert_2_active
When the user has a second X.509 signing certificate and that certificate's status is Active, this value
is TRUE. Otherwise it is FALSE.
Note
Users can have up to two X.509 signing certificates, to make certificate rotation easier.
cert_2_last_rotated
The date and time, in ISO 8601 date-time format, when the user's second signing certificate was
created or last changed. If the user does not have a second active signing certificate, the value in this
field is N/A (not applicable).
Getting Credential Reports (AWS Management Console)
You can use the AWS Management Console to download a credential report as a comma-separated
values (CSV) file.
To download a credential report using the AWS Management Console
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, click Credential report.
3.
Click Download Report.
Getting Credential Reports (AWS CLI, Tools for Windows
PowerShell, or IAM API)
To generate a credential report
You can use the following commands to create a credential report:
• AWS CLI: aws iam generate-credential-report
• Tools for Windows PowerShell: Request-IAMCredentialReport
• IAM API: GenerateCredentialReport
To retrieve a credential report
You can use the following commands to retrieve a generated credential report:
• AWS CLI: aws iam get-credential-report
85
AWS Identity and Access Management User Guide
Using IAM with AWS CodeCommit: Git
Credentials, SSH Keys, and AWS Access Keys
• Tools for Windows PowerShell: Get-IAMCredentialReport
• IAM API: GetCredentialReport
Using IAM with AWS CodeCommit: Git Credentials,
SSH Keys, and AWS Access Keys
AWS CodeCommit is a managed version control service that hosts private Git repositories in the AWS
cloud. To use AWS CodeCommit, you configure your Git client to communicate with AWS CodeCommit
repositories. As part of this configuration, you provide IAM credentials that AWS CodeCommit can use to
authenticate you. IAM supports AWS CodeCommit with three types of credentials:
• Git credentials, an IAM -generated user name and password pair you can use to communicate with
AWS CodeCommit repositories over HTTPS.
• SSH keys, a locally generated public-private key pair that you can associate with your IAM user to
communicate with AWS CodeCommit repositories over SSH.
• AWS access keys (p. 74), which you can use with the credential helper included with the AWS CLI to
communicate with AWS CodeCommit repositories over HTTPS.
See the following sections for more information about each option.
Use Git Credentials and HTTPS with AWS CodeCommit
(Recommended)
With Git credentials, you generate a static user name and password pair for your IAM user, and then use
those credentials for HTTPS connections. You can also use these credentials with any third-party tool or
integrated development environment (IDE) that supports static Git credentials.
Because these credentials are universal for all supported operating systems and compatible with most
credential management systems, development environments, and other software development tools,
this is the recommended method. You can reset the password for Git credentials at any time. You can
also make the credentials inactive or delete them if you no longer need them.
Note
You cannot choose your own user name or password for Git credentials. IAM generates these
credentials for you to help ensure they meet the security standards for AWS and secure
repositories in AWS CodeCommit. You can download the credentials only once, at the time they
are generated. Make sure that you save the credentials in a secure location. If necessary, you can
reset the password at any time, but doing so invalidates any connections configured with the old
password. You must reconfigure connections to use the new password before you can connect.
See the following topics for more information:
• To create an IAM user, see Creating an IAM User in Your AWS Account (p. 54).
• To generate and use Git credentials with AWS CodeCommit, see For HTTPS Users Using Git Credentials
in the AWS CodeCommit User Guide.
Note
Changing the name of an IAM user after generating Git credentials does not change the user
name of the Git credentials. The user name and password remain the same and are still valid.
To rotate service specific credentials
1.
Create a second service-specific credential set in addition to the set currently in use.
86
AWS Identity and Access Management User Guide
Working with Server Certificates
2.
Update all of your applications to use the new set of credentials and validate that the applications
are working.
3.
Change the state of the original credentials to "Inactive".
4.
Ensure that all of your applications are still working.
5.
Delete the inactive service-specific credentials.
Use SSH Keys and SSH with AWS CodeCommit
With SSH connections, you create public and private key files on your local machine that Git and AWS
CodeCommit use for SSH authentication. You associate the public key with your IAM user and store the
private key on your local machine. See the following topics for more information:
• To create an IAM user, see Creating an IAM User in Your AWS Account (p. 54).
• To create an SSH public key and associate it with an IAM user, see For SSH Connections on Linux, OS X,
or Unix or see For SSH Connections on Windows in the AWS CodeCommit User Guide.
Note
IAM accepts public keys in the OpenSSH RSA format only. If you provide your public key in
another format, you will see an error message stating that the key format is not valid.
Use HTTPS with the AWS CLI Credential Helper and AWS
CodeCommit
As an alternative to HTTPS connections with Git credentials, you can allow Git to use a cryptographically
signed version of your IAM user credentials or Amazon EC2 instance role whenever Git needs to
authenticate with AWS to interact with AWS CodeCommit repositories. This is the only connection
method for AWS CodeCommit repositories that does not require an IAM user. This is also the only
method that works with federated access and temporary credentials. Unless your business needs require
federated access or the use of temporary credentials, creating and using IAM users for access is strongly
recommended. See the following topics for more information:
• To learn more about federated access, see Identity Providers and Federation (p. 105) and Providing
Access to Externally Authenticated Users (Identity Federation) (p. 104).
• To learn more about temporary credentials, see Temporary Security Credentials (p. 193) and
Temporary Access to AWS CodeCommit Repositories.
The AWS CLI credential helper is not compatible with other credential helper systems, such as Keychain
Access or Windows Credential Management. There are additional configuration considerations when
you configure HTTPS connections with the credential helper. For more information, see For HTTPS
Connections on Linux, OS X, or Unix with the AWS CLI Credential Helper or HTTPS Connections on
Windows with the AWS CLI Credential Helper in the AWS CodeCommit User Guide.
Working with Server Certificates
To enable HTTPS connections to your website or application in AWS, you need an SSL/TLS server
certificate. You can use a server certificate provided by AWS Certificate Manager (ACM) or one that you
obtained from an external provider. You can use ACM or IAM to store and deploy server certificates.
ACM is the preferred tool to provision, manage, and deploy your server certificates. With ACM you can
request a certificate or deploy an existing ACM or external certificate to AWS resources. Certificates
provided by ACM are free and automatically renew. You can use ACM to manage server certificates
87
AWS Identity and Access Management User Guide
Working with Server Certificates
from the console or programmatically. For more information about using ACM, see the AWS Certificate
Manager User Guide.
Use IAM as a certificate manager only when you must support HTTPS connections in a region that is
not supported by ACM. IAM supports deploying server certificates in all regions, but you must obtain
your certificate from an external provider for use with AWS. You cannot upload an ACM certificate to
IAM. Additionally, you cannot manage your certificates from the IAM Console. You must upload, retrieve,
manage, or delete your server certificates programmatically.
For more information about requesting an ACM certificate, see Request a Certificate in the AWS
Certificate Manager User Guide.
For more information about importing third party certificates into ACM, see Importing Certificates in the
AWS Certificate Manager User Guide.
For more information about uploading third party certificates to IAM, see the following topics.
Topics
• Uploading a Server Certificate (IAM API) (p. 88)
• Retrieving a Server Certificate (IAM API) (p. 89)
• Listing Server Certificates (IAM API) (p. 89)
• Renaming a Server Certificate or Updating its Path (IAM API) (p. 89)
• Deleting a Server Certificate (IAM API) (p. 90)
• Troubleshooting (p. 90)
Uploading a Server Certificate (IAM API)
To upload a server certificate to IAM, you must provide the certificate and its matching private key. When
the certificate is not self-signed, you must also provide a certificate chain. (You don't need a certificate
chain when uploading a self-signed certificate.) Before you upload a certificate, ensure that you have all
these items and that they meet the following criteria:
• The certificate must be valid at the time of upload. You cannot upload a certificate before its validity
period begins (the certificate's NotBefore date) or after it expires (the certificate's NotAfter date).
• The private key must be unencrypted. You cannot upload a private key that is protected by a password
or passphrase. For help decrypting an encrypted private key, see Troubleshooting (p. 90).
• The certificate, private key, and certificate chain must all be PEM-encoded. For help converting these
items to PEM format, see Troubleshooting (p. 90).
To use the IAM API to upload a certificate, send an UploadServerCertificate request. The following
example shows how to do this with the AWS Command Line Interface (AWS CLI). The example assumes
the following:
• The PEM-encoded certificate is stored in a file named Certificate.pem.
• The PEM-encoded certificate chain is stored in a file named CertificateChain.pem.
• The PEM-encoded, unencrypted private key is stored in a file named PrivateKey.pem.
To use the following example command, replace these file names with your own and replace
ExampleCertificate with a name for your uploaded certificate. Type the command on one continuous
line. The following example includes line breaks and extra spaces to make it easier to read.
$ aws iam upload-server-certificate --server-certificate-name ExampleCertificate
88
AWS Identity and Access Management User Guide
Working with Server Certificates
--certificate-body file://Certificate.pem
--certificate-chain file://CertificateChain.pem
--private-key file://PrivateKey.pem
When the preceding command is successful, it returns metadata about the uploaded certificate,
including its Amazon Resource Name (ARN), its friendly name, its identifier (ID), its expiration date, and
more.
Note
If you are uploading a server certificate to use with Amazon CloudFront, you must specify a path
using the --path option. The path must begin with /cloudfront and must include a trailing
slash (for example, /cloudfront/test/).
To use the AWS Tools for Windows PowerShell to upload a certificate, use Publish-IAMServerCertificate.
Retrieving a Server Certificate (IAM API)
To use the IAM API to retrieve a certificate, send a GetServerCertificate request. The following example
shows how to do this with the AWS CLI. Replace ExampleCertificate with the name of the certificate to
retrieve.
$ aws iam get-server-certificate --server-certificate-name ExampleCertificate
When the preceding command is successful, it returns the certificate, the certificate chain (if one was
uploaded), and metadata about the certificate.
Note
You cannot download or retrieve a private key from IAM after you upload it.
To use the AWS Tools for Windows PowerShell to retrieve a certificate, use Get-IAMServerCertificate.
Listing Server Certificates (IAM API)
To use the IAM API to list your uploaded server certificates, send a ListServerCertificates request. The
following example shows how to do this with the AWS CLI.
$ aws iam list-server-certificates
When the preceding command is successful, it returns a list that contains metadata about each
certificate.
To use the AWS Tools for Windows PowerShell to list your uploaded server certificates, use GetIAMServerCertificates.
Renaming a Server Certificate or Updating its Path (IAM API)
To use the IAM API to rename a server certificate or update its path, send an UpdateServerCertificate
request. The following example shows how to do this with the AWS CLI.
To use the following example command, replace the old and new certificate names and the certificate
path, and type the command on one continuous line. The following example includes line breaks and
extra spaces to make it easier to read.
$ aws iam update-server-certificate --server-certificate-name ExampleCertificate
89
AWS Identity and Access Management User Guide
Working with Server Certificates
--new-server-certificate-name CloudFrontCertificate
--new-path /cloudfront/
When the preceding command is successful, it does not return any output.
To use the AWS Tools for Windows PowerShell to rename a server certificate or update its path, use
Update-IAMServerCertificate.
Deleting a Server Certificate (IAM API)
To use the IAM API to delete a server certificate, send a DeleteServerCertificate request. The following
example shows how to do this with the AWS CLI.
To use the following example command, replace ExampleCertificate with the name of the certificate to
delete.
$ aws iam delete-server-certificate --server-certificate-name ExampleCertificate
When the preceding command is successful, it does not return any output.
To use the AWS Tools for Windows PowerShell to delete a server certificate, use RemoveIAMServerCertificate.
Troubleshooting
Before you can upload a certificate to IAM, you must make sure that the certificate, private key, and
certificate chain are all PEM-encoded. You must also ensure that the private key is unencrypted. See the
following examples.
Example PEM-encoded certificate
-----BEGIN CERTIFICATE----Base64-encoded certificate
-----END CERTIFICATE-----
Example PEM-encoded, unencrypted private key
-----BEGIN RSA PRIVATE KEY----Base64-encoded private key
-----END RSA PRIVATE KEY-----
Example PEM-encoded certificate chain
A certificate chain contains one or more certificates. The following example contains three certificates,
but your certificate chain might contain more or fewer.
-----BEGIN CERTIFICATE----Base64-encoded certificate
-----END CERTIFICATE---------BEGIN CERTIFICATE----Base64-encoded certificate
-----END CERTIFICATE---------BEGIN CERTIFICATE----Base64-encoded certificate
90
AWS Identity and Access Management User Guide
Working with Server Certificates
-----END CERTIFICATE-----
If these items are not in the right format for uploading to IAM, you can use OpenSSL to convert them to
the right format.
To convert a certificate or certificate chain from DER to PEM
Use the OpenSSL x509 command, as in the following example. In the following example command,
replace Certificate.der with the name of the file that contains your DER-encoded certificate.
Replace Certificate.pem with the desired name of the output file to contain the PEM-encoded
certificate.
$ openssl x509 -inform DER -in Certificate.der -outform PEM -out Certificate.pem
To convert a private key from DER to PEM
Use the OpenSSL rsa command, as in the following example. In the following example command,
replace PrivateKey.der with the name of the file that contains your DER-encoded private key.
Replace PrivateKey.pem with the desired name of the output file to contain the PEM-encoded
private key.
$ openssl rsa -inform DER -in PrivateKey.der -outform PEM -out PrivateKey.pem
To decrypt an encrypted private key (remove the password or passphrase)
Use the OpenSSL rsa command, as in the following example. To use the following example
command, replace EncryptedPrivateKey.pem with the name of the file that contains your encrypted
private key. Replace PrivateKey.pem with the desired name of the output file to contain the PEMencoded unencrypted private key.
$ openssl rsa -in EncryptedPrivateKey.pem -out PrivateKey.pem
To convert a certificate bundle from PKCS#12 (PFX) to PEM
Use the OpenSSL pkcs12 command, as in the following example. In the following example
command, replace CertificateBundle.p12 with the name of the file that contains your PKCS#12encoded certificate bundle. Replace CertificateBundle.pem with the desired name of the output
file to contain the PEM-encoded certificate bundle.
$ openssl pkcs12 -in CertificateBundle.p12 -out CertificateBundle.pem -nodes
To convert a certificate bundle from PKCS#7 to PEM
Use the OpenSSL pkcs7 command, as in the following example. In the following example command,
replace CertificateBundle.p7b with the name of the file that contains your PKCS#7-encoded
certificate bundle. Replace CertificateBundle.pem with the desired name of the output file to
contain the PEM-encoded certificate bundle.
$ openssl pkcs7 -in CertificateBundle.p7b -print_certs -out CertificateBundle.pem
91
AWS Identity and Access Management User Guide
Groups
IAM Groups
An IAM group (p. 92) is a collection of IAM users. Groups let you specify permissions for multiple users,
which can make it easier to manage the permissions for those users. For example, you could have a group
called Admins and give that group the types of permissions that administrators typically need. Any user
in that group automatically has the permissions that are assigned to the group. If a new user joins your
organization and needs administrator privileges, you can assign the appropriate permissions by adding
the user to that group. Similarly, if a person changes jobs in your organization, instead of editing that
user's permissions, you can remove him or her from the old groups and add him or her to the appropriate
new groups.
Note that a group is not truly an "identity" in IAM because it cannot be identified as a Principal in a
permission policy. It is simply a way to attach policies to multiple users at one time.
Following are some important characteristics of groups:
• A group can contain many users, and a user can belong to multiple groups.
• Groups can't be nested; they can contain only users, not other groups.
• There's no default group that automatically includes all users in the AWS account. If you want to have
a group like that, you need to create it and assign each new user to it.
• There's a limit to the number of groups you can have, and a limit to how many groups a user can be in.
For more information, see Limitations on IAM Entities and Objects (p. 360).
The following diagram shows a simple example of a small company. The company owner creates an
Admins group for users to create and manage other users as the company grows. The Admins group
creates a Developers group and a Test group. Each of these groups consists of users (humans and
applications) that interact with AWS (Jim, Brad, DevApp1, and so on). Each user has an individual set of
security credentials. In this example, each user belongs to a single group. However, users can belong to
multiple groups.
92
AWS Identity and Access Management User Guide
Creating Groups
Creating IAM Groups
To set up a group, you need to create the group, give it permissions based on the type of work that you
expect the users in the group to do, and then add users to the group.
For information about the permissions that you need in order to create a group, see Delegating
Permissions to Administer IAM Users, Groups, and Credentials (p. 225).
93
AWS Identity and Access Management User Guide
Managing Groups
To create an IAM group and attach policies (AWS Management Console)
1.
2.
3.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
In the navigation pane, click Groups and then click Create New Group.
In the Group Name box, type the name of the group and then click Next Step.
Important
Group names must be unique within an account. They are not distinguished by case, for
example, you cannot create groups named both "ADMINS" and "admins".
4.
In the list of policies, select the check box for each policy that you want to apply to all members of
the group. Then click Next Step.
5.
Click Create Group.
For an example of how to set up an Administrators group, see Creating Your First IAM Admin User and
Group (p. 14).
To create IAM groups and attach policies (AWS CLI, Tools for Windows PowerShell, AWS API)
Use one of the following commands to create a group:
• AWS CLI: aws iam create-group
• Tools for Windows PowerShell: New-IAMGroup
• AWS API: CreateGroup
Managing IAM Groups
Amazon Web Services offers multiple tools for managing IAM groups. For information about the
permissions that you need in order to add and remove users in a group, see Delegating Permissions to
Administer IAM Users, Groups, and Credentials (p. 225).
Topics
• Listing IAM Groups (p. 94)
• Adding and Removing Users in an IAM Group (p. 95)
• Attaching a Policy to an IAM Group (p. 95)
• Renaming an IAM Group (p. 96)
• Deleting an IAM Group (p. 96)
Listing IAM Groups
You can list all the groups in your account, list the users in a group, and list the groups a user belongs
to. If you use the AWS CLI, Tools for Windows PowerShell, or AWS API, you can list all the groups with a
particular path prefix
To list all the groups in your account
• AWS Management Console: In the navigation pane, choose Groups.
• AWS CLI: aws iam list-groups
• Tools for Windows PowerShell: Get-IAMGroups
• AWS API: ListGroups
To list the users in a specific group
94
AWS Identity and Access Management User Guide
Managing Groups
• AWS Management Console: In the navigation pane, choose Groups, choose the name of the group, and
then choose the Users tab.
• AWS CLI: aws iam get-group
• Tools for Windows PowerShell: Get-IAMGroup
• AWS API: GetGroup
To list all the groups that a user is in
• AWS Management Console: In the navigation pane, chose Users, choose the user name, and then
choose the Groups tab.
• AWS CLI: aws iam list-groups-for-user
• Tools for Windows PowerShell: Get-IAMGroupForUser
• AWS API: ListGroupsForUser
Adding and Removing Users in an IAM Group
At any time, you can add users to or remove users from an IAM group. This is useful as people enter and
leave your organization.
To add a user to an IAM group
• AWS Management Console: In the navigation pane, choose Groups and then choose the name of the
group. Choose the Users tab and then choose Add Users to Group. Select the users you want to add
and then choose Add Users to Group.
• AWS CLI: aws iam add-user-to-group
• Tools for Windows PowerShell: Add-IAMUserToGroup
• AWS API: AddUserToGroup
To remove a user from an IAM group
• AWS Management Console: In the navigation pane, choose Groups and then choose the name of the
group. Choose the Users tab and then choose Remove Users from Group. Select the users you want to
add and then choose Remove Users from Group.
• AWS CLI: aws iam remove-user-from-group
• Tools for Windows PowerShell: Remove-IAMUserFromGroup
• AWS API: RemoveUserFromGroup
Attaching a Policy to an IAM Group
You can attach an AWS managed policy (p. 236)—that is, a prewritten policy provided by AWS—to a
group, as explained in the following steps. To attach a customer managed policy—that is, a policy with
custom permissions that you create—you must first create the policy. For information about creating
customer managed policies, see Creating Customer Managed Policies (p. 252).
For more information about permissions and policies, see Access Management (p. 222).
To attach a policy to a group (AWS Management Console)
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, select Policies.
95
AWS Identity and Access Management User Guide
Managing Groups
3.
In the list of policies, select the check box next to the name of the policy to attach. You can use the
Filter menu and the search box to filter the list of policies.
4.
Click Policy actions, then click Attach.
5.
For Filter, choose All Types, then click Groups.
6.
Select the check box next to the name of the group to attach the policy to, then click Attach policy.
To attach a policy to a group (AWS CLI, Tools for Windows PowerShell, API)
• AWS CLI: aws iam attach-group-policy
• Tools for Windows PowerShell: Register-IAMGroupPolicy
• AWS API: AttachGroupPolicy
Renaming an IAM Group
When you change a group's name or path, the following happens:
• Any policies attached to the group stay with the group under the new name.
• The group retains all its users under the new name.
• The unique ID for the group remains the same. For more information about unique IDs, see Unique
IDs (p. 359).
IAM does not automatically update policies that refer to the group as a resource to use the new
name; you must manually do that. For example, let's say Bob is the manager of the testing part of the
organization, and he has a policy attached to his IAM user entity that lets him add and remove users
from the Test group. If an an admin changes the name of the group to Test_1 (or changes the path for
the group), the admin also needs to update the policy attached to Bob to use the new name (or new
path). Otherwise Bob won't be able to add and remove users from the group.
To change the name of an IAM group
• AWS Management Console: In the navigation pane, click Groups and then select the check box next to
the group name. From the Group Actions list at the top of the page, select Edit Group Name. Type the
new group name and then click Yes, Edit.
• AWS CLI: aws iam update-group
• Tools for Windows PowerShell: Update-IAMGroup
• AWS API: UpdateGroup
Deleting an IAM Group
When you delete a group in the AWS Management Console, the console automatically removes all group
members, detaches all attached managed policies, and deletes all inline policies.
In contrast, when you use the AWS CLI, Tools for Windows PowerShell, or AWS API to delete a group, you
must first remove the users in the group, delete any inline policies embedded in the group, and detach
any managed policies attached to the group before you can delete the group.
To delete an IAM group (AWS Management Console)
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, select Groups.
96
AWS Identity and Access Management User Guide
Roles
3.
In the list of groups, select the check box next to the name of the group to delete. You can use the
Filter menu and the search box to filter the list of policies.
4.
Click Group Actions, then click Delete Group.
5.
In the confirmation box, click Yes, Delete.
To delete an IAM group (AWS CLI, Tools for Windows PowerShell, AWSAPI)
1.
Remove all users from the group.
• CLI: aws iam get-group (to get the list of users in the group), and aws iam remove-user-fromgroup (to remove a user from the group)
• Tools for Windows PowerShell:
(Get-IAMGroup -GroupName "GroupToDelete").Users | Remove-IAMUserFromGroup -GroupName
"GroupToDelete" -Force
• AWS API: GetGroup (to get the list of users in the group), and RemoveUserFromGroup (to remove
a user from the group)
2.
Delete all inline policies embedded in the group.
• CLI: aws iam list-group-policies (to get a list of the group's inline policies), and aws iam deletegroup-policy (to delete the group's inline policies)
• Tools for Windows PowerShell:
Get-IAMGroupPolicies -GroupName "GroupToReplace" | % { Remove-IAMGroupPolicy GroupName "GroupToReplace" -PolicyName $_ -Force}
• AWS API: ListGroupPolicies (to get a list of the group's inline policies), and DeleteGroupPolicy (to
delete the group's inline policies)
3.
Detach all managed policies attached to the group.
• CLI: aws iam list-attached-group-policies (to get a list of the managed policies attached to the
group), and aws iam detach-group-policy (to detach a managed policy from the group)
• Tools for Windows PowerShell:
Get-IAMAttachedUserPolicies -UserName "UserToDelete" | % { Unregister-IAMUserPolicy PolicyArn $_.PolicyArn -UserName -UserName "UserToDelete" -Force }
• AWS API: ListAttachedGroupPolicies (to get a list of the managed policies attached to the group'),
and DetachGroupPolicy (to detach a managed policy from the group)
4.
Delete the group.
• CLI: aws iam delete-group
• Tools for Windows PowerShell: Remove-IAMGroup
• AWS API: DeleteGroup
IAM Roles
An IAM role is similar to a user, in that it is an AWS identity with permission policies that determine what
the identity can and cannot do in AWS. However, instead of being uniquely associated with one person,
a role is intended to be assumable by anyone who needs it. Also, a role does not have any credentials
(password or access keys) associated with it. Instead, if a user is assigned to a role, access keys are created
dynamically and provided to the user.
97
AWS Identity and Access Management User Guide
Terms and Concepts
You can use roles to delegate access to users, applications, or services that don't normally have access to
your AWS resources. For example, you might want to grant users in your AWS account access to resources
they don't usually have, or grant users in one AWS account access to resources in another account. Or
you might want to allow a mobile app to use AWS resources, but not want to embed AWS keys within
the app (where they can be difficult to rotate and where users can potentially extract them). Sometimes
you want to give AWS access to users who already have identities defined outside of AWS, such as in your
corporate directory. Or, you might want to grant access to your account to third parties so that they can
perform an audit on your resources.
For these scenarios, you can delegate access to AWS resources using an IAM role. This section introduces
roles and the different ways you can use them, when and how to choose among approaches, and how to
create, manage, switch to (or assume), and delete roles.
Topics
• Roles Terms and Concepts (p. 98)
• Common Scenarios for Roles: Users, Applications, and Services (p. 100)
• Identity Providers and Federation (p. 105)
• Using Service-Linked Roles (p. 139)
• Creating IAM Roles (p. 146)
• Using IAM Roles (p. 167)
• Managing IAM Roles (p. 183)
• How IAM Roles Differ from Resource-based Policies (p. 191)
Roles Terms and Concepts
Here are some basic terms to help you get started with roles.
Role
A set of permissions that grant access to actions and resources in AWS. These permissions are
attached to the role, not to an IAM user or group. Roles can be used by the following:
• An IAM user in the same AWS account as the role
• An IAM user in a different AWS account as the role
• A web service offered by AWS such as Amazon Elastic Compute Cloud (Amazon EC2)
• An external user authenticated by an external identity provider (IdP) service that is compatible
with SAML 2.0 or OpenID Connect, or a custom-built identity broker.
AWS service role
A role that a service assumes to perform actions on your behalf. When you set up most AWS service
environments, you must define a role for the service to assume. This service role must include all
the permissions required for the service to access the AWS resources that it needs. Service roles vary
from service to service, but many allow you to choose your permissions, as long as you meet the
documented requirements for that service. You can create, modify, and delete a service role from
within IAM.
AWS service role for an EC2 instance
A special type of service role that a service assumes to launch an Amazon EC2 instance that runs
your application. This role is assigned to the EC2 instance when it is launched. AWS automatically
provides temporary security credentials that are attached to the role and then makes them available
for the EC2 instance to use on behalf of its applications. For details about using a service role for an
EC2 instance, see Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2
Instances (p. 177).
98
AWS Identity and Access Management User Guide
Terms and Concepts
AWS service-linked role
A unique type of service role that is linked directly to an AWS service. Service-linked roles are
predefined by the service and include all the permissions that the service requires to call other AWS
services on your behalf. The linked service also defines how you create, modify, and delete a servicelinked role. A service might automatically create or delete the role. It might allow you to create,
modify, or delete the role as part of a wizard or process in the service. Or it might require that you
use IAM to create or delete the role. Regardless of the method, service-linked roles make setting up
a service easier because you don’t have to manually add the necessary permissions.
Note
If you are already using a service when it begins supporting service-linked roles, you might
receive an email telling you about a new role in your account. In this case, the service
automatically created the service-linked role in your account. You don't need to take any
action to support this role, and you should not manually delete it. For more information,
see A New Role Appeared in My IAM Account (p. 347).
For information about which services support using service-linked roles, see AWS Services That
Work with IAM (p. 363) and look for the services that have Yes in the Service-Linked Role column.
Choose a Yes with a link to view the service-linked role documentation for that service. If the service
does not include documentation for creating, modifying, or deleting the service-linked role, then you
can use the IAM console, CLI, or API. For more information, see Using Service-Linked Roles (p. 139).
Delegation
The granting of permission to someone to allow access to resources that you control. Delegation
involves setting up a trust between the account that owns the resource (the trusting account), and
the account that contains the users that need to access the resource (the trusted account). The
trusted and trusting accounts can be any of the following:
• The same account.
• Two accounts that are both under your (organization's) control.
• Two accounts owned by different organizations.
To delegate permission to access a resource, you create an IAM role (p. 146) that has two
policies (p. 100) attached. The permissions policy grants the user of the role the needed
permissions to carry out the intended tasks on the resource. The trust policy specifies which trusted
accounts are allowed to grant its users permissions to assume the role.
When you create a trust policy, you cannot specify a wildcard (*) as a principal. The trust policy
on the role in the trusting account is one-half of the permissions. The other half is a permissions
policy attached to the user in the trusted account that allows that user to switch to, or assume
the role (p. 167). A user who assumes a role temporarily gives up his or her own permissions and
instead takes on the permissions of the role. When the user exits, or stops using the role, the original
user permissions are restored. An additional parameter called external ID (p. 149) helps ensure
secure use of roles between accounts that are not controlled by the same organization.
Federation
The creation of a trust relationship between an external identity provider and AWS. Users can sign
in to a web identity provider, such as Login with Amazon, Facebook, Google, or any IdP that is
compatible with OpenID Connect (OIDC). Users can also sign in to an enterprise identity system
that is compatible with Security Assertion Markup Language (SAML) 2.0, such as Microsoft Active
Directory Federation Services. When you use OIDC and SAML 2.0 to configure a trust relationship
between these external identity providers and AWS, the user is assigned to an IAM role and receives
temporary credentials that enable the user to access your AWS resources.
Trust policy
A document in JSON format in which you define who is allowed to assume the role. This trusted
entity is included in the policy as the principal element in the document. The document is written
according to the rules of the IAM policy language (p. 373).
99
AWS Identity and Access Management User Guide
Common Scenarios
Permissions policy
A permissions document in JSON format in which you define what actions and resources the role can
use. The document is written according to the rules of the IAM policy language (p. 373).
Principal
An entity in AWS that can perform actions and access resources. A principal can be an IAM user, or a
role. You can grant permissions to access a resource in one of two ways:
• You can attach a permissions policy to a user (directly, or indirectly through a group) or to a role.
• For those services that support resource-based policies (p. 7), you can identify the principal in the
Principal element of a policy attached to the resource.
If you reference an AWS account as principal, it generally means any principal defined within that
account.
Note
You cannot use a wildcard (*) in the Principal element in a role's trust policy.
Role for cross-account access
Granting access to resources in one account to a trusted principal in a different account. Roles are
the primary way to grant cross-account access. However, with some of the web services offered by
AWS you can attach a policy directly to a resource (instead of using a role as a proxy). These are
called resource-based policies, and you can use them to grant principals in another AWS account
access to the resource. The following services support resource-based policies for the specified
resources: Amazon Simple Storage Service (S3) buckets, Amazon Glacier vaults, Amazon Simple
Notification Service (SNS) topics, and Amazon Simple Queue Service (SQS) queues. For more
information, see How IAM Roles Differ from Resource-based Policies (p. 191).
Common Scenarios for Roles: Users, Applications, and
Services
As with most AWS features, you generally have two ways to use a role: interactively in the IAM console,
or programmatically with the AWS CLI, Tools for Windows PowerShell, or API.
• IAM users in your account using the IAM console can switch to a role to temporarily use the
permissions of the role in the console. The users give up their original permissions and take on the
permissions assigned to the role. When the users exit the role, their original permissions are restored.
• An application or a service offered by AWS (like Amazon EC2) can assume a role by requesting
temporary security credentials for a role with which to make programmatic requests to AWS. You use
a role this way so that you don't have to share or maintain long-term security credentials (for example,
by creating an IAM user) for each entity that requires access to a resource.
Note
This guide uses the phrases switch to a role and assume a role interchangeably.
The simplest way to use roles is to grant your IAM users permissions to switch to roles that you create
within your own or another AWS account. They can switch roles easily using the IAM console to use
permissions that you don't ordinarily want them to have, and then exit the role to surrender those
permissions. This can help prevent accidental access to or modification of sensitive resources.
For more complex uses of roles, such as granting access to applications and services, or federated
external users, you can call the AssumeRole API. This API call returns a set of temporary credentials that
the application can use in subsequent API calls. Actions attempted with the temporary credentials have
only the permissions granted by the associated role. An application doesn't have to "exit" the role the
100
AWS Identity and Access Management User Guide
Common Scenarios
way a user in the console does; rather the application simply stops using the temporary credentials and
resumes making calls with the original credentials.
Federated users sign in by using credentials from an identity provider (IdP). AWS then provides
temporary credentials to the trusted IdP to pass on to the user for including in subsequent AWS resource
requests. Those credentials provide the permissions granted to the assigned role.
This section provides overviews of the following scenarios:
• Provide access for an IAM user in one AWS account that you own to access resources in another
account that you own (p. 101)
• Provide access to IAM users in AWS accounts owned by third parties (p. 103)
• Provide access for services offered by AWS to AWS resources (p. 103)
• Provide access for externally authenticated users (identity federation) (p. 104)
Providing Access to an IAM User in Another AWS Account That
You Own
You can grant your IAM users permission to switch to roles within your AWS account or to roles defined
in other AWS accounts that you own.
Note
If you want to grant access to an account that you do not own or control, see Providing Access to
AWS Accounts Owned by Third Parties (p. 103) later in this topic.
Imagine that you have Amazon Elastic Compute Cloud (Amazon EC2) instances that are critical to your
organization. Instead of directly granting your users permission to terminate the instances, you can
create a role with those privileges and allow administrators to switch to the role when they need to
terminate an instance. This adds the following layers of protection to the instances:
• You must explicitly grant your users permission to assume the role.
• Your users must actively switch to the role using the AWS Management Console.
We recommend using this approach to enforce the principle of least access, that is, restricting the use
of elevated permissions to only those times when they are needed for specific tasks. With roles you
can help prevent accidental changes to sensitive environments, especially if you combine them with
auditing (p. 323) to help ensure that roles are only used when needed.
When you create a role for this purpose, you specify the accounts by ID whose users need access in the
Principal element of the role's trust policy. You can then grant specific users in those other accounts
permissions to switch to the role.
A user in one account can switch to a role in the same or a different account. While using the role, the
user can perform only the actions and access only the resources permitted by the role; their original user
permissions are suspended. When the user exits the role, the original user permissions are restored.
Example Scenario Using Separate Development and Production Accounts
Imagine that your organization has multiple AWS accounts to isolate a development environment
from a production environment. Users in the development account might occasionally need to access
resources in the production account, such as when you are promoting an update from the development
environment to the production environment. Although you could create separate identities (and
passwords) for users who work in both accounts, managing credentials for multiple accounts makes
101
AWS Identity and Access Management User Guide
Common Scenarios
identity management difficult. In the following figure, all users are managed in the development
account, but some developers require limited access to the production account. The development
account has two groups: Testers and Developers, and each group has its own policy.
1. In the production account an administrator uses IAM to create the UpdateAPP role in that account.
In the role, the administrator defines a trust policy that specifies the development account as a
Principal, meaning that authorized users from the development account can use the UpdateAPP
role. The administrator also defines a permissions policy for the role that specifies that users of
the role have read and write permissions to the Amazon Simple Storage Service (S3) bucket named
productionapp.
The administrator then shares the account number and name of the role (for AWS console users)
or the Amazon Resource Name (ARN) (for AWS CLI, Tools for Windows PowerShell, or AWS API
access) of the role with anyone who needs to assume the role. The role ARN might look like arn:awscn:iam::123456789012:role/UpdateAPP, where the role is named UpdateAPP and the role was created
in account number 123456789012.
2. In the development account an administrator grants members of the Developers group permission to
switch to the role. This is done by granting the Developers group permission to call the AWS Security
Token Service (AWS STS) AssumeRole API for the UpdateAPP role. Any IAM user that belongs to the
Developers group in the development account can now switch to the UpdateAPP role in the production
account. Other users who are not in the developer group do not have permission to switch to the role
and therefore cannot access the S3 bucket in the production account.
3. The user requests switches to the role:
• AWS console: The user chooses the account name on the navigation bar and chooses Switch Role.
The user specifies the account ID (or alias) and role name. Alternatively, the user can click on a link
sent in email by the administrator. The link takes the user to the Switch Role page with the details
already filled in.
• AWS API/Tools for Windows PowerShell/AWS CLI: A user in the Developers group of the
development account calls the AssumeRole function to obtain credentials for the UpdateAPP
role. The user specifies the ARN of the UpdateAPP role as part of the call. If a user in the Testers
group makes the same request, the request fails because Testers do not have permission to call
AssumeRole for the UpdateAPP role ARN.
4. AWS STS returns temporary credentials:
• AWS console: AWS STS verifies the request with the role's trust policy to ensure that the request
is from a trusted entity (which it is: the development account). After verification, AWS STS returns
temporary security credentials to the AWS console.
102
AWS Identity and Access Management User Guide
Common Scenarios
• API/CLI: AWS STS verifies the request against the role's trust policy to ensure that the request is
from a trusted entity (which it is: the Development account). After verification, AWS STS returns
temporary security credentials to the application.
5. The temporary credentials allow access to the AWS resource:
• AWS console: The AWS console uses the temporary credentials on behalf of the user on all
subsequent console actions, in this case, to read and write to the productionapp bucket. The
console cannot access any other resource in the production account. When the user exits the role,
the user's permissions revert to the original permissions held before switching to the role.
• API/CLI: The application uses the temporary security credentials to update the productionapp
bucket. With the temporary security credentials, the application can only read from and write to
the productionapp bucket and cannot access any other resource in the Production account. The
application does not have to exit the role, but instead stops using the temporary credentials and
uses the original credentials in subsequent API calls.
Providing Access to AWS Accounts Owned by Third Parties
When third parties require access to your organization's AWS resources, you can use roles to delegate
access to them. For example, a third party might provide a service for managing your AWS resources.
With IAM roles, you can grant these third parties access to your AWS resources without sharing your AWS
security credentials. Instead, the third party can access your AWS resources by assuming a role that you
create in your AWS account.
Third parties must provide you with the following information for you to create a role that they can
assume:
• The third party's AWS account ID. You specify their AWS account ID as the principal when you define
the trust policy for the role.
• An external ID to uniquely associate with the role. The external ID can be any secret identifier that is
known by you and the third party. For example, you can use an invoice ID between you and the third
party, but do not use something that can be guessed, like the name of phone number of the third
party. You must specify this ID when you define the trust policy for the role. The third party must
provide this ID when they assume the role. For more information about the external ID, see How to Use
an External ID When Granting Access to Your AWS Resources to a Third Party (p. 149).
• The permissions that the third party requires to work with your AWS resources. You must specify these
permissions when defining the role's access policy. This policy defines what actions they can take and
what resources they can access.
After you create the role, you must provide the role's Amazon Resource Name (ARN) to the third party.
They require your role's ARN in order to assume the role.
For details about creating a role to delegate access to a third party, see How to Use an External ID When
Granting Access to Your AWS Resources to a Third Party (p. 149).
Important
When you grant third parties access to your AWS resources, they can access any resource that
you specify in the policy. Their use of your resources is billed to you. Ensure that you limit their
use of your resources appropriately.
Providing Access to an AWS Service
Many AWS services require that you use roles to control what that service can access. A role that a
service assumes to perform actions on your behalf is called a service role (p. 98). When a role serves
a specialized purpose for a service, it can be categorized as a service role for EC2 instances (p. 98), or
a service-linked role (p. 99). See the AWS documentation for each service to see if it uses roles and to
learn how to assign a role for the service to use.
103
AWS Identity and Access Management User Guide
Common Scenarios
For details about creating a role to delegate access to a service offered by AWS, see Creating a Role to
Delegate Permissions to an AWS Service (p. 153).
Providing Access to Externally Authenticated Users (Identity
Federation)
Your users might already have identities outside of AWS, such as in your corporate directory. If those
users need to work with AWS resources (or work with applications that access those resources), then
those users also need AWS security credentials. You can use an IAM role to specify permissions for users
whose identity is federated from your organization or a third-party identity provider (IdP).
Federating Users of a Mobile or Web-based App with Amazon Cognito
If you create a mobile or web-based app that accesses AWS resources, the app needs security credentials
in order to make programmatic requests to AWS. For most mobile application scenarios, we recommend
that you use Amazon Cognito. You can use this service with the AWS Mobile SDK for iOS and the AWS
Mobile SDK for Android and Fire OS to create unique identities for users and authenticate them for
secure access to your AWS resources. Amazon Cognito supports the same identity providers as those
listed in next section, and it also supports developer authenticated identities and unauthenticated
(guest) access. Amazon Cognito also provides APIs for synchronizing user data so that it is preserved
as users move between devices. For more information, see Using Amazon Cognito for Mobile
Apps (p. 107).
Federating Users with Public Identity Service Providers or OpenID Connect
Whenever possible, use Amazon Cognito for mobile and web-based application scenarios. Amazon
Cognito does most of the behind-the-scenes work with public identity provider services for you. It works
with the same third-party services and also supports anonymous sign-ins. However, for more advanced
scenarios, you can work directly with a third-party service like Login with Amazon, Facebook, Google, or
any IdP that is compatible with OpenID Connect (OIDC). For more information about using web identity
federation using one of these services, see About Web Identity Federation (p. 106).
Federating users with SAML 2.0
If your organization already uses an identity provider software package that supports SAML 2.0 (Security
Assertion Markup Language 2.0), you can create trust between your organization as an identity provider
(IdP) and AWS as the service provider. You can then use SAML to provide your users with federated
single-sign on (SSO) to the AWS Management Console or federated access to call AWS APIs. For example,
if your company uses Microsoft Active Directory and Active Directory Federation Services, then you can
federate using SAML 2.0. For more information about federating users with SAML 2.0, see About SAML
2.0-based Federation (p. 112).
Federating users by creating a custom identity broker application
If your identity store is not compatible with SAML 2.0, then you can build a custom identity broker
application to perform a similar function. The broker application authenticates users, requests temporary
credentials for users from AWS, and then provides them to the user to access AWS resources.
For example, Example Corp. has many employees who need to run internal applications that access
the company's AWS resources. The employees already have identities in the company identity and
authentication system, and Example Corp. doesn't want to create a separate IAM user for each company
employee.
Bob is a developer at Example Corp. To enable Example Corp. internal applications to access the
company's AWS resources, Bob develops a custom identity broker application. The application verifies
that employees are signed into the existing Example Corp. identity and authentication system, which
might use LDAP, Active Directory, or another system. The identity broker application then obtains
temporary security credentials for the employees. This scenario is similar to the previous one (a mobile
104
AWS Identity and Access Management User Guide
Identity Providers and Federation
app that uses a custom authentication system), except that the applications that need access to AWS
resources all run within the corporate network, and the company has an existing authentication system.
To get temporary security credentials, the identity broker application calls either AssumeRole or
GetFederationToken to obtain temporary security credentials, depending on how Bob wants to manage
the policies for users and when the temporary credentials should expire. (For more information about
the differences between these APIs, see Temporary Security Credentials (p. 193) and Controlling
Permissions for Temporary Security Credentials (p. 207).) The call returns temporary security
credentials consisting of an AWS access key ID, a secret access key, and a session token. The identity
broker application makes these temporary security credentials available to the internal company
application. The app can then use the temporary credentials to make calls to AWS directly. The app
caches the credentials until they expire, and then requests a new set of temporary credentials. The
following figure illustrates this scenario.
This scenario has the following attributes:
• The identity broker application has permissions to access IAM's token service (STS) API to create
temporary security credentials.
• The identity broker application is able to verify that employees are authenticated within the existing
authentication system.
• Users are able to get a temporary URL that gives them access to the AWS Management Console (which
is referred to as single sign-on).
To see a sample application similar to the identity broker application that is described in this scenario,
go to Identity Federation Sample Application for an Active Directory Use Case at AWS Sample Code &
Libraries. For information about creating temporary security credentials, seeRequesting Temporary
Security Credentials (p. 195). For more information about federated users getting access to the
AWS Management Console, see Enabling SAML 2.0 Federated Users to Access the AWS Management
Console (p. 129).
Identity Providers and Federation
If you already manage user identities outside of AWS, you can use IAM identity providers instead of
creating IAM users in your AWS account. With an identity provider (IdP), you can manage your user
105
AWS Identity and Access Management User Guide
Identity Providers and Federation
identities outside of AWS and give these external user identities permissions to use AWS resources in
your account. This is useful if your organization already has its own identity system, such as a corporate
user directory. It is also useful if you are creating a mobile app or web application that requires access to
AWS resources.
When you use an IdP, you don't have to create custom sign-in code or manage your own user identities;
the IdP provides that for you. Your external users sign in through a well-known identity provider, such
as Login with Amazon, Facebook, Google, and many others. You can give those external identities
permissions to use AWS resources in your account. Identity providers help keep your AWS account secure
because you don't have to distribute or embed long-term security credentials, such as IAM access keys, in
your application.
To use an IdP, you create an IAM identity provider entity to establish a trust relationship between your
AWS account and the IdP. IAM supports IdPs that are compatible with OpenID Connect (OIDC) or SAML
2.0 (Security Assertion Markup Language 2.0). For more information about using one of these IdPs with
AWS, see the following sections:
• About Web Identity Federation (p. 106)
• About SAML 2.0-based Federation (p. 112)
For details about creating the identity provider entity in IAM to establish a trust relationship between a
compatible IdP and AWS, see Creating IAM Identity Providers (p. 116)
About Web Identity Federation
Imagine that you are creating a mobile app that accesses AWS resources, such as a game that runs on a
mobile device and stores player and score information using Amazon S3 and DynamoDB.
When you write such an app, you'll make requests to AWS services that must be signed with an AWS
access key. However, we strongly recommend that you do not embed or distribute long-term AWS
credentials with apps that a user downloads to a device, even in an encrypted store. Instead, build your
app so that it requests temporary AWS security credentials dynamically when needed using web identity
federation. The supplied temporary credentials map to an AWS role that has only the permissions needed
to perform the tasks required by the mobile app.
With web identity federation, you don't need to create custom sign-in code or manage your own user
identities. Instead, users of your app can sign in using a well-known identity provider (IdP) —such as
Login with Amazon, Facebook, Google, or any other OpenID Connect (OIDC)-compatible IdP, receive an
authentication token, and then exchange that token for temporary security credentials in AWS that map
to an IAM role with permissions to use the resources in your AWS account. Using an IdP helps you keep
your AWS account secure, because you don't have to embed and distribute long-term security credentials
with your application.
For most scenarios, we recommend that you use Amazon Cognito because it acts as an identity broker
and does much of the federation work for you. For details, see the following section, Using Amazon
Cognito for Mobile Apps (p. 107).
If you don't use Amazon Cognito, then you must write code that interacts with a web IdP
(Login with Amazon, Facebook, Google, or any other OIDC-compatible IdP) and then calls the
AssumeRoleWithWebIdentity API to trade the authentication token you get from those IdPs for AWS
temporary security credentials. If you have already used this approach for existing apps, you can
continue to use it.
Topics
• Using Amazon Cognito for Mobile Apps (p. 107)
• Using Web Identity Federation APIs for Mobile Apps (p. 108)
• Identifying Users with Web Identity Federation (p. 110)
106
AWS Identity and Access Management User Guide
Identity Providers and Federation
• Additional Resources for Web Identity Federation (p. 111)
Using Amazon Cognito for Mobile Apps
The preferred way to use web identity federation is to use Amazon Cognito. For example, Adele the
developer is building a game for a mobile device where user data such as scores and profiles is stored
in Amazon S3 and Amazon DynamoDB. Adele could also store this data locally on the device and use
Amazon Cognito to keep it synchronized across devices. She knows that for security and maintenance
reasons, long-term AWS security credentials should not be distributed with the game. She also knows
that the game might have a large number of users. For all of these reasons, she does not want to create
new user identities in IAM for each player. Instead, she builds the game so that users can sign in using
an identity that they've already established with a well-known identity provider, such as Login with
Amazon, Facebook, Google, or any OpenID Connect (OIDC)-compatible identity provider. Her game
can take advantage of the authentication mechanism from one of these providers to validate the user's
identity.
To enable the mobile app to access her AWS resources, Adele first registers for a developer ID with her
chosen IdPs. She also configures the application with each of these providers. In her AWS account that
contains the Amazon S3 bucket and DynamoDB table for the game, Adele uses Amazon Cognito to
create IAM roles that precisely define permissions that the game needs. If she is using an OIDC IdP, she
also creates an IAM OIDC identity provider entity to establish trust between her AWS account and the
IdP.
In the app's code, Adele calls the sign-in interface for the IdP that she configured previously. The IdP
handles all the details of letting the user sign in, and the app gets an OAuth access token or OIDC ID
token from the provider. Adele's app can trade this authentication information for a set of temporary
security credentials that consist of an AWS access key ID, a secret access key, and a session token. The
app can then use these credentials to access web services offered by AWS. The app is limited to the
permissions that are defined in the role that it assumes.
The following figure shows a simplified flow for how this might work, using Login with Amazon as the
IdP. For Step 2, the app can also use Facebook, Google, or any OIDC-compatible identity provider, but
that's not shown here.
1. A customer starts your app on a mobile device. The app asks the user to sign in.
107
AWS Identity and Access Management User Guide
Identity Providers and Federation
2. The app uses Login with Amazon resources to accept the user's credentials.
3. The app uses Cognito APIs to exchange the Login with Amazon ID token for a Cognito token.
4. The app requests temporary security credentials from AWS STS, passing the Cognito token.
5. The temporary security credentials can be used by the app to access any AWS resources required
by the app to operate. The role associated with the temporary security credentials and its assigned
policies determines what can be accessed.
Use the following process to configure your app to use Amazon Cognito to authenticate users and
give your app access to AWS resources. For specific steps to accomplish this scenario, consult the
documentation for Amazon Cognito.
1. (Optional) Sign up as a developer with Login with Amazon, Facebook, Google, or any other OpenID
Connect (OIDC)–compatible identity provider and configure one or more apps with the provider. This
step is optional because Amazon Cognito also supports unauthenticated (guest) access for your users.
2. Go to Amazon Cognito in the AWS Management Console. Use the Amazon Cognito wizard to create
an identity pool, which is a container that Amazon Cognito uses to keep end user identities organized
for your apps. You can share identity pools between apps. When you set up an identity pool, Amazon
Cognito creates one or two IAM roles (one for authenticated identities, and one for unauthenticated
"guest" identities) that define permissions for Amazon Cognito users.
3. Download and integrate the AWS SDK for iOS or the AWS SDK for Android with your app, and import
the files required to use Amazon Cognito.
4. Create an instance of the Amazon Cognito credentials provider, passing the identity pool ID, your AWS
account number, and the Amazon Resource Name (ARN) of the roles that you associated with the
identity pool. The Amazon Cognito wizard in the AWS Management Console provides sample code to
help you get started.
5. When your app accesses an AWS resource, pass the credentials provider instance to the client object,
which passes temporary security credentials to the client. The permissions for the credentials are
based on the role or roles that you defined earlier.
For more information, see the following:
• Amazon Cognito Identity in the AWS Mobile SDK for Android Developer Guide.
• Amazon Cognito Identity in the AWS Mobile SDK for iOS Developer Guide.
Using Web Identity Federation APIs for Mobile Apps
For best results, use Amazon Cognito as your identity broker for almost all web identity federation
scenarios. Amazon Cognito is easy to use and provides additional capabilities like anonymous
(unauthenticated) access, and synchronizing user data across devices and providers. However,
if you have already created an app that uses web identity federation by manually calling the
AssumeRoleWithWebIdentity API, you can continue to use it and your apps will still work fine.
Note
To help understand how web identity federation works, you can use the Web Identity Federation
Playground. This interactive website lets you walk through the process of authenticating via
Login with Amazon, Facebook, or Google, getting temporary security credentials, and then using
those credentials to make a request to AWS.
The process for using web identity federation without Amazon Cognito follows this general outline:
1. Sign up as a developer with the IdP and configure your app with the IdP, who gives you a unique ID
for your app. (Different IdPs use different terminology for this process. This outline uses the term
configure for the process of identifying your app with the IdP.) Each IdP gives you an app ID that's
108
AWS Identity and Access Management User Guide
Identity Providers and Federation
unique to that IdP, so if you configure the same app with multiple IdPs, your app will have multiple
app IDs. You can configure multiple apps with each provider.
The following external links provide information about using some of the commonly used identity
providers:
• Login with Amazon Developer Center
• Add Facebook Login to Your App or Website on the Facebook developers site.
• Using OAuth 2.0 for Login (OpenID Connect) on the Google developers site.
Note
Although Amazon Cognito and Google are based on OIDC technology, you don't have to
create an identity provider entity in IAM to use them. Support for Amazon Cognito and
Google are built-in to AWS.
2. If you use an IdP that is compatible with OIDC, then create an identity provider entity for it in IAM.
3. In IAM, create one or more roles (p. 156). For each role, define who can assume the role (the trust
policy) and what permissions the app's users are to have (the permissions policy). Typically, you create
one role for each IdP that an app supports. For example, you might create a role that is assumed by
an app when the user signs in through Login with Amazon, a second role for the same app where the
user signs in through Facebook, and a third role for the app where the user signs in through Google.
For the trust relationship, specify the IdP (like Amazon.com) as the Principal (the trusted entity), and
include a Condition that matches the IdP assigned app ID. Examples of roles for different providers
are described later in this topic.
4. In your application, authenticate your users with the IdP. The specifics of how to do this vary both
according to which IdP you're using (Login with Amazon, Facebook, or Google) and on which platform
your app. For example, an Android app's method of authentication can differ from that of an iOS app
or a JavaScript-based web app.
Typically, if the user is not already signed in, the IdP takes care of displaying a sign-in page. After the
IdP authenticates the user, the IdP returns an authentication token with information about the user to
your app. The information included depends on what the IdP exposes and what information the user
is willing to share. You can use this information in your app.
5. In your app, make an unsigned call to the AssumeRoleWithWebIdentity action to request temporary
security credentials. In the request, you pass the IdP's authentication token and specify the Amazon
Resource Name (ARN) for the IAM role that you created for that IdP. AWS verifies that the token
is trusted and valid and if so, returns temporary security credentials to your app that have the
permissions for the role that you name in the request. The response also includes metadata about the
user from the IdP, such as the unique user ID that the IdP associates with the user.
6. Using the temporary security credentials from the AssumeRoleWithWebIdentity response, your app
makes signed requests to AWS APIs. The user ID information from the identity provider can distinguish
users in your app—for example, you can put objects into Amazon S3 folders that include the user
ID as prefixes or suffixes. This lets you create access control policies that lock the folder so only
the user with that ID can access it. For more information, see Identifying Users with Web Identity
Federation (p. 110) later in this topic.
7. Your app should cache the temporary security credentials so that you do not have to get new ones
each time the app needs to make a request to AWS. By default, the credentials are good for one hour.
When the credentials expire (or before then), you make another call to AssumeRoleWithWebIdentity
to obtain a new set of temporary security credentials. Depending on the IdP and how they
manage their tokens, you might have to refresh the IdP's token before you make a new call to
AssumeRoleWithWebIdentity, since the IdP's tokens also usually expire after a fixed time. If you use the
AWS SDK for iOS or the AWS SDK for Android, you can use the AmazonSTSCredentialsProvider action,
which manages the IAM temporary credentials, including refreshing them as required.
109
AWS Identity and Access Management User Guide
Identity Providers and Federation
Identifying Users with Web Identity Federation
When you create access policies in IAM, it's often useful to be able to specify permissions based on
configured apps and on the ID of users who have authenticated using an identity provider. For example,
your mobile app that's using web identity federation might keep information in Amazon S3 using a
structure like this:
myBucket/app1/user1
myBucket/app1/user2
myBucket/app1/user3
...
myBucket/app2/user1
myBucket/app2/user2
myBucket/app2/user3
...
You might also want to additionally distinguish these paths by provider. In that case, the structure might
look like the following (only two providers are listed to save space):
myBucket/Amazon/app1/user1
myBucket/Amazon/app1/user2
myBucket/Amazon/app1/user3
...
myBucket/Amazon/app2/user1
myBucket/Amazon/app2/user2
myBucket/Amazon/app2/user3
myBucket/Facebook/app1/user1
myBucket/Facebook/app1/user2
myBucket/Facebook/app1/user3
...
myBucket/Facebook/app2/user1
myBucket/Facebook/app2/user2
myBucket/Facebook/app2/user3
...
For these structures, app1 and app2 represent different apps, such as different games, and each user of
the app has a distinct folder. The values for app1 and app2 might be friendly names that you assign (for
example, mynumbersgame) or they might be the app IDs that the providers assign when you configure your
app. If you decide to include provider names in the path, those can also be friendly names like Cognito,
Amazon, Facebook, and Google.
You can typically create the folders for app1 and app2 through the AWS Management Console, since
the application names are static values. That's true also if you include the provider name in the path,
since the provider name is also a static value. In contrast, the user-specific folders (user1, user2,
user3, etc.) have to be created at run time from the app, using the user ID that's available in the
SubjectFromWebIdentityToken value that is returned by the request to AssumeRoleWithWebIdentity.
To write policies that allow exclusive access to resources for individual users, you can match the complete
folder name, including the app name and provider name, if you're using that. You can then include the
following provider-specific context keys that reference the user ID that the provider returns:
•
•
•
•
cognito-identity.amazonaws.com:sub
www.amazon.com:user_id
graph.facebook.com:id
accounts.google.com:sub
For OIDC providers, use the fully qualified URL of the OIDC provider with the subcontext key, like the
following example:
110
AWS Identity and Access Management User Guide
Identity Providers and Federation
• server.example.com:sub
The following example shows an access policy that grants access to a bucket in Amazon S3 only if the
prefix for the bucket matches the string:
myBucket/Amazon/mynumbersgame/user1
The example assumes that the user is signed in using Login with Amazon, and that the user is using an
app called mynumbersgame. The user's unique ID is presented as an attribute called user_id.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": ["arn:aws-cn:s3:::myBucket"],
"Condition": {"StringLike": {"s3:prefix": ["Amazon/mynumbersgame/
${www.amazon.com:user_id}/*"]}}
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": [
"arn:aws-cn:s3:::myBucket/amazon/mynumbersgame/${www.amazon.com:user_id}",
"arn:aws-cn:s3:::myBucket/amazon/mynumbersgame/${www.amazon.com:user_id}/*"
]
}
]
}
You would create similar policies for users who sign in using Amazon Cognito, Facebook, Google, or
another OpenID Connect–compatible IdP. Those policies would use a different provider name as part of
the path as well as different app IDs.
For more information about the web identity federation keys available for condition checks in policies,
see Available Keys for Web Identity Federation (p. 426).
Additional Resources for Web Identity Federation
The following resources can help you learn more about web identity federation:
• Amazon Cognito Identity in the AWS Mobile SDK for Android Developer Guide and Amazon Cognito
Identity in the AWS Mobile SDK for iOS Developer Guide.
• The Web Identity Federation Playground is an interactive website that lets you walk through the
process of authenticating via Login with Amazon, Facebook, or Google, , getting temporary security
credentials, and then using those credentials to make a request to AWS.
• The entry Web Identity Federation using the AWS SDK for .NET on the AWS .NET Development blog
walks through how to use web identity federation with Facebook and includes code snippets in C# that
show how to call AssumeRoleWithWebIdentity and how to use the temporary security credentials from
that API call to access an S3 bucket.
• The AWS SDK for iOS and the AWS SDK for Android contain sample apps. These apps include code that
shows how to invoke the identity providers and then how to use the information from these providers
to get and use temporary security credentials.
111
AWS Identity and Access Management User Guide
Identity Providers and Federation
• The article Web Identity Federation with Mobile Applications discusses web identity federation and
shows an example of how to use web identity federation to get access to content in Amazon S3.
About SAML 2.0-based Federation
AWS supports identity federation with SAML 2.0 (Security Assertion Markup Language 2.0), an open
standard that many identity providers (IdPs) use. This feature enables federated single sign-on (SSO), so
users can log into the AWS Management Console or call the AWS APIs without you having to create an
IAM user for everyone in your organization. By using SAML, you can simplify the process of configuring
federation with AWS, because you can use the IdP's service instead of writing custom identity proxy code.
IAM federation supports these use cases:
• Federated access to allow a user or application in your organization to call AWS APIs (p. 112). You
use a SAML assertion (as part of the authentication response) that is generated in your organization
to get temporary security credentials. This scenario is similar to other federation scenarios that IAM
supports, like those described in Requesting Temporary Security Credentials (p. 195) and About Web
Identity Federation (p. 106). However, SAML 2.0–based identity providers in your organization handle
many of the details at run time for performing authentication and authorization checking. This is the
scenario discussed in this topic.
• Web-based single sign-on (SSO) to the AWS Management Console from your
organization (p. 129). Users can sign in to a portal in your organization hosted by a SAML 2.0–
compatible IdP, select an option to go to AWS, and be redirected to the console without having to
provide additional sign-in information. In addition to being able to use a third-party SAML IdP to
establish SSO access to the console, you can alternatively create a custom IdP to enable console
access for your external users. For more information about building a custom IdP, see Creating a
URL that Enables Federated Users to Access the AWS Management Console (Custom Federation
Broker) (p. 132).
Using SAML-Based Federation for API Access to AWS
Imagine that in your organization, you want to provide a way for users to copy data from their computers
to a backup folder. You build an application that users can run on their computers. On the back end, the
application reads and writes objects in an S3 bucket. Users don't have direct access to AWS. Instead, the
following process is used:
112
AWS Identity and Access Management User Guide
Identity Providers and Federation
1. A user in your organization uses a client app to request authentication from your organization's IdP.
2. The IdP authenticates the user against your organization's identity store.
3. The IdP constructs a SAML assertion with information about the user and sends the assertion to the
client app.
4. The client app calls the AWS STS AssumeRoleWithSAML API, passing the ARN of the SAML provider, the
ARN of the role to assume, and the SAML assertion from IdP.
5. The API response to the client app includes temporary security credentials.
6. The client app uses the temporary security credentials to call Amazon S3 APIs.
Overview of Configuring SAML 2.0-Based Federation
Before you can use SAML 2.0-based federation as described in the preceding scenario and diagram, you
must configure your organization's IdP and your AWS account to trust each other. The general process
for configuring this trust is described in the following steps. Inside your organization, you must have an
IdP that supports SAML 2.0 (p. 124), like Microsoft Active Directory Federation Service (AD FS, part of
Windows Server), Shibboleth, or another compatible SAML 2.0 provider.
To configure your organization's IdP and AWS to trust each other
1.
You begin by registering AWS with your IdP. In your organization's IdP you register AWS as a service
provider (SP) by using the SAML metadata document that you get from the following URL:
https://signin.amazonaws.cn/static/saml-metadata.xml
2.
Using your organization's IdP, you generate an equivalent metadata XML file that can describe your
IdP as an identity provider to AWS. It must include the issuer name, a creation date, an expiration
date, and keys that AWS can use to validate authentication responses (assertions) from your
organization.
3.
In the IAM console, you create a SAML identity provider entity. As part of this process, you upload
the SAML metadata document that was produced by the IdP in your organization in Step 2. For more
information, see Creating SAML Identity Providers (p. 121).
113
AWS Identity and Access Management User Guide
Identity Providers and Federation
4.
In IAM, you create one or more IAM roles. In the role's trust policy, you set the SAML provider as
the principal, which establishes a trust relationship between your organization and AWS. The role's
permission policy establishes what users from your organization are allowed to do in AWS. For more
information, see Creating a Role for a Third-Party Identity Provider (Federation) (p. 156).
5.
In your organization's IdP, you define assertions that map users or groups in your organization to
the IAM roles. Note that different users and groups in your organization might map to different IAM
roles. The exact steps for performing the mapping depend on what IdP you're using. In the earlier
scenario (p. 112) of an Amazon S3 folder for users, it's possible that all users will map to the same
role that provides Amazon S3 permissions. For more information, see Configuring SAML Assertions
for the Authentication Response (p. 125).
If your IdP enables SSO to the AWS console, then you can configure the maximum duration of the
console sessions. For more information, see Enabling SAML 2.0 Federated Users to Access the AWS
Management Console (p. 129).
Note
The AWS implementation of SAML 2.0 federation does not support encrypted SAML
assertions between the identity provider and AWS. However, the traffic between the
customer's systems and AWS is transmitted over an encrypted (TLS) channel.
6.
In the application that you're creating, you call the AWS Security Token Service AssumeRoleWithSAML
API, passing it the ARN of the SAML provider you created in Step 3, the ARN of the role to assume
that you created in Step 4, and the SAML assertion about the current user that you get from your
IdP. AWS makes sure that the request to assume the role comes from the IdP referenced in the SAML
provider.
For more information, see AssumeRoleWithSAML in the AWS Security Token Service API Reference.
7.
If the request is successful, the API returns a set of temporary security credentials, which your
application can use to make signed requests to AWS. Your application has information about the
current user and can access user-specific folders in Amazon S3, as described in the previous scenario.
Overview of the Role to Allow SAML-Federated Access to Your AWS Resources
The role or roles that you create in IAM define what federated users from your organization are allowed
to do in AWS. When you create the trust policy for the role, you specify the SAML provider that you
created earlier as the Principal. You can additionally scope the trust policy with a Condition to allow
only users that match certain SAML attributes to access the role. For example, you can specify that only
users whose SAML affiliation is staff (as asserted by https://openidp.feide.no) are allowed to access the
role, as illustrated by the following sample policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"AWS": "arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:saml-provider/
ExampleOrgSSOProvider"},
"Action": "sts:AssumeRoleWithSAML",
"Condition": {
"StringEquals": {
"saml:aud": "https://signin.amazonaws.cn/saml",
"saml:iss": "https://openidp.feide.no"
},
"ForAllValues:StringLike": {"saml:edupersonaffiliation": ["staff"]}
}
}]
}
For more information about the SAML keys that you can check in a policy, see Available Keys for SAMLBased Federation (p. 427).
114
AWS Identity and Access Management User Guide
Identity Providers and Federation
For the access policy in the role, you specify permissions as you would for any role. For example, if
users from your organization are allowed to administer Amazon Elastic Compute Cloud instances,
you must explicitly allow Amazon EC2 actions in the permissions policy, such as those in the
AmazonEC2FullAccess managed policy.
Uniquely Identifying Users in SAML-Based Federation
When you create access policies in IAM, it's often useful to be able to specify permissions based on the
identity of users. For example, for users who have been federated using SAML, an application might want
to keep information in Amazon S3 using a structure like this:
myBucket/app1/user1
myBucket/app1/user2
myBucket/app1/user3
You can create the bucket (myBucket) and folder (app1) through the Amazon S3 console or the AWS CLI,
since those are static values. However, the user-specific folders (user1, user2, user3, etc.) have to be
created at run time using code, since the value that identifies the user isn't known until the first time the
user signs in through the federation process.
To write policies that reference user-specific details as part of a resource name, the user identity has
to be available in SAML keys that can be used in policy conditions. The following keys are available for
SAML 2.0–based federation for use in IAM policies. You can use the values returned by the following keys
to create unique user identifiers for resources like Amazon S3 folders.
• saml:namequalifier. A hash value based on the concatenation of the Issuer response value
(saml:iss) and a string with the AWS account ID and the friendly name (the last part of the ARN) of the
SAML provider in IAM. The concatenation of the account ID and friendly name of the SAML provider is
available to IAM policies as the key saml:doc. The account ID and provider name must be separated by
a '/' as in "123456789012/provider_name". For more information, see the saml:doc key at Available
Keys for SAML-Based Federation (p. 427).
The combination of NameQualifier and Subject can be used to uniquely identify a federated
user. The following pseudocode shows how this value is calculated. In this pseudocode + indicates
concatenation, SHA1 represents a function that produces a message digest using SHA-1, and Base64
represents a function that produces Base-64 encoded version of the hash output.
Base64 ( SHA1 ( "https://example.com/saml" + "123456789012" + "/MySAMLIdP" ) )
For more information about the policy keys that are available for SAML-based federation, see Available
Keys for SAML-Based Federation (p. 427).
• saml:sub (string). This is the subject of the claim, which includes a value that uniquely identifies an
individual user within an organization (for example, _cbb88bf52c2510eabe00c1642d4643f41430fe25e3).
• saml:sub_type (string). This key can be persistent, transient, or the full Format URI from the
Subject and NameID elements used in your SAML assertion. A value of persistent indicates that
the value in saml:sub is the same for a user across all sessions. If the value is transient, the user
has a different saml:sub value for each session. For information about the NameID element's Format
attribute, see Configuring SAML Assertions for the Authentication Response (p. 125).
The following example shows an access policy that uses the preceding keys to grant permissions to a
user-specific folder in Amazon S3. The policy assumes that the Amazon S3 objects are identified using a
prefix that includes both saml:namequalifier and saml:sub. Notice that the Condition element includes
a test to be sure that saml:sub_type is set to persistent. If it is set to transient, the saml:sub value for
the user can be different for each session, and the combination of values should not be used to identity
user-specific folders.
{
115
AWS Identity and Access Management User Guide
Identity Providers and Federation
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": [
"arn:aws-cn:s3:::exampleorgBucket/backup/${saml:namequalifier}/${saml:sub}",
"arn:aws-cn:s3:::exampleorgBucket/backup/${saml:namequalifier}/${saml:sub}/*"
],
"Condition": {"StringEquals": {"saml:sub_type": "persistent"}}
}
}
For more information about mapping assertions from the IdP to policy keys, see Configuring SAML
Assertions for the Authentication Response (p. 125).
Creating IAM Identity Providers
When you want to configure federation with an external identity provider service (IdP), you create an
identity provider in the IAM console to inform AWS about the IdP and its configuration. This establishes
"trust" between your AWS account and the IdP. The following topics include details about how to create
an identity provider in IAM for each of the IdP types.
Topics
• Creating OpenID Connect (OIDC) Identity Providers (p. 116)
• Creating SAML Identity Providers (p. 121)
Creating OpenID Connect (OIDC) Identity Providers
OIDC identity providers are entities in IAM that describe an identity provider (IdP) service that supports
the OpenID Connect (OIDC) standard. You use an OIDC identity provider when you want to establish
trust between an OIDC-compatible IdP—such as Google, Salesforce, and many others—and your AWS
account. This is useful if you are creating a mobile app or web application that requires access to AWS
resources, but you don't want to create custom sign-in code or manage your own user identities. For
more information about this scenario, see the section called “About Web Identity Federation” (p. 106).
You can create and manage an OIDC identity provider using the AWS Management Console, the AWS
Command Line Interface, the Tools for Windows PowerShell, or the IAM API.
Topics
• Creating and Managing an OIDC Provider (AWS Management Console) (p. 116)
• Creating and Managing an OIDC Identity Provider (AWS CLI, Tools for Windows PowerShell, and IAM
API) (p. 117)
• Obtaining the Thumbprint for an OpenID Connect Identity Provider (p. 118)
Creating and Managing an OIDC Provider (AWS Management Console)
Follow these instructions to create and manage an OIDC provider in the AWS Management Console.
To create an OIDC identity provider
1.
Before you create an OIDC identity provider in IAM, you must register your application with the IdP
to receive a client ID. The client ID (also known as audience) is a unique identifier for your app that is
116
AWS Identity and Access Management User Guide
Identity Providers and Federation
2.
3.
4.
5.
issued to you when you register your app with the IdP. For more information about obtaining a client
ID, see the documentation for your IdP.
Open the IAM console at https://console.amazonaws.cn/iam/.
In the navigation pane, click Identity Providers, and then click Create Provider.
For Provider Type, click Choose a provider type, and then choose OpenID Connect.
For Provider URL, type the URL of the IdP. The URL must comply with these restrictions:
• The URL is case-sensitive.
• The URL must begin with https://
• The URL cannot include a colon (:) character, and therefore cannot specify a port number. This
means that the server must be listening on the default port 443.
• Within your AWS account, each OIDC identity provider must use a unique URL.
6.
For Audience, type the client ID of the application that you registered with the IdP and received
in Step 1, and that will make requests to AWS. If you have additional client IDs (also known as
audiences) for this IdP, you can add them later on the provider detail page. Click Next Step.
7.
Use the Thumbprint to verify the server certificate of your IdP. To learn how, see Obtaining the
Thumbprint for an OpenID Connect Identity Provider (p. 118). Click Create.
8.
In the confirmation message at the top of the screen, click Do this now to go to the Roles tab to
create a role for this identity provider. For more information about creating a role for an OIDC
identity provider, see Creating a Role for a Third-Party Identity Provider (Federation) (p. 156). OIDC
identity providers must have a role in order to access your AWS account. To skip this step and create
the role later, click Close.
To add or remove a thumbprint or client ID (also known as audience) for an OIDC identity
provider
1.
Open the IAM console at https://console.amazonaws.cn/iam/.
2.
In the navigation pane, click Identity Providers, then click the name of the identity provider that
you want to update.
3.
To add a thumbprint or audience, click Add a Thumbprint or Add an Audience. To remove a
thumbprint or audience, click Remove next to the item that you want to remove.
Note
An OIDC identity provider must have at least 1 and can have a maximum of 5 thumbprints.
An OIDC identity provider must have at least 1 and can have a maximum of 100 audiences.
When you are done, click Save Changes.
To delete an OIDC identity provider
1.
2.
Open the IAM console at https://console.amazonaws.cn/iam/.
In the navigation pane, click Identity Providers.
3.
4.
Select the check box next to the identity provider that you want to delete.
Click Delete Providers.
Creating and Managing an OIDC Identity Provider (AWS CLI, Tools for Windows PowerShell, and
IAM API)
Use the following commands to create and manage an OIDC provider.
To create a new OIDC provider
• AWS CLI: aws iam create-open-id-connect-provider
117
AWS Identity and Access Management User Guide
Identity Providers and Federation
• Tools for Windows PowerShell: New-IAMOpenIDConnectProvider
• IAM API: CreateOpenIDConnectProvider
To add a new client ID to an existing OIDC provider
• AWS CLI: aws iam add-client-id-to-open-id-connect-provider
• Tools for Windows PowerShell: Add-IAMClientIDToOpenIDConnectProvider
• IAM API: AddClientIDToOpenIDConnectProvider
To remove a client ID from an existing OIDC provider
• AWS CLI: aws iam remove-client-id-from-open-id-connect-provider
• Tools for Windows PowerShell: Remove-IAMClientIDToOpenIDConnectProvider
• IAM API: RemoveClientIDFromOpenIDConnectProvider
To update the list of server certificate thumbprints for an existing OIDC provider
• AWS CLI: aws iam update-open-id-connect-provider-thumbprint
• Tools for Windows PowerShell: Update-IAMOpenIDConnectProviderThumbprint
• IAM API: UpdateOpenIDConnectProviderThumbprint
To get a list of all the OIDC providers in your AWS account
• AWS CLI: aws iam list-open-id-connect-providers
• Tools for Windows PowerShell: Get-IAMOpenIDConnectProviders
• IAM API: ListOpenIDConnectProviders
To get detailed information about an OIDC provider
• AWS CLI: aws iam get-open-id-connect-provider
• Tools for Windows PowerShellGet-IAMOpenIDConnectProvider:
• IAM API: GetOpenIDConnectProvider
To delete an OIDC provider
• AWS CLI: aws iam delete-open-id-connect-provider
• Tools for Windows PowerShell: Remove-IAMOpenIDConnectProvider
• IAM API: DeleteOpenIDConnectProvider
Obtaining the Thumbprint for an OpenID Connect Identity Provider
When you create an OpenID Connect (OIDC) identity provider (p. 116) in IAM, you must supply a
thumbprint for the identity provider (IdP). The thumbprint is a signature for the unique server certificate
that is used by the OIDC-compatible IdP. When you create an OIDC identity provider in IAM, you are
trusting identities authenticated by that IdP with access to your AWS account. By supplying the OIDC
IdP's thumbprint, you assert to AWS that you wish to trust a particular OIDC IdP with this access.
When you create an OIDC identity provider with the AWS Command Line Interface, the Tools for
Windows PowerShell, or the IAM API (p. 117), you must obtain the thumbprint manually and supply it
to AWS. When you create an OIDC identity provider with the IAM console (p. 116), the console attempts
118
AWS Identity and Access Management User Guide
Identity Providers and Federation
to fetch the thumbprint for you. We recommend that you also obtain the thumbprint for your OIDC IdP
manually and verify that the thumbprint obtained by the IAM console matches the one you expect for
your OIDC provider.
You use a web browser and the OpenSSL command line tool to obtain the thumbprint for an OIDC
provider. For more information, see the following sections.
To obtain the thumbprint for an OIDC IdP
1.
Before you can obtain the thumbprint for an OIDC IdP, you need to obtain the OpenSSL commandline tool. You use this tool to download the OIDC IdP's certificate chain and produce a thumbprint of
the final certificate in the certificate chain. If you need to install and configure OpenSSL, follow the
instructions at Install OpenSSL (p. 120) and Configure OpenSSL (p. 120).
2.
Start with the OIDC IdP's URL (for example, https://server.example.com), and then add /.wellknown/openid-configuration to form the URL for the IdP's configuration document, like the
following:
https://server.example.com/.well-known/openid-configuration
Open this URL in a web browser, replacing server.example.com with your IdP's server name.
3.
In the document displayed in your web browser, find "jwks_uri". (Use your web browser's Find
feature to locate this text on the page.) Immediately following the text "jwks_uri" you will see a
colon (:) followed by a URL. Copy the fully qualified domain name of the URL. Do not include the
https:// or any path that comes after the top-level domain.
4.
Use the OpenSSL command line tool to execute the following command. Replace keys.example.com
with the domain name you obtained in Step 3.
openssl s_client -showcerts -connect keys.example.com:443
5.
In your command window, scroll up until you see a certificate similar to the following example. If
you see more than one certificate, find the last certificate that is displayed (at the bottom of the
command output).
-----BEGIN CERTIFICATE----MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6
b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd
BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN
MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD
VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z
b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt
YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ
21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T
rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE
Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4
nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb
FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb
NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE=
-----END CERTIFICATE-----
6.
Copy the certificate (including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----lines) and paste it into a text file. Then save the file with the file name certificate.crt.
Use the OpenSSL command-line tool to execute the following command.
openssl x509 -in certificate.crt -fingerprint -noout
Your command window displays the certificate thumbprint, which looks similar to the following
example:
119
AWS Identity and Access Management User Guide
Identity Providers and Federation
SHA1 Fingerprint=99:0F:41:93:97:2F:2B:EC:F1:2D:DE:DA:52:37:F9:C9:52:F2:0D:9E
Remove the colon characters (:) from this string to produce the final thumbprint, like this:
990F4193972F2BECF12DDEDA5237F9C952F20D9E
7.
If you are creating the IAM identity provider with the AWS CLI, Tools for Windows PowerShell, or the
IAM API, supply this thumbprint when creating the provider.
If you are creating the OIDC provider in the IAM console, compare this thumbprint to the thumbprint
that you see in the console on the Verify Provider Information page when creating an OIDC
provider.
Important
If the thumbprint you obtained does not match the one you see in the console, you should
not create the OIDC provider in IAM. Instead, you should wait a while and then try again
to create the OIDC provider, ensuring that the thumbprints match before you create the
provider. If the thumbprints still do not match after a second attempt, use the IAM Forum
to contact AWS.
Install OpenSSL
If you don't already have OpenSSL installed, follow the instructions in this section.
To install OpenSSL on Linux or Unix
1.
Go to OpenSSL: Source, Tarballs (https://openssl.org/source/).
2.
Download the latest source and build the package.
To install OpenSSL on Windows
1.
Go to OpenSSL: Binary Distributions (https://wiki.openssl.org/index.php/Binaries) for a list of sites
from which you can install the Windows version.
2.
Follow the instructions on your selected site to start the installation.
3.
If you are asked to install the Microsoft Visual C++ 2008 Redistributables and it is not already
installed on your system, choose the download link appropriate for your environment. Follow the
instructions provided by the Microsoft Visual C++ 2008 Redistributable Setup Wizard.
Note
If you are not sure whether the Microsoft Visual C++ 2008 Redistributables is already
installed on your system, you can try installing OpenSSL first. The OpenSSL installer
displays an alert if the Microsoft Visual C++ 2008 Redistributables is not yet installed. Make
sure you install the architecture (32-bit or 64-bit) that matches the version of OpenSSL that
you install.
4.
After you have installed the Microsoft Visual C++ 2008 Redistributables, select the appropriate
version of the OpenSSL binaries for your environment and save the file locally. Start the OpenSSL
Setup Wizard.
5.
Follow the instructions described in the OpenSSL Setup Wizard.
Configure OpenSSL
Before you use OpenSSL commands, you must configure the operating system so that it has information
about the location where OpenSSL is installed.
120
AWS Identity and Access Management User Guide
Identity Providers and Federation
To configure OpenSSL on Linux or Unix
1.
At the command line, set the OpenSSL_HOME variable to the location of the OpenSSL installation:
$ export OpenSSL_HOME=path_to_your_OpenSSL_installation
2.
Set the path to include the OpenSSL installation:
$ export PATH=$PATH:$OpenSSL_HOME/bin
Note
Any changes you make to environment variables with the export command are valid only
for the current session. You can make persistent changes to the environment variables by
setting them in your shell configuration file. For more information, see the documentation
for your operating system.
To configure OpenSSL on Windows
1.
Open a Command Prompt window.
2.
Set the OpenSSL_HOME variable to the location of the OpenSSL installation:
C:\> set OpenSSL_HOME=path_to_your_OpenSSL_installation
3.
Set the OpenSSL_CONF variable to the location of the configuration file in your OpenSSL installation:
C:\> set OpenSSL_CONF=path_to_your_OpenSSL_installation\bin\openssl.cfg
4.
Set the path to include the OpenSSL installation:
C:\> set Path=%Path%;%OpenSSL_HOME%\bin
Note
Any changes you make to Windows environment variables in a Command Prompt window
are valid only for the current command line session. You can make persistent changes to the
environment variables by setting them as system properties. The exact procedures depends
on what version of Windows you're using. (For example, in Windows 7, open Control Panel,
System and Security, System. Then choose Advanced system settings, Advanced tab,
Environment Variables.) For more information, see the Windows documentation.
Creating SAML Identity Providers
A SAML 2.0 identity provider is an entity in IAM that describes an identity provider (IdP) service that
supports the SAML 2.0 (Security Assertion Markup Language 2.0) standard. You use a SAML identity
provider when you want to establish trust between an SAML-compatible IdP such as Shibboleth or Active
Directory Federation Services so that users in your organization can access AWS resources. SAML identity
providers in IAM are used as principals in an IAM trust policy.
For more information about this scenario, see About SAML 2.0-based Federation (p. 112).
You can create and manage a SAML identity provider in the AWS Management Console or with AWS CLI,
Tools for Windows PowerShell, or AWS API calls.
After you create a SAML provider, you must create one or more IAM roles. A role is an identity in AWS
that doesn't have its own credentials (as a user does) but is, in this context, dynamically assigned to a
federated user that is authenticated by your organization's identity provider (IdP). The role permits your
121
AWS Identity and Access Management User Guide
Identity Providers and Federation
organization's IdP to request temporary security credentials for access to AWS. The policies assigned
to the role determine what the federated users are allowed to do in AWS. To create a role for SAML
federation, see Creating a Role for a Third-Party Identity Provider (Federation) (p. 156).
Finally, after you create the role, you complete the SAML trust by configuring your IdP with information
about AWS and the role(s) that you want your federated users to use. This is referred to as configuring
relying party trust between your IdP and AWS. To configure relying party trust, see Configuring your
SAML 2.0 IdP with Relying Party Trust and Adding Claims (p. 123).
Topics
• Creating and Managing a SAML Identity Provider (AWS Management Console) (p. 122)
• Managing a SAML Provider (AWS CLI, Tools for Windows PowerShell and AWS API) (p. 123)
• Configuring your SAML 2.0 IdP with Relying Party Trust and Adding Claims (p. 123)
• Integrating Third-Party SAML Solution Providers with AWS (p. 124)
• Configuring SAML Assertions for the Authentication Response (p. 125)
Creating and Managing a SAML Identity Provider (AWS Management Console)
You can use the AWS Management Console to create and delete SAML identity providers.
To create a SAML identity provider
1.
Before you can create a SAML identity provider, you need the SAML metadata document that you
get from the IdP that includes the issuer's name, expiration information, and keys that can be
used to validate the SAML authentication response (assertions) that are received from the IdP. To
generate the metadata document, use the identity management software your organization uses as
its IdP. For instructions on how to configure many of the available IdPs to work with AWS, including
how to generate the required SAML metadata document, see Integrating Third-Party SAML Solution
Providers with AWS (p. 124).
Important
The metadata file must be encoded in UTF-8 format without a byte order mark (BOM). Also,
the x.509 certificate that is included as part of the SAML metadata document must use a
key size of at least 1024 bits. If the key size is smaller, the IdP creation fails with an "Unable
to parse metadata" error. To remove the BOM, you can encode the file as UTF-8 using a text
editing tool, such as Notepad++.
2.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
3.
In the navigation pane, click Identity Providers and then click Create Provider.
4.
For Provider Type, click Choose a provider type and click SAML.
5.
Type a name for the identity provider.
6.
For Metadata Document, click Choose File, specify the SAML metadata document that you
downloaded in Step 1, and click Open. Click Next Step.
7.
Verify the information you have provided, and click Create.
To delete a SAML provider
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, click Identity Providers.
3.
Select the check box next to the identity provider that you want to delete.
4.
Click Delete Providers.
122
AWS Identity and Access Management User Guide
Identity Providers and Federation
Managing a SAML Provider (AWS CLI, Tools for Windows PowerShell and AWS API)
Use the following commands to create and manage a SAML provider.
To create an identity provider and upload a metadata document
• AWS CLI: aws iam create-saml-provider
• Tools for Windows PowerShell: New-IAMSAMLProvider
• AWS API: CreateSAMLProvider
To upload a new metadata document for an IdP
• AWS CLI: aws iam update-saml-provider
• Tools for Windows PowerShell: Update-IAMSAMLProvider
• AWS API: UpdateSAMLProvider
To get information about a specific provider, such as the ARN, creation date, and expiration
• AWS CLI: aws iam get-saml-provider
• Tools for Windows PowerShell: Get-IAMSAMLProvider
• AWS API: GetSAMLProvider
To list information for all IdPs, such as the ARN, creation date, and expiration
• AWS CLI: aws iam list-saml-providers
• Tools for Windows PowerShell: Get-IAMSAMLProviders
• AWS API: ListSAMLProviders
To delete an IdP
• AWS CLI: aws iam delete-saml-provider
• Tools for Windows PowerShell: Remove-IAMSAMLProvider
• AWS API: DeleteSAMLProvider
Configuring your SAML 2.0 IdP with Relying Party Trust and Adding Claims
When you create a SAML provider and the role for SAML access in IAM, you are essentially telling AWS
about the identity provider (IdP) and what its users are allowed to do. Your next step is to then tell the
IdP about AWS as a service provider. This is called adding relying party trust between your IdP and AWS.
The exact process for adding relying party trust depends on what IdP you're using; for details, see the
documentation for your identity management software.
Many IdPs allow you to specify a URL from which the IdP can read an XML document that contains
relying party information and certificates. For AWS, you can use https://signin.aws.amazon.com/
static/saml-metadata.xml
If you can't specify a URL directly, then download the XML document from the preceding URL and import
it into your IdP software.
You also need to create appropriate claim rules in your IdP that specify AWS as a relying party. When
the IdP sends a SAML response to the AWS endpoint, it includes a SAML assertion that contains one or
more claims. A claim is information about the user and its groups. A claim rule maps that information
123
AWS Identity and Access Management User Guide
Identity Providers and Federation
into SAML attributes. This lets you make sure that SAML authentication responses from your IdP contain
the necessary attributes that AWS uses in IAM policies to check permissions for federated users. For more
information, see the following topics:
• Overview of the Role to Allow SAML-Federated Access to Your AWS Resources (p. 114). This topic
discusses using SAML-specific keys in IAM policies and how to use them to restrict permissions for
SAML-federated users.
• Configuring SAML Assertions for the Authentication Response (p. 125). This topic discusses how
to configure SAML claims that include information about the user. The claims are bundled into
a SAML assertion and included in the SAML response that is sent to AWS. You must ensure that
the information needed by AWS policies is included in the SAML assertion in a form that AWS can
recognize and use.
• Integrating Third-Party SAML Solution Providers with AWS (p. 124). This topic provides links to
documentation provided by third-party organizations about how to integrate identity solutions with
AWS.
Integrating Third-Party SAML Solution Providers with AWS
The following links help you configure third-party SAML 2.0 identity provider solutions to work with AWS
federation.
Solution
More information
Auth0
AWS Integration in Auth0 – This page on the Auth0
documentation website describes how to set up single signon (SSO) with the AWS Management Console and includes a
JavaScript example.
Bitium
Configuring SAML for Amazon Web Services (AWS) – This
article on the Bitium support site explains how to use Bitium
to set up AWS with SAML SSO.
Centrify
Configure Centrify and Use SAML for SSO to AWS – This page
on the Centrify website explains how to configure Centrify to
use SAML for SSO to AWS.
CertiVox
Setting up M-Pin SSO as an Identity Provider within AWS –
This page on the CertiVox website explains how to configure
an AWS service provider for SSO authentication through your
M-Pin SSO system.
Clearlogin
Amazon Web Services Setup – This article in the Clearlogin
Help Center explains how to set up SSO functionality between
Clearlogin and AWS.
Google G Suite
Amazon Web Services cloud application – This article on the
Google G Suite Administrator Help site describes how to
configure G Suite as a SAML 2.0 IdP with AWS as the service
provider.
Identacor
Configuring SSO (SAML) for AWS – This article on the
Identacor website describes how to set up and enable SSO for
AWS.
Matrix42
MyWorkspace Getting Started Guide – This guide describes
how to integrate AWS identity services with Matrix42
MyWorkspace.
124
AWS Identity and Access Management User Guide
Identity Providers and Federation
Solution
More information
Microsoft Active Directory Federation
Services (AD FS)
Enabling Federation to AWS Using Windows Active Directory,
AD FS, and SAML 2.0 – This post on the AWS Security Blog
shows how to set up AD FS on an EC2 instance and enable
SAML federation with AWS.
PowerShell Automation to Give AWS Console Access – This
post on Sivaprasad Padisetty's blog describes how to use
Windows PowerShell to automate the process of setting
up Active Directory and AD FS as well as enabling SAML
federation with AWS.
miniOrange
SSO for AWS – This page on the miniOrange website describes
how to establish secure access to AWS for enterprises and full
control over access of AWS applications.
Okta
Amazon Web Services and Okta Integration Guide – From this
page on the Okta support site you can download a PDF file
that describes how to configure Okta for use with AWS.
OneLogin
Configuring SAML Single-Role for AWS – This article in
the OneLogin Help Center explains how to set up SSO
functionality between OneLogin and AWS.
Ping Identity
PingFederate AWS Connector – From this page on the Ping
Identity website, you can download a PDF file that describes
how to configure a PingFederate server to enable SSO for user
accounts with AWS.
Configuring an SSO connection to AWS – This Ping Identity
page describes how to configure an SSO connection from
PingOne to AWS.
RadiantLogic
Radiant Logic Technology Partners – Radiant Logic's
RadiantOne Federated Identity Service integrates with AWS to
provide an identity hub for SAML-based SSO.
Salesforce.com
How to configure SSO from Salesforce to AWS – This how-to
article on the Salesforce.com developer site describes how to
set up an identity provider (IdP) in Salesforce and configure
AWS as a service provider.
SecureAuth
AWS - SecureAuth SAML SSO – This article on the SecureAuth
website describes how to set up SAML integration with AWS
for a SecureAuth appliance.
Shibboleth
How to Use Shibboleth for SSO to the AWS Management
Console – This entry on the AWS Security Blog provides
a step-by-step tutorial on how to set up Shibboleth and
configure it as an identity provider for AWS.
For more details, see the IAM Partners page on the AWS website.
Configuring SAML Assertions for the Authentication Response
In your organization, after a user's identity has been verified, the IdP sends an authentication response to
the AWS SAML endpoint at https://signin.aws.amazon.com/saml. This response is a POST request that
125
AWS Identity and Access Management User Guide
Identity Providers and Federation
includes a SAML token that adheres to the HTTP POST Binding for SAML 2.0 standard and that contains
the following elements, or claims. You configure these claims in your SAML-compatible IdP. Refer to the
documenation for your IdP for instructions on how to enter these claims.
When the IdP sends the response containing the claims to AWS, many of the incoming claims map
to AWS context keys that can be checked in IAM policies using the Condition element. A listing of
the available mappings follows in the section Mapping SAML Attributes to AWS Trust Policy Context
Keys (p. 128).
Subject and NameID
The following excerpt shows an example. Substitute your own values for the marked ones. There
must be exactly 1 SubjectConfirmation element with a SubjectConfirmationData element that
includes both the NotOnOrAfter attribute and a Recipient attribute with a value that must match
the AWS endpoint (https://signin.aws.amazon.com/saml), as shown in the following example. For
information about the name identifier formats supported for single sign-on interactions, see Oracle
Sun OpenSSO Enterprise Administration Reference.
<Subject>
<NameID Format="urn:oasis:names:tc:SAML:2.0:nameidformat:persistent">_cbb88bf52c2510eabe00c1642d4643f41430fe25e3</NameID>
<SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<SubjectConfirmationData NotOnOrAfter="2013-11-05T02:06:42.876Z"
Recipient="https://signin.aws.amazon.com/saml"/>
</SubjectConfirmation>
</Subject>
AudienceRestriction and Audience
For security reasons, AWS must be included as an audience in the SAML assertion your IdP sends to
AWS. Therefore, the value of the Audience element must match one of the following two values,
either https://signin.aws.amazon.com/saml or urn:amazon:webservices. AWS tests and enforces
this value automatically. The following sample XML snippet from a SAML assertion shows how this
key can be specified by the IdP and shows both valid values; you only need to include one.
<Conditions>
<AudienceRestriction>
<Audience>https://signin.aws.amazon.com/saml</Audience>
<Audience>urn:amazon:webservices</Audience>
</AudienceRestriction>
</Conditions>
Important
The SAML AudienceRestriction value in the SAML assertion from the IdP does not map to
the saml:aud context key that you can test in an IAM policy. Instead, the saml:aud context
key comes from the SAML recipient attribute because it is the SAML equivalent to the OIDC
audience field, for example, by accounts.google.com:aud.
An Attribute element with the Name attribute set to https://aws.amazon.com/SAML/Attributes/Role
This element contains one or more AttributeValue elements that list the IAM role and SAML
identity provider to which the user is mapped by your IdP. The role and identity provider are
specified as a comma-delimited pair of ARNs in the same format as the RoleArn and PrincipalArn
parameters that are passed to AssumeRoleWithSAML. This element must contain at least one roleprovider pair—that is, at least one AttributeValue element—and can contain multiple pairs. If the
element contains multiple pairs, then the user is asked to select which role to assume when he or
she uses WebSSO to sign into the AWS Management Console.
Important
The value of the Name attribute in the Attribute tag is case-sensitive. It must be set to
https://aws.amazon.com/SAML/Attributes/Role exactly.
126
AWS Identity and Access Management User Guide
Identity Providers and Federation
<Attribute Name="https://aws.amazon.com/SAML/Attributes/Role">
<AttributeValue>arn:aws-cn:iam::account-number:role/role-name1,arn:awscn:iam::account-number:saml-provider/provider-name</AttributeValue>
<AttributeValue>arn:aws-cn:iam::account-number:role/role-name2,arn:awscn:iam::account-number:saml-provider/provider-name</AttributeValue>
<AttributeValue>arn:aws-cn:iam::account-number:role/role-name3,arn:awscn:iam::account-number:saml-provider/provider-name</AttributeValue>
</Attribute>
An Attribute element with the Name attribute set to https://aws.amazon.com/SAML/Attributes/
RoleSessionName
This element contains one AttributeValue element that provides an identifier for the AWS
temporary credentials that are issued for SSO and is used to display user information in the
AWS Management Console. The value in the AttributeValue element must be between
2 and 64 characters long, can contain only alphanumeric characters, underscores, and the
following characters: + (plus sign), = (equals sign), , (comma), . (period), @ (at symbol), and (hyphen). It cannot contain spaces. The value is typically a user ID (bobsmith) or an email address
([email protected]). It should not be a value that includes a space, like a user's display name
(Bob Smith).
Important
The value of the Name attribute in the Attribute tag is case-sensitive. It must be set to
https://aws.amazon.com/SAML/Attributes/RoleSessionName exactly.
<Attribute Name="https://aws.amazon.com/SAML/Attributes/RoleSessionName">
<AttributeValue>user-id-name</AttributeValue>
</Attribute>
An optional Attribute element with the SessionDuration attribute set to https://aws.amazon.com/
SAML/Attributes/SessionDuration
This element contains one AttributeValue element that specifies the maximum time that the user
can access the AWS Management Console before having to request new temporary credentials.
The value is an integer representing the number of seconds, and can be a maximum of 43200
seconds (12 hours). If this attribute is not present, then the maximum session duration defaults
to one hour (the default value of the DurationSeconds parameter of the AssumeRoleWithSAML
API). To use this attribute, you must configure the SAML provider to provide single sign-on
access to the AWS Management Console through the console sign-in web endpoint at https://
signin.aws.amazon.com/saml. Note that this attribute extends sessions only to the AWS
Management Console. It cannot extend the lifetime of other credentials. However, if it is present in
an AssumeRoleWithSAML API call, it can be used to shorten the lifetime of the credentials returned by
the call to less than the default of 60 minutes.
Note, too, that if a SessionNotOnOrAfter attribute is also defined, then the lesser value of the two
attributes, SessionDuration or SessionNotOnOrAfter, establishes the maximum duration of the
console session.
When you enable console sessions with an extended duration the risk of compromise of the
credentials rises. To help you mitigate this risk, you can immediately disable the active console
sessions for any role by choosing Revoke Sessions on the Role Summary page in the IAM console.
For more information, see Revoking IAM Role Temporary Security Credentials (p. 182).
Important
The value of the Name attribute in the Attribute tag is case-sensitive. It must be set to
https://aws.amazon.com/SAML/Attributes/SessionDuration exactly.
<Attribute Name="https://aws.amazon.com/SAML/Attributes/SessionDuration">
127
AWS Identity and Access Management User Guide
Identity Providers and Federation
<AttributeValue>7200</AttributeValue>
</Attribute>
Mapping SAML Attributes to AWS Trust Policy Context Keys
The tables in this section list commonly used SAML attributes and how they map to trust policy
condition context keys in AWS. You can use these keys to control access to a role by evaluating them
against the values included in the assertions that accompany a SAML request to access a role.
Important
These keys are available only in IAM trust policies (policies that determine who can assume a
role) and are not applicable to permissions policies.
In the eduPerson and eduOrg attributes table, values are typed either as strings or as lists of strings.
For string values, you can test these values in IAM trust policies using StringEquals or StringLike
conditions. For values that contain a list of strings, you can use the ForAnyValue and ForAllValues policy
set operators (p. 401) to test the values in trust policies.
Note
You should include only one claim per AWS context key. If you include more than one, only one
claim will be mapped.
eduPerson and eduOrg Attributes
eduPerson or eduOrg attribute (Name key)
Maps to this AWS context
key (FriendlyName key)
Type
urn:oid:1.3.6.1.4.1.5923.1.1.1.1
eduPersonAffiliation
List of strings
urn:oid:1.3.6.1.4.1.5923.1.1.1.2
eduPersonNickname
List of strings
urn:oid:1.3.6.1.4.1.5923.1.1.1.3
eduPersonOrgDN
String
urn:oid:1.3.6.1.4.1.5923.1.1.1.4
eduPersonOrgUnitDN
List of strings
urn:oid:1.3.6.1.4.1.5923.1.1.1.5
eduPersonPrimaryAffiliation
String
urn:oid:1.3.6.1.4.1.5923.1.1.1.6
eduPersonPrincipalName
String
urn:oid:1.3.6.1.4.1.5923.1.1.1.7
eduPersonEntitlement
List of strings
urn:oid:1.3.6.1.4.1.5923.1.1.1.8
eduPersonPrimaryOrgUnitDN String
urn:oid:1.3.6.1.4.1.5923.1.1.1.9
eduPersonScopedAffiliationList of strings
urn:oid:1.3.6.1.4.1.5923.1.1.1.10
eduPersonTargetedID
List of strings
urn:oid:1.3.6.1.4.1.5923.1.1.1.11
eduPersonAssurance
List of strings
urn:oid:1.3.6.1.4.1.5923.1.2.1.2
eduOrgHomePageURI
List of strings
urn:oid:1.3.6.1.4.1.5923.1.2.1.3
eduOrgIdentityAuthNPolicyURI
List of strings
urn:oid:1.3.6.1.4.1.5923.1.2.1.4
eduOrgLegalName
List of strings
urn:oid:1.3.6.1.4.1.5923.1.2.1.5
eduOrgSuperiorURI
List of strings
urn:oid:1.3.6.1.4.1.5923.1.2.1.6
eduOrgWhitePagesURI
List of strings
urn:oid:2.5.4.3
cn
List of strings
128
AWS Identity and Access Management User Guide
Identity Providers and Federation
Active Directory Attributes
AD attribute
Maps to this AWS
context key
Type
http://schemas.xmlsoap.org/ws/2005/05/identity/
claims/name
name
String
http://schemas.xmlsoap.org/claims/CommonName
commonName
String
http://schemas.xmlsoap.org/ws/2005/05/identity/
claims/givenname
givenName
String
http://schemas.xmlsoap.org/ws/2005/05/identity/
claims/surname
surname
String
http://schemas.xmlsoap.org/ws/2005/05/identity/
claims/emailaddress
mail
String
http://schemas.microsoft.com/ws/2008/06/identity/
claims/primarygroupsid
uid
String
X.500 Attributes
X.500 Attribute
Maps to this AWS context key Type
2.5.4.3
commonName
String
2.5.4.4
surname
String
2.4.5.42
givenName
String
2.5.4.45
x500UniqueIdentifier
String
0.9.2342.19200300100.1.1
uid
String
0.9.2342.19200300100.1.3
mail
String
0.9.2342.19200300.100.1.45
organizationStatus
String
Enabling SAML 2.0 Federated Users to Access the AWS
Management Console
You can use a role to configure your SAML 2.0-compliant IdP and AWS to permit your federated users
to access the AWS Management Console. The role grants the user permissions to carry out tasks in the
console. If instead you want to give SAML federated users other ways to access AWS, see one of these
topics:
• AWS CLI: Switching to an IAM Role (AWS Command Line Interface) (p. 173)
• Tools for Windows PowerShell: Switching to an IAM Role (Tools for Windows PowerShell) (p. 174)
• AWS API : Switching to an IAM Role (API) (p. 176)
Overview
The following diagram illustrates the flow for SAML-enabled single sign-on.
129
AWS Identity and Access Management User Guide
Identity Providers and Federation
Note
This specific use of SAML differs from the more general one illustrated at About SAML 2.0based Federation (p. 112) because this workflow opens the AWS Management Console on
behalf of the user. This requires the use of the AWS SSO endpoint instead of directly calling
the AssumeRoleWithSAML API. The endpoint calls the API for the user and returns a URL that
automatically redirects the user's browser to the AWS Management Console.
The diagram illustrates the following steps:
1. The user browses to your organization's portal and selects the option to go to the AWS Management
Console. In your organization, the portal is typically a function of your identity provider (IdP) that
handles the exchange of trust between your organization and AWS. For example, in Active Directory
Federation Services, the portal URL is: https://ADFSServiceName/adfs/ls/IdpInitiatedSignOn.aspx
2. The portal verifies the user's identity in your organization.
3. The portal generates a SAML authentication response that includes assertions that identify the user
and include attributes about the user. You can also configure your IdP to include a SAML assertion
attribute called SessionDuration that specifies how long the console session is valid. The portal sends
this response to the client browser.
4. The client browser is redirected to the AWS single sign-on endpoint and posts the SAML assertion.
5. The endpoint requests temporary security credentials on behalf of the user and creates a console signin URL that uses those credentials.
6. AWS sends the sign-in URL back to the client as a redirect.
7. The client browser is redirected to the AWS Management Console. If the SAML authentication
response includes attributes that map to multiple IAM roles, the user is first prompted to select the
role to use for access to the console.
From the user's perspective, the process happens transparently: The user starts at your organization's
internal portal and ends up at the AWS Management Console, without ever having to supply any AWS
credentials.
Consult the following sections for an overview of how to configure this behavior along with links to
detailed steps.
Configure your network as a SAML provider for AWS
Inside your organization's network, you configure your identity store (such as Windows Active Directory)
to work with a SAML-based identity provider (IdP) like Windows Active Directory Federation Services,
Shibboleth, etc. Using your IdP, you generate a metadata document that describes your organization as
130
AWS Identity and Access Management User Guide
Identity Providers and Federation
an identity provider and includes authentication keys. You also configure your organization's portal to
route user requests for the AWS Management Console to the AWS SAML endpoint for authentication
using SAML assertions. How you configure your IdP to produce the metadata.xml file depends on your
IdP. Refer to your IdP's documentation for instructions, or see Integrating Third-Party SAML Solution
Providers with AWS (p. 124) for links to the web documentation for many of the SAML providers
supported.
Create a SAML provider in IAM
Next, you sign in to the AWS Management Console and go to the IAM console. There you create a new
SAML provider, which is an entity in IAM that holds information about your organization's identity
provider. As part of this process, you upload the metadata document produced by the IdP software in
your organization in the previous section. For details, see Creating SAML Identity Providers (p. 121).
Configure permissions in AWS for your federated users
The next step is to create an IAM role that establishes a trust relationship between IAM and your
organization's IdP that identifies your IdP as a principal (trusted entity) for purposes of federation. The
role also defines what users authenticated by your organization's IdP are allowed to do in AWS. You can
use the IAM console to create this role. When you create the trust policy that indicates who can assume
the role, you specify the SAML provider that you created earlier in IAM along with one or more SAML
attributes that a user must match to be allowed to assume the role. For example, you can specify that
only users whose SAML eduPersonOrgDN value is ExampleOrg are allowed to sign in. The role wizard
automatically adds a condition to test the saml:aud attribute to make sure that the role is assumed only
for sign-in to the AWS Management Console. The trust policy for the role might look like this:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Federated": "arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:saml-provider/
ExampleOrgSSOProvider"},
"Action": "sts:AssumeRoleWithSAML",
"Condition": {"StringEquals": {
"saml:edupersonorgdn": "ExampleOrg",
"saml:aud": "https://signin.www.amazonaws.cn/saml"
}}
}]
}
For the access policy (p. 222) in the role, you specify permissions as you would for any role, user, or
group. For example, if users from your organization are allowed to administer Amazon EC2 instances,
you explicitly allow Amazon EC2 actions in the access policy. You can do this by assigning a managed
policy (p. 250), such as the Amazon EC2 Full Access managed policy.
For details about creating a role for a SAML IdP, see Creating a Role for SAML 2.0 Federation
(Console) (p. 162).
Finish configuring the SAML IdP and create assertions for the SAML authentication response
After you create the role, inform your SAML IdP about AWS as a service provider by installing the samlmetadata.xml file found at https://signin.www.amazonaws.cn/static/saml-metadata.xml. How you
install that file depends on your IdP. Some providers give you the option to type the URL, whereupon
the IdP gets and installs the file for you. Others require you to download the file from the URL and then
provide it as a local file. Refer to your IdP documentation for details, or see Integrating Third-Party SAML
Solution Providers with AWS (p. 124) for links to the web documentation for many of the supported
SAML providers.
You also configure the information that you want the IdP to pass as SAML attributes to AWS as part
of the authentication response. Most of this information appears in AWS as condition context keys
that you can evaluate in your policies to ensure that only authorized users in the right contexts are
131
AWS Identity and Access Management User Guide
Identity Providers and Federation
granted permissions to access your AWS resources. You can specify time windows that restrict when the
console may be used and the maximum time (up to 12 hours) that users can access the console before
having to refresh their credentials. For details, see Configuring SAML Assertions for the Authentication
Response (p. 125).
Creating a URL that Enables Federated Users to Access the AWS
Management Console (Custom Federation Broker)
You can write and run code to create a URL that lets users who sign in to your organization's network
securely access the AWS Management Console. The URL includes a sign-in token that you get from AWS
and that authenticates the user to AWS.
Note
If your organization uses an identity provider (IdP) that is compatible with SAML, such as
Microsoft's Active Directory Federation Services or open-source Shibboleth, you can set up
access to the AWS Management Console without writing code. For details, see Enabling SAML
2.0 Federated Users to Access the AWS Management Console (p. 129).
To enable your organization's users to access the AWS Management Console, you can create a custom
"identity broker" that performs the following steps:
1. Verify that the user is authenticated by your local identity system.
2. Call the AWS Security Token Service (AWS STS) AssumeRole (recommended) or GetFederationToken
APIs to obtain temporary security credentials for the user. The credentials are associated with a role
with permissions that control what the user can do. These credentials have a maximum duration as
specified in the DurationSeconds parameter of the AssumeRole or GetFederationToken API call used
to generate them.
Important
If you use the AssumeRole API, you must call it as an IAM user with long-term credentials.
The call to the federation endpoint in step 3 works only if the temporary credentials are
requested by an IAM user with long-term credentials. If the temporary credentials are
requested by an IAM assumed-role user with a different set of temporary credentials, then
the call to the federation endpoint fails.
3. Call the AWS federation endpoint and supply the temporary security credentials to request a sign-in
token.
• If you used one of the AssumeRole* APIs to get the temporary security credentials, then this request
to the AWS federation endpoint can include the HTTP parameter SessionDuration to specify how
long the federated consoled session is valid, up to a maximum of 12 hours.
• If you instead used the GetFederationToken API to get the credentials, then you don't need the
SessionDuration HTTP parameter because the temporary credentials are already valid for up to 36
hours and specify the maximum length of the federated console session.
4. Construct a URL for the console that includes the token.
5. Give the URL to the user or invoke the URL on the user's behalf.
The URL that the federation endpoint provides is valid for 15 minutes after it is created. The temporary
security credentials associated with the URL are valid for the duration you specified when you created
them, starting from the time they were created.
Important
Keep in mind that the URL grants access to your AWS resources through the AWS Management
Console to the extent that you have enabled permissions in the associated temporary security
credentials. For this reason, you should treat the URL as a secret. We recommend returning the
URL through a secure redirect, for example, by using a 302 HTTP response status code over an
SSL connection. For more information about the 302 HTTP response status code, go to RFC
2616, section 10.3.3.
132
AWS Identity and Access Management User Guide
Identity Providers and Federation
To view a sample application that shows you how you can implement a single sign-on solution, go to
AWS Management Console federation proxy sample use case in the AWS Sample Code & Libraries.
To complete these tasks, you can use the HTTPS Query API for AWS Identity and Access Management
(IAM) and the AWS Security Token Service (AWS STS). Or, you can use programming languages, such
as Java, Ruby, or C#, along with the appropriate AWS SDK. Each of these methods is described in the
following sections.
Topics
• Example Code Using IAM Query APIs (p. 133)
• Example Code Using Python (p. 135)
• Example Code Using Java (p. 136)
• Example Showing How to Construct the URL (Ruby) (p. 138)
Example Code Using IAM Query APIs
You can construct a URL that gives your federated users direct access to the AWS Management Console.
This task uses the IAM and AWS STS HTTPS Query API. For more information about making query
requests, see Making Query Requests.
Note
The following procedure contains examples of text strings. To enhance readability, line breaks
have been added to some of the longer examples. When you create these strings for your own
use, you should omit any line breaks.
To give a federated user access to your resources from the AWS Management Console
1.
Authenticate the user in your identity and authorization system.
2.
Obtain temporary security credentials for the user. The temporary credentials consist of an access
key ID, a secret access key, and a security token. For more information about creating temporary
credentials, see Temporary Security Credentials (p. 193).
To get temporary credentials, you call either the AWS STS AssumeRole API (recommended) or
the GetFederationToken API. For more information about the differences between these APIs, see
Understanding the API Options for Securely Delegating Access to Your AWS Account in the AWS
Security Blog.
Important
• When you create temporary security credentials, you must specify the permissions
the credentials grants to the user who holds them. For any of the APIs that begin
with AssumeRole*, you use an IAM role to assign permissions. For the other APIs, the
mechanism varies with the API. For more details, see Controlling Permissions for
Temporary Security Credentials (p. 207).
• If you use the AssumeRole API, you must call it as an IAM user with long-term credentials.
The call to the federation endpoint in step 3 works only if the temporary credentials are
requested by an IAM user with long-term credentials. If the temporary credentials are
requested by an IAM assumed-role user with a different set of temporary credentials,
then the call to the federation endpoint fails.
3.
After you obtain the temporary security credentials, build them into a JSON "session" string to
exchange them for a sign-in token. The following example shows how to encode the credentials. You
replace the placeholder text with the appropriate values from the credentials that you receive in the
previous step.
{"sessionId":"*** temporary access key ID ***",
"sessionKey":"*** temporary secret access key ***",
133
AWS Identity and Access Management User Guide
Identity Providers and Federation
"sessionToken":"*** security token ***"}
4.
URL encode the session string from the previous step. Because the information that you are
encoding is sensitive, we recommend that you avoid using a web service for this encoding. Instead,
use a locally installed function or feature in your development toolkit to securely encode this
information, such as the urllib.quote_plus function in Python, the URLEncoder.encode function in
Java, or the CGI.escape function in Ruby, as shown in the examples later in this topic.
5.
Send your request to the AWS federation endpoint at the following address:
https://signin.aws.amazon.com/federation
The request must include the Action and Session parameters, and (optionally) if you used
AssumeRole, a SessionDuration HTTP parameter as shown in the following example.
Action = getSigninToken
SessionDuration = time in seconds
Session = *** the URL encoded JSON string created in steps 3 & 4 ***
The SessionDuration parameter specifies the number of seconds that the credentials for the
console session are valid. This is separate from the duration of the temporary credentials. You can
specify a SessionDuration maximum value of 43200 (12 hours). If the parameter is missing, then
the session defaults to the duration of the credentials you retrieved from AWS STS in step 2 (which
defaults to one hour). See the documentation for the AssumeRole API for details about how to
specify duration using the DurationSeconds parameter. The ability to create a console session that
is longer than one hour is intrinsic to the getSigninToken action of the federation endpoint. You
cannot use the IAM or STS APIs to get credentials that are valid for longer than one hour (3600
seconds).
Note
You do not need the SessionDuration HTTP parameter if you got the temporary credentials
with GetFederationToken, because the console session can be as long as the temporary
credentials are valid (up to 36 hours).
When you enable console sessions with an extended duration the risk of compromise of the
credentials rises. To help you mitigate this risk, you can immediately disable the active console
sessions for any role by choosing Revoke Sessions on the Role Summary page in the IAM console.
For more information, see Revoking IAM Role Temporary Security Credentials (p. 182).
The following is an example of what your request might look like. The lines are wrapped here for
readability, but you should submit it as a one-line string.
https://signin.aws.amazon.com/federation
?Action=getSigninToken
&SessionDuration=43200
&Session=%7B%22sessionId%22%3A+%22ASIAJUMHIZPTOKTBMK5A%22%2C+%22sessionKey%22
%3A+%22LSD7LWI%2FL%2FN%2BgYpan5QFz0XUpc8s7HYjRsgcsrsm%22%2C+%22sessionToken%2
2%3A+%22FQoDYXdzEBQaDLbj3VWv2u50NN%2F3yyLSASwYtWhPnGPMNmzZFfZsL0Qd3vtYHw5A5dW
AjOsrkdPkghomIe3mJip5%2F0djDBbo7SmO%2FENDEiCdpsQKodTpleKA8xQq0CwFg6a69xdEBQT8
FipATnLbKoyS4b%2FebhnsTUjZZQWp0wXXqFF7gSm%2FMe2tXe0jzsdP0O12obez9lijPSdF1k2b5
PfGhiuyAR9aD5%2BubM0pY86fKex1qsytjvyTbZ9nXe6DvxVDcnCOhOGETJ7XFkSFdH0v%2FYR25C
UAhJ3nXIkIbG7Ucv9cOEpCf%2Fg23ijRgILIBQ%3D%3D%22%7D
The response from the federation endpoint is a JSON document with an SigninToken value. It will
look similar to the following example.
{"SigninToken":"*** the SigninToken string ***"}
134
AWS Identity and Access Management User Guide
Identity Providers and Federation
6.
Finally, create the URL that your federated users can use to access the AWS Management Console.
The URL is the same federation URL endpoint that you used in Step 5 (p. 134), plus the following
parameters:
?Action = login
&Issuer = *** the form-urlencoded URL for your internal sign-in page ***
&Destination = *** the form-urlencoded URL to the desired AWS console page ***
&SigninToken = *** the value of SigninToken received in the previous step ***
The following example shows what the final URL might look like. The URL is valid for 15 minutes
from the time it is created. The temporary security credentials and console session embedded within
the URL are valid for the duration you specify in the SessionDuration parameter when you initially
request them.
https://signin.aws.amazon.com/federation
?Action=login
&Issuer=https%3A%2F%2Fexample.com
&Destination=https%3A%2F%2Fconsole.www.amazonaws.cn%2Fs
&SigninToken=VCQgs5qZZt3Q6fn8Tr5EXAMPLEmLnwB7JjUc-SHwnUUWabcRdnWsi4DBn-dvC
CZ85wrD0nmldUcZEXAMPLE-vXYH4Q__mleuF_W2BE5HYexbe9y4Of-kje53SsjNNecATfjIzpW1
WibbnH6YcYRiBoffZBGExbEXAMPLE5aiKX4THWjQKC6gg6alHu6JFrnOJoK3dtP6I9a6hi6yPgm
iOkPZMmNGmhsvVxetKzr8mx3pxhHbMEXAMPLETv1pij0rok3IyCR2YVcIjqwfWv32HU2Xlj471u
3fU6uOfUComeKiqTGX974xzJOZbdmX_t_lLrhEXAMPLEDDIisSnyHGw2xaZZqudm4mo2uTDk9Pv
9l5K0ZCqIgEXAMPLEcA6tgLPykEWGUyH6BdSC6166n4M4JkXIQgac7_7821YqixsNxZ6rsrpzwf
nQoS14O7R0eJCCJ684EXAMPLEZRdBNnuLbUYpz2Iw3vIN0tQgOujwnwydPscM9F7foaEK3jwMkg
Apeb1-6L_OB12MZhuFxx55555EXAMPLEhyETEd4ZulKPdXHkgl6T9ZkIlHz2Uy1RUTUhhUxNtSQ
nWc5xkbBoEcXqpoSIeK7yhje9Vzhd61AEXAMPLElbWeouACEMG6-Vd3dAgFYd6i5FYoyFrZLWvm
0LSG7RyYKeYN5VIzUk3YWQpyjP0RiT5KUrsUi-NEXAMPLExMOMdoODBEgKQsk-iu2ozh6r8bxwC
RNhujg
Example Code Using Python
The following example shows how to use Python to programmatically construct a URL that gives
federated users direct access to the AWS Management Console. The example uses the AWS SDK for
Python (Boto).
The code uses the AssumeRole API to obtain temporary security credentials.
import urllib, json
import requests # 'pip install requests'
from boto.sts import STSConnection # AWS SDK for Python (Boto) 'pip install boto'
# Step 1: Authenticate user in your own identity system.
# Step 2: Using the access keys for an IAM user in your AWS account,
# call "AssumeRole" to get temporary access keys for the federated user
# Note: Calls to AWS STS AssumeRole must be signed using the access key ID
# and secret access key of an IAM user or using existing temporary credentials.
# The credentials can be in EC2 instance metadata, in environment variables,
# or in a configuration file, and will be discovered automatically by the
# STSConnection() function. For more information, see the Python SDK docs:
# http://boto.readthedocs.org/en/latest/boto_config_tut.html
sts_connection = STSConnection()
assumed_role_object = sts_connection.assume_role(
role_arn="arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/ROLE-NAME",
role_session_name="AssumeRoleSession"
)
135
AWS Identity and Access Management User Guide
Identity Providers and Federation
# Step 3: Format resulting temporary credentials into JSON
json_string_with_temp_credentials = '{'
json_string_with_temp_credentials += '"sessionId":"' +
assumed_role_object.credentials.access_key + '",'
json_string_with_temp_credentials += '"sessionKey":"' +
assumed_role_object.credentials.secret_key + '",'
json_string_with_temp_credentials += '"sessionToken":"' +
assumed_role_object.credentials.session_token + '"'
json_string_with_temp_credentials += '}'
# Step 4. Make request to AWS federation endpoint to get sign-in token. Construct the
parameter string with
# the sign-in action request, a 12-hour session duration, and the JSON document with
temporary credentials
# as parameters.
request_parameters = "?Action=getSigninToken"
request_parameters += "&SessionDuration=43200"
request_parameters += "&Session=" + urllib.quote_plus(json_string_with_temp_credentials)
request_url = "https://signin.aws.amazon.com/federation" + request_parameters
r = requests.get(request_url)
# Returns a JSON document with a single element named SigninToken.
signin_token = json.loads(r.text)
# Step 5: Create URL where users can use the sign-in token to sign in to
# the console. This URL must be used within 15 minutes after the
# sign-in token was issued.
request_parameters = "?Action=login"
request_parameters += "&Issuer=Example.org"
request_parameters += "&Destination=" + urllib.quote_plus("https://
console.aws.amazon.com/")
request_parameters += "&SigninToken=" + signin_token["SigninToken"]
request_url = "https://signin.aws.amazon.com/federation" + request_parameters
# Send final URL to stdout
print request_url
Example Code Using Java
The following example shows how to use Java to programmatically construct a URL that gives federated
users direct access to the AWS Management Console. The following code snippet uses the AWS SDK for
Java.
import java.net.URLEncoder;
import java.net.URL;
import java.net.URLConnection;
import java.io.BufferedReader;
import java.io.InputStreamReader;
// Available at http://www.json.org/java/index.html
import org.json.JSONObject;
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceClient;
import com.amazonaws.services.securitytoken.model.Credentials;
import com.amazonaws.services.securitytoken.model.GetFederationTokenRequest;
import com.amazonaws.services.securitytoken.model.GetFederationTokenResult;
/* Calls to AWS STS APIs must be signed using the access key ID
and secret access key of an IAM user or using existing temporary
credentials. The credentials should not be embedded in code. For
this example, the code looks for the credentials in a
standard configuration file.
*/
AWSCredentials credentials =
136
AWS Identity and Access Management User Guide
Identity Providers and Federation
new PropertiesCredentials(
AwsConsoleApp.class.getResourceAsStream("AwsCredentials.properties"));
AWSSecurityTokenServiceClient stsClient =
new AWSSecurityTokenServiceClient(credentials);
GetFederationTokenRequest getFederationTokenRequest =
new GetFederationTokenRequest();
getFederationTokenRequest.setDurationSeconds(3600);
getFederationTokenRequest.setName("UserName");
// A sample policy for accessing Amazon Simple Notification Service (Amazon SNS) in the
console.
String policy = "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"sns:*\"," +
"\"Effect\":\"Allow\",\"Resource\":\"*\"}]}";
getFederationTokenRequest.setPolicy(policy);
GetFederationTokenResult federationTokenResult =
stsClient.getFederationToken(getFederationTokenRequest);
Credentials federatedCredentials = federationTokenResult.getCredentials();
//
//
//
//
//
The issuer parameter specifies your internal sign-in
page, for example https://mysignin.internal.mycompany.com/.
The console parameter specifies the URL to the destination console of the
AWS Management Console. This example goes to Amazon SNS.
The signin parameter is the URL to send the request to.
String issuerURL = "https://mysignin.internal.mycompany.com/";
String consoleURL = "https://console.aws.amazon.com/sns";
String signInURL = "https://signin.aws.amazon.com/federation";
// Create the sign-in token using temporary credentials,
// including the access key ID, secret access key, and security token.
String sessionJson = String.format(
"{\"%1$s\":\"%2$s\",\"%3$s\":\"%4$s\",\"%5$s\":\"%6$s\"}",
"sessionId", federatedCredentials.getAccessKeyId(),
"sessionKey", federatedCredentials.getSecretAccessKey(),
"sessionToken", federatedCredentials.getSessionToken());
// Construct the sign-in request with the request sign-in token action, a
// 12-hour console session duration, and the JSON document with temporary
// credentials as parameters.
String getSigninTokenURL = signInURL +
"?Action=getSigninToken" +
"&SessionDuration=43200" +
"&SessionType=json&Session=" +
URLEncoder.encode(sessionJson,"UTF-8");
URL url = new URL(getSigninTokenURL);
// Send the request to the AWS federation endpoint to get the sign-in token
URLConnection conn = url.openConnection ();
BufferedReader bufferReader = new BufferedReader(new
InputStreamReader(conn.getInputStream()));
String returnContent = bufferReader.readLine();
String signinToken = new JSONObject(returnContent).getString("SigninToken");
String signinTokenParameter = "&SigninToken=" + URLEncoder.encode(signinToken,"UTF-8");
// The issuer parameter is optional, but recommended. Use it to direct users
137
AWS Identity and Access Management User Guide
Identity Providers and Federation
// to your sign-in page when their session expires.
String issuerParameter = "&Issuer=" + URLEncoder.encode(issuerURL, "UTF-8");
// Finally, present the completed URL for the AWS console session to the user
String destinationParameter = "&Destination=" + URLEncoder.encode(consoleURL,"UTF-8");
String loginURL = signInURL + "?Action=login" +
signinTokenParameter + issuerParameter + destinationParameter;
Example Showing How to Construct the URL (Ruby)
The following example shows how to use Ruby to programmatically construct a URL that gives federated
users direct access to the AWS Management Console. This code snippet uses the AWS SDK for Ruby.
require
require
require
require
require
'rubygems'
'json'
'open-uri'
'cgi'
'aws-sdk'
# Create a new STS instance
#
# Note: Calls to AWS STS APIs must be signed using an access key ID
# and secret access key. The credentials can be in EC2 instance metadata
# or in environment variables and will be automatically discovered by
# the default credentials provider in the AWS Ruby SDK.
sts = Aws::STS::Client.new()
#
#
#
#
The following call creates a temporary session that returns
temporary security credentials and a session token.
The policy grants permissions to work
in the AWS SNS console.
session = sts.get_federation_token({
duration_seconds: 3600,
name: "UserName",
policy: "{\"Version\":\"2012-10-17\",\"Statement\":{\"Effect\":\"Allow\",\"Action\":
\"sns:*\",\"Resource\":\"*\"}}",
})
# The issuer value is the URL where users are directed (such as
# to your internal sign-in page) when their session expires.
#
# The console value specifies the URL to the destination console.
# This example goes to the Amazon SNS console.
#
# The sign-in value is the URL of the AWS STS federation endpoint.
issuer_url = "https://mysignin.internal.mycompany.com/"
console_url = "https://console.aws.amazon.com/sns"
signin_url = "https://signin.aws.amazon.com/federation"
# Create a block of JSON that contains the temporary credentials
# (including the access key ID, secret access key, and session token).
session_json = {
:sessionId => session.credentials[:access_key_id],
:sessionKey => session.credentials[:secret_access_key],
:sessionToken => session.credentials[:session_token]
}.to_json
#
#
#
#
Call the federation endpoint, passing the parameters
created earlier and the session information as a JSON block.
The request returns a sign-in token that's valid for 15 minutes.
Signing in to the console with the token creates a session
138
AWS Identity and Access Management User Guide
Service-Linked Roles
# that is valid for 12 hours.
get_signin_token_url = signin_url +
"?Action=getSigninToken" +
"&SessionDuration=43200" +
"&SessionType=json&Session=" +
CGI.escape(session_json)
returned_content = URI.parse(get_signin_token_url).read
# Extract the sign-in token from the information returned
# by the federation endpoint.
signin_token = JSON.parse(returned_content)['SigninToken']
signin_token_param = "&SigninToken=" + CGI.escape(signin_token)
# Create the URL to give to the user, which includes the
# sign-in token and the URL of the console to open.
# The "issuer" parameter is optional but recommended.
issuer_param = "&Issuer=" + CGI.escape(issuer_url)
destination_param = "&Destination=" + CGI.escape(console_url)
login_url = signin_url + "?Action=login" + signin_token_param +
issuer_param + destination_param
Using Service-Linked Roles
A service-linked role is a unique type of IAM role that is linked directly to an AWS service. Servicelinked roles are predefined by the service and include all the permissions that the service requires to call
other AWS services on your behalf. The linked service also defines how you create, modify, and delete a
service-linked role. A service might automatically create or delete the role. It might allow you to create,
modify, or delete the role as part of a wizard or process in the service. Or it might require that you use
IAM to create or delete the role. Regardless of the method, service-linked roles make setting up a service
easier because you don’t have to manually add the necessary permissions.
The linked service defines the permissions of its service-linked roles, and unless defined otherwise, only
that service can assume the roles. The defined permissions include the trust policy and the permissions
policy, and that permissions policy cannot be attached to any other IAM entity.
You can delete the roles only after first deleting their related resources. This protects your resources
because you can't inadvertently remove permission to access the resources.
For information about which services support using service-linked roles, see AWS Services That Work
with IAM (p. 363) and look for the services that have Yes in the Service-Linked Role column. Choose a
Yes with a link to view the service-linked role documentation for that service.
Service-Linked Role Permissions
You must configure permissions to allow an IAM entity (such as a user, group, or role) to create or edit
the description of a service-linked role.
To allow an IAM entity to create a specific service-linked role
Add the following statement to the permissions policy for the IAM entity that needs to create the
service-linked role:
{
"Effect": "Allow",
"Action": [
"iam:CreateServiceLinkedRole",
"iam:PutRolePolicy"
],
"Resource": "arn:aws:iam::*:role/aws-service-role/SERVICE-NAMEURL.amazonaws.com/SERVICE-LINKED-ROLE-NAME-PREFIX*",
139
AWS Identity and Access Management User Guide
Service-Linked Roles
}
"Condition": {"StringLike": {"iam:AWSServiceName": "SERVICE-NAME-URL.amazonaws.com"}}
To allow an IAM entity to create any service-linked role
Add the following statement to the permissions policy for the IAM entity that needs to create a servicelinked role:
{
}
"Effect": "Allow",
"Action": [
"iam:CreateServiceLinkedRole",
"iam:PutRolePolicy"
],
"Resource": "*"
To allow an IAM entity to edit the description of service-linked roles
Add the following statement to the permissions policy for the IAM entity that needs to edit the
description of a service-linked role:
{
}
"Effect": "Allow",
"Action": [
"iam:UpdateRoleDescription"
],
"Resource": "*"
To allow an IAM entity to delete a specific service-linked role
Add the following statement to the permissions policy for the IAM entity that needs to delete the
service-linked role:
{
"Effect": "Allow",
"Action": [
"iam:DeleteServiceLinkedRole",
"iam:GetServiceLinkedRoleDeletionStatus"
],
"Resource": "arn:aws:iam::*:role/aws-service-role/SERVICE-NAMEURL.amazonaws.com/SERVICE-LINKED-ROLE-NAME-PREFIX*",
"Condition": {"StringLike": {"iam:AWSServiceName": "SERVICE-NAME-URL.amazonaws.com"}}
}
To allow an IAM entity to delete any specific service-linked role
Add the following statement to the permissions policy for the IAM entity that needs to delete a servicelinked role:
{
}
"Effect": "Allow",
"Action": [
"iam:DeleteServiceLinkedRole",
"iam:GetServiceLinkedRoleDeletionStatus"
],
"Resource": "*"
Alternatively, you can use an AWS managed policy to provide full access to the service.
140
AWS Identity and Access Management User Guide
Service-Linked Roles
Creating a Service-Linked Role
The method that you use to create a service-linked role depends on the service. In some cases, you don't
need to manually create a service-linked role. For example, when you complete a specific action (such as
creating a resource) in the service, the service might create the service-linked role for you. Or if you were
using a service before it began supporting service-linked roles, then the service might have automatically
created the role in your account. To learn more, see A New Role Appeared in My IAM Account (p. 347).
In other cases, the service might support creating a service-linked role manually using the service
console, API, or CLI. For information about which services support using service-linked roles, see AWS
Services That Work with IAM (p. 363) and look for the services that have Yes in the Service-Linked Role
column. To learn whether the service supports creating the service-linked role, choose the Yes link to
view the service-linked role documentation for that service.
If the service does not support creating the role, then you can use IAM to create the service-linked role.
Important
Service-linked roles count toward your IAM roles in an AWS account limit, but if you have
reached your limit, you can still create service-linked roles in your account. Only service-linked
roles can exceed the limit.
Creating a Service-Linked Role (IAM Console)
Before you create a service-linked role in IAM, find out whether the linked service automatically creates
service-linked roles and whether you can t create the role from the service's console, API, or CLI.
To create a service-linked role (console)
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
3.
In the navigation pane of the IAM console, choose Roles. Then choose Create role.
Choose the AWS Service role type, and then choose the service that you want to allow to assume
this role.
Choose the use case for your service. If the specified service has only one use case, it is selected for
you. Use cases are defined by the service to include the trust policy required by the service. Then
choose Next: Permissions.
Choose one or more permissions policies to attach to the role. Depending on the use case that you
selected, the service might do any of the following:
4.
5.
• Define the permissions used by the role
• Allow you to choose from a limited set of permissions
• Allow you to choose from any permissions
• Allow you to select no policies at this time, create the policies later, and then attach them to the
role.
Select the box next to the policy that assigns the permissions that you want the role to have, and
then choose Next: Review.
Note
6.
The permissions that you specify are available to any entity that uses the role. By default, a
role has no permissions.
For Role name, the degree of role name customization is defined by the service. If the service
defines the role's name, then this option is not editable. In other cases, the service might define a
prefix for the role and allow you to type an optional suffix.
If possible, type a role name suffix to add to the default name. This suffix helps you identify
the purpose of this role. Role names must be unique within your AWS account. They are not
141
AWS Identity and Access Management User Guide
Service-Linked Roles
distinguished by case. For example, you cannot create roles named both <service-linked-rolename>_SAMPLE and <service-linked-role-name>_sample. Because various entities might reference
the role, you cannot edit the name of the role after it has been created.
7.
(Optional) For Role description, edit the description for the new service-linked role.
8.
Review the role and then choose Create role.
Creating a Service-Linked Role (IAM CLI)
Before creating a service-linked role in IAM, find out whether the linked service automatically creates
service-linked roles and whether you can create the role from the service's CLI. If the service CLI is not
supported, you can use IAM commands to create a service-linked role with the trust policy and inline
policies that the service needs to assume the role.
To create a service-linked role (IAM CLI)
Use the following command:
$ aws iam create-service-linked-role --aws-service-name SERVICE-NAME-URL.amazonaws.com
Creating a Service-Linked Role (IAM API)
Before creating a service-linked role in IAM, find out whether the linked service automatically creates
service-linked roles and whether you can create the role from the service's API. If the service API is not
supported, you can use the IAM API to create a service-linked role with the trust policy and inline policies
that the service needs to assume the role.
To create a service-linked role (API)
Use the CreateServiceLinkedRole API call. In the request, specify a service name of
SERVICE_NAME_URL.amazonaws.com.
For example, to create the Lex Bots service-linked role, use lex.amazonaws.com.
Editing a Service-Linked Role
The method that you use to edit a service-linked role depends on the service. Some services might allow
you to edit the permissions for a service-linked role from the service console, API, or CLI. However, after
you create a service-linked role, you cannot change the name of the role because various entities might
reference the role. You can edit the description of any role from the IAM console, API, or CLI.
For information about which services support using service-linked roles, see AWS Services That Work
with IAM (p. 363) and look for the services that have Yes in the Service-Linked Role column. To learn
whether the service supports editing the service-linked role, choose the Yes link to view the servicelinked role documentation for that service.
Editing a Service-Linked Role Description (IAM Console)
You can use the IAM console to edit the description of a service-linked role.
To edit the description of a service-linked role (console)
1.
In the navigation pane of the IAM console, choose Roles.
2.
Choose the name of the role to modify.
3.
To the far right of Role description, choose Edit.
4.
Type a new description in the box and choose Save.
142
AWS Identity and Access Management User Guide
Service-Linked Roles
Editing a Service-Linked Role Description (IAM CLI)
You can use IAM commands from the AWS Command Line Interface to edit the description of a servicelinked role.
To change the description of a service-linked role (IAM CLI)
1.
(Optional) To view the current description for a role, use the following commands:
$ aws iam get-role --role-name ROLE-NAME
Use the role name, not the ARN, to refer to roles with the CLI commands. For example, if a role has
the following ARN: arn:aws-cn:iam::123456789012:role/myrole, you refer to the role as myrole.
2.
To update a service-linked role's description, use the following command:
$ aws iam update-role-description --role-name ROLE-NAME --description OPTIONALDESCRIPTION
Editing a Service-Linked Role Description (IAM API)
You can use the IAM API to edit the description of a service-linked role.
To change the description of a service-linked role (API)
1.
(Optional) To view the current description for a role, use the following command, and specify the
name of the role:
IAM API: GetRole
2.
To update a role's description, use the following command, and specify the name (and optional
description) of the role:
IAM API: UpdateRoleDescription
Deleting a Service-Linked Role
The method that you use to create a service-linked role depends on the service. In some cases, you don't
need to manually delete a service-linked role. For example, when you complete a specific action (such as
removing a resource) in the service, the service might delete the service-linked role for you.
In other cases, the service might support deleting a service-linked role manually from the service
console, API, or CLI.
For information about which services support using service-linked roles, see AWS Services That Work
with IAM (p. 363) and look for the services that have Yes in the Service-Linked Role column. To learn
whether the service supports deleting the service-linked role, choose the Yes link to view the servicelinked role documentation for that service.
If the service does not support deleting the role, then you can delete the service-linked role from the IAM
console, API, or CLI. If you no longer need to use a feature or service that requires a service-linked role,
we recommend that you delete that role. That way you don’t have an unused entity that is not actively
monitored or maintained. However, you must clean up your service-linked role before you can delete it.
Cleaning Up a Service-Linked Role
Before you can use IAM to delete a service-linked role, you must first confirm that the role has no active
sessions and remove any resources used by the role.
143
AWS Identity and Access Management User Guide
Service-Linked Roles
To check whether the service-linked role has an active session in the IAM console
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane of the IAM console, choose Roles. Then choose the name (not the check box)
of the service-linked role.
3.
On the Summary page for the selected role, choose the Access Advisor tab.
4.
On the Access Advisor tab, review recent activity for the service-linked role.
Note
If you are unsure whether the service is using the service-linked role, you can try to delete
the role. If the service is using the role, then the deletion fails and you can view the regions
where the role is being used. If the role is being used, then you must wait for the session to
end before you can delete the role. You cannot revoke the session for a service-linked role.
To remove resources used by a service-linked role
For information about which services support using service-linked roles, see AWS Services That Work
with IAM (p. 363) and look for the services that have Yes in the Service-Linked Role column. To learn
whether the service supports deleting the service-linked role, choose the Yes link to view the servicelinked role documentation for that service. See the documentation for that service to learn how to
remove resources used by your service-linked role.
Deleting a Service-Linked Role (IAM Console)
You can use the IAM console to delete a service-linked role.
To delete a service-linked role (console)
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane of the IAM console, choose Roles. Then select the check box next to the role
name that you want to delete, not the name or row itself.
3.
For Role actions at the top of the page, choose Delete role.
4.
In the confirmation dialog box, review the service last accessed data, which shows when each of the
selected roles last accessed an AWS service. This helps you to confirm whether the role is currently
active. If you want to proceed, choose Yes, Delete to submit the service-linked role for deletion.
5.
Watch the IAM console notifications to monitor the progress of the service-linked role deletion.
Because the IAM service-linked role deletion is asynchronous, after you submit the role for deletion,
the deletion task can succeed or fail.
• If the task succeeds, then the role is removed from the list and a notification of success appears at
the top of the page.
• If the task fails, you can choose View details or View Resources from the notifications to learn
why the deletion failed. If the deletion fails because the role is using the service's resources, then
the notification includes a list of resources, if the service returns that information. You can then
clean up the resources (p. 143) and submit the deletion again.
Note
You might have to repeat this process several times, depending on the information that
the service returns. For example, your service-linked role might use six resources and your
service might return information about five of them. If you clean up the five resources
and submit the role for deletion again, the deletion fails and the service reports the one
remaining resource. A service might return all of the resources, a few of them, or it might
not report any resources.
144
AWS Identity and Access Management User Guide
Service-Linked Roles
• If the task fails and the notification does not include a list of resources, then the service might not
return that information. To learn how to clean up the resources for that service, see AWS Services
That Work with IAM (p. 363). Find your service in the table, and choose the Yes link to view the
service-linked role documentation for that service.
Deleting a Service-Linked Role (IAM CLI)
You can use IAM commands from the AWS Command Line Interface to delete a service-linked role.
To delete a service-linked role (IAM CLI)
1.
If you don't know the name of the service-linked role that you want to delete, type the following
command to list the roles and their Amazon Resource Names (ARNs) in your account:
$ aws iam get-role --role-name role-name
Use the role name, not the ARN, to refer to roles with the CLI commands. For example, if a role has
the following ARN: arn:aws-cn:iam::123456789012:role/myrole, you refer to the role as myrole.
2.
Because a service-linked role cannot be deleted if it is being used or has associated resources, you
must submit a deletion request. That request can be denied if these conditions are not met. You
must capture the deletion-task-id from the response to check the status of the deletion task. Type
the following command to submit a service-linked role deletion request:
$ aws iam delete-service-linked-role --role-name role-name
3.
Type the following command to check the status of the deletion task:
$ aws iam get-service-linked-role-deletion-status --deletion-task-id deletion-task-id
The status of the deletion task can be NOT_STARTED, IN_PROGRESS, SUCCEEDED, or FAILED. If the
deletion fails, the call returns the reason that it failed so that you can troubleshoot. If the deletion
fails because the role is using the service's resources, then the notification includes a list of
resources, if the service returns that information. You can then clean up the resources (p. 143) and
submit the deletion again.
Note
You might have to repeat this process several times, depending on the information that
the service returns. For example, your service-linked role might use six resources and your
service might return information about five of them. If you clean up the five resources
and submit the role for deletion again, the deletion fails and the service reports the one
remaining resource. A service might return all of the resources, a few of them, or it might
not report any resources. To learn how to clean up the resources for a service that does not
report any resources, see AWS Services That Work with IAM (p. 363). Find your service in
the table, and choose the Yes link to view the service-linked role documentation for that
service.
Deleting a Service-Linked Role (IAM API)
You can use the IAM API to delete a service-linked role.
To delete a service-linked role (API)
1.
To submit a deletion request for a service-linked roll, call DeleteServiceLinkedRole. In the request,
specify a role name.
145
AWS Identity and Access Management User Guide
Creating Roles
Because a service-linked role cannot be deleted if it is being used or has associated resources, you
must submit a deletion request. That request can be denied if these conditions are not met. You
must capture the DeletionTaskId from the response to check the status of the deletion task.
2.
To check the status of the deletion, call GetServiceLinkedRoleDeletionStatus. In the request, specify
the DeletionTaskId.
The status of the deletion task can be NOT_STARTED, IN_PROGRESS, SUCCEEDED, or FAILED. If the
deletion fails, the call returns the reason that it failed so that you can troubleshoot. If the deletion
fails because the role is using the service's resources, then the notification includes a list of
resources, if the service returns that information. You can then clean up the resources (p. 143) and
submit the deletion again.
Note
You might have to repeat this process several times, depending on the information that
the service returns. For example, your service-linked role might use six resources and your
service might return information about five of them. If you clean up the five resources
and submit the role for deletion again, the deletion fails and the service reports the one
remaining resource. A service might return all of the resources, a few of them, or it might
not report any resources. To learn how to clean up the resources for a service that does not
report any resources, see AWS Services That Work with IAM (p. 363). Find your service in
the table, and choose the Yes link to view the service-linked role documentation for that
service.
Creating IAM Roles
To create a role, you can use the AWS Management Console, the AWS CLI, the Tools for Windows
PowerShell, or the IAM API.
If you use the AWS Management Console, a wizard guides you through the steps for creating a role. The
wizard has slightly different steps depending on whether you're creating a role for an AWS service, for an
AWS account, or for a federated user.
Topics
• Creating a Role to Delegate Permissions to an IAM User (p. 146)
• Creating a Role to Delegate Permissions to an AWS Service (p. 153)
• Creating a Role for a Third-Party Identity Provider (Federation) (p. 156)
• Examples of Policies for Delegating Access (p. 164)
Creating a Role to Delegate Permissions to an IAM User
You can use IAM roles to delegate access to your AWS resources. With IAM roles, you can establish trust
relationships between your trusting account and other AWS trusted accounts. The trusting account owns
the resource to be accessed and the trusted account contains the users who need access to the resource.
After you create the trust relationship, an IAM user or an application from the trusted account can
use the AWS Security Token Service (AWS STS) AssumeRole API action. This action provides temporary
security credentials that enable access to AWS resources in your account.
The accounts can both be controlled by you, or the account with the users can be controlled by a third
party. If the other account with the users is in an AWS account that you do not control, then you can use
the externalID attribute and a unique identifier supplied by the third-party account. This helps ensure
that access occurs only in the correct contexts. For more information, see How to Use an External ID
When Granting Access to Your AWS Resources to a Third Party (p. 149).
146
AWS Identity and Access Management User Guide
Creating Roles
For information about how to use roles to delegate permissions, see Roles Terms and Concepts (p. 98).
For information about using a service role to allow services to access resources in your account, see
Creating a Role to Delegate Permissions to an AWS Service (p. 153).
Creating an IAM Role (Console)
You can use the AWS Management Console to create a role that an IAM user can assume. For example,
imagine that your organization has multiple AWS accounts to isolate a development environment from a
production environment. To view a high-level description of the steps necessary to set up and use a role
that allows users in the development account to access resources in the production account, see Example
Scenario Using Separate Development and Production Accounts (p. 101).
To create a role (console)
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane of the console, choose Roles and then choose Create role.
3.
Choose the Another AWS account role type.
4.
For Account ID, type the AWS account ID to which you want to grant access to your resources.
The administrator of the specified account can grant permission to assume this role to any IAM user
in that account. To do this, the administrator attaches a policy to the user or a group that grants
permission for the sts:AssumeRole action. That policy must specify the role's ARN as the Resource.
5.
If you are granting permissions to users from an account that you do not control, select Require
external ID. The external ID can be any word or number that is agreed upon between you and
the administrator of the third party account. This option automatically adds a condition to
the trust policy that allows the user to assume the role only if the request includes the correct
sts:ExternalID. For more information, see How to Use an External ID When Granting Access to Your
AWS Resources to a Third Party (p. 149).
Important
Choosing this option restricts access to the role only through the AWS CLI, Tools for
Windows PowerShell, or the AWS API. This is because you cannot use the AWS console to
switch to a role that has an externalID condition in its trust policy. However, you can create
this kind of access programmatically by writing a script or an application using the relevant
SDK. For more information and a sample script, see How to Enable Cross-Account Access to
the AWS Management Console in the AWS Security Blog.
6.
Choose Next: Permissions.
7.
Choose one or more permissions policies to attach to the role. Choose policies that specify
what actions can be done on specific resources (similar to setting permissions for IAM groups).
For information about using policies to manage permissions, see Overview of AWS IAM
Permissions (p. 222).
The permissions that you specify are available to any entity that uses the role. By default, a role has
no permissions.
Select the box next to the policy that assigns the permissions that you want the users to have. Then
choose Next: Review. If you prefer, you can select no policies at this time, create the policies later,
and then attach them to the role.
8.
For Role name, type a name for your role. This name helps you identify the purpose of this role.
Role names must be unique within your AWS account. They are not distinguished by case. For
example, you cannot create roles named both PRODROLE and prodrole. Because various entities
might reference the role, you cannot edit the name of the role after it has been created.
9.
(Optional) For Role description, type a description for the new role.
10. Review the role and then choose Create role.
147
AWS Identity and Access Management User Guide
Creating Roles
Important
Remember that this is only the first half of the configuration required. You must also
give individual users in the trusted account permissions to switch to the role. For more
information about this step, see Granting a User Permissions to Switch Roles (p. 167).
After you create the role and grant it permissions to perform AWS tasks or access AWS resources,
the user can assume the role. For more information, see Switching to a Role (AWS Management
Console) (p. 171).
Creating an IAM Role (AWS CLI)
Creating a role from the AWS CLI involves multiple steps. When you use the console to create a role,
many of the steps are done for you, but with the AWS CLI you must explicitly perform each step yourself.
You must create the policy and assign a permissions policy to the role.
To create a role for cross-account access (AWS CLI)
• Create a role: aws iam create-role
• Attach a managed access policy to the role: aws iam attach-role-policy
-orCreate an inline access policy for the role: aws iam put-role-policy
The following example shows both steps in a simple environment. The example assumes that you are
using a client computer running Windows, and have already configured your command line interface
with your account credentials and region. For more information, see Configuring the AWS Command Line
Interface.
The sample trust policy referenced in the first command contains the following JSON code to enable
users in the account 123456789012 to assume the role.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Principal": { "AWS": "arn:aws-cn:iam::123456789012:root" },
"Action": "sts:AssumeRole"
}
Important
If your Principal element contains an ARN that points to a specific IAM role or user, then that
ARN is transformed to a unique principal ID when the policy is saved. This helps mitigate the
risk of someone escalating their privileges by removing and recreating the role or user. You
don't normally see this ID in the console, because there is also a reverse transformation back
to the ARN when the trust policy is displayed. However, if you delete the role or user, then the
relationship is broken. The policy no longer applies, even if you recreate the user or role because
it does not match the principal ID stored in the trust policy. When this happens, the principal ID
shows up in the console because AWS can no longer map it back to an ARN. The result is that if
you delete and recreate a user or role referenced in a trust policy's Principal element, you must
edit the role to replace the ARN. The user or role is transformed into the new principal ID when
you save the policy.
The managed policy referenced in the second command is assumed to already exists in IAM. This policy
allows the user who assumes the role to perform only the ListBucket action on an S3 bucket named
example_bucket. The policy looks like this:
148
AWS Identity and Access Management User Guide
Creating Roles
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws-cn:s3:::example_bucket"
}
The commands to run are the following:
# Create the role and attach the trust policy that allows users in an account to switch to
the role.
$ aws iam create-role --role-name Test-UserAccess-Role --assume-role-policy-document
file://C:\policies\trustpolicyforacct123456789012.json
# Attach the permissions policy (in this example a managed policy) to the role to specify
what it is allowed to do.
$ aws iam attach-role-policy --role-name Test-UserAccess-Role --policy-arn arn:awscn:iam::123456789012:role/PolicyForRole
Important
Remember that this is only the first half of the configuration required. You must also give
individual users in the trusted account permissions to switch to the role. For more information
about this step, see Granting a User Permissions to Switch Roles (p. 167).
After you create the role and grant it permissions to perform AWS tasks or access AWS resources, the
user can switch to the role. For more information, see Switching to an IAM Role (AWS Command Line
Interface) (p. 173).
Creating an IAM Role (AWS API)
You can use API calls to create a role that an IAM user can switch to.
To create a role in code (API)
• Create a role: CreateRole
For the role's trust policy, you can specify a file location.
• Attach a managed access policy to the role: AttachRolePolicy
-orCreate an inline access policy for the role: PutRolePolicy
Important
Remember that this is only the first half of the configuration required. You must also give
individual users in the trusted account permissions to switch to the role. For more information
about this step, see Granting a User Permissions to Switch Roles (p. 167).
After you create the role and grant it permissions to perform AWS tasks or access AWS resources, the
user can switch to the role. For more information, see Switching to an IAM Role (API) (p. 176).
How to Use an External ID When Granting Access to Your AWS Resources to a
Third Party
At times, you need to give a third party access to your AWS resources (delegate access). One important
aspect of this scenario is the External ID, an optional piece of information that you can use in an IAM role
trust policy to designate who can assume the role.
149
AWS Identity and Access Management User Guide
Creating Roles
For example, let's say that you decide to hire a third-party company called Example Corp to monitor
your AWS account and help optimize costs. In order to track your daily spending, Example Corp needs to
access your AWS resources. Example Corp also monitors many other AWS accounts for other customers.
Although you could give Example Corp access to an IAM user and its long-term credentials in your AWS
account, you should choose instead to go with the highly recommended best practice of using an IAM
role. An IAM role provides a mechanism to allow a third party to access your AWS resources without
needing to share long-term credentials (for example, an IAM user's access key).
You can use an IAM role to establish a trusted relationship between your AWS account and the account
belonging to Example Corp. After this relationship is established, one of Example Corp's IAM users or
applications in the trusted AWS account can call the AWS STS AssumeRole API to obtain temporary
security credentials that can then be used to access AWS resources in your account.
Note
For more information about the AssumeRole and other AWS APIs that you can call to obtain
temporary security credentials, see Requesting Temporary Security Credentials (p. 195).
Here's a more detailed breakdown of this scenario:
1. You hire Example Corp, so they create a unique customer identifier for you. They give you your unique
customer ID and their AWS account number. You need this information to create an IAM role in the
next step.
Note
Example Corp can use any string value they want for the ExternalId, as long as it is unique for
each customer. It can be a customer account number or even a random string of characters,
as long as no two customers have the same value. It is not intended to be a 'secret'. Example
Corp must provide the ExternalId value to each customer. What is key is that it must be
generated by Example Corp and not their customers.
2. You sign in to AWS and create an IAM role that gives Example Corp access to your resources. Like any
IAM role, the role has two policies, an access policy and a trust policy. The role's trust policy specifies
who can assume the role. In our sample scenario, the policy specifies the AWS account number
of Example Corp as the Principal. This allows identities from that account to assume the role. In
addition, you add an Condition element to the trust policy that tests the ExternalID context key to
ensure that it matches the unique customer ID that Example Corp assigned to you when you hired the
company. For example:
"Principal": {"AWS": "Example Corp's AWS Account ID"},
"Condition": {"StringEquals": {"sts:ExternalId": "Unique ID Assigned by Example
Corp"}}
3. The access policy for the role specifies what the role allows someone to do. For example, you could
specify that the role allows someone to manage only your Amazon EC2 and Amazon RDS resources
but not your IAM users or groups. In our sample scenario, you use the access policy to give Example
Corp read-only access to all of the resources in your account.
4. After you create the role, you provide the Amazon Resource Name (ARN) of the role to Example Corp.
5. When Example Corp needs to access your AWS resources, someone from the company calls the AWS
sts:AssumeRole API. The call includes the ARN of the role to assume and the ExternalID parameter
that corresponds to your customer ID.
All of this results in the request being authorized only if the role ARN and the external ID are correct,
and if the request comes from someone using Example Corp's AWS account. If the request succeeds, it
provides temporary security credentials that Example Corp can use to access the AWS resources that your
role allows.
In other words, when a role policy includes an external ID, anyone who wants to assume the role must
not only be specified as a principal in the role, but must also include the correct external ID.
150
AWS Identity and Access Management User Guide
Creating Roles
Why Do You Need to Use an External ID?
In abstract terms, the external ID allows the user that is assuming the role to assert the circumstances in
which they are operating. It also provides a way for the account owner to permit the role to be assumed
only under specific circumstances. The primary function of the external ID is to address and prevent the
"confused deputy" problem.
The Confused Deputy Problem
To continue the previous example, Example Corp requires access to certain resources in your AWS
account. But in addition to you, Example Corp has other customers and needs a way to access each
customer's AWS resources. Instead of asking its customers for their AWS account access keys, which
are secrets that should never be shared, Example Corp requests a role ARN from each customer. But if
another Example Corp customer were able to guess or obtain your role ARN, that customer could then
use your role ARN to gain access to your AWS resources by way of Example Corp. This form of privilege
escalation is known as the confused deputy problem.
The following diagram illustrates the confused deputy problem.
This diagram assumes the following:
• AWS1 is your AWS account.
• AWS1:ExampleRole is a role in your account. This role's trust policy trusts Example Corp by specifying
Example Corp's AWS account as the one that can assume the role.
Here's what happens:
1. When you start using Example Corp's service, you provide the ARN of AWS1:ExampleRole to Example
Corp.
2. Example Corp uses that role ARN to obtain temporary security credentials to access resources in your
AWS account. In this way, you are trusting Example Corp as a "deputy" that can act on your behalf.
3. Another AWS customer also starts using Example Corp's service, and this customer also provides
the ARN of AWS1:ExampleRole for Example Corp to use. Presumably the other customer learned or
guessed the AWS1:ExampleRole, which isn't a secret.
4. When the other customer asks Example Corp to access AWS resources in (what it claims to be) its
account, Example Corp uses AWS1:ExampleRole to access resources in your account
This is how the other customer could gain unauthorized access to your resources. Because this other
customer was able to trick Example Corp into unwittingly acting on your resources, Example Corp is now
a "confused deputy."
How Does the External ID Prevent the Confused Deputy Problem?
You address the confused deputy problem by including the ExternalID condition check in the role's
trust policy. The "deputy" company inserts a unique external ID value for each customer into the request
for AWS credentials. The external ID is a customer ID value that must be unique among Example Corp's
customers and is out of the control of Example Corp's customers. This is why you get it from Example
151
AWS Identity and Access Management User Guide
Creating Roles
Corp and you don't come up with it on your own. This helps prevent one customer from successfully
impersonating another customer. Example Corp always inserts the customer's assigned external ID, so
you should never see a request coming from Example Corp with any external ID except your own.
In our scenario, imagine Example Corp's unique identifier for you is "12345," and its identifier for the
other customer is "67890." These identifiers are simplified for this scenario. Generally, these identifiers
are GUIDs. Assuming that these identifiers are unique among Example Corp's customers, they are
sensible values to use for the external ID.
Example Corp gives the external ID value of "12345" to you. You must then add a Condition element to
the role's trust policy that requires the sts:ExternalID value to be 12345, like this:
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {"AWS": "Example Corp's AWS Account ID"},
"Condition": {"StringEquals": {"sts:ExternalId": "12345"}}
}
The Condition element in this policy allows Example Corp to assume the role only when the AssumeRole
API call includes the external ID value of "12345". Example Corp makes sure that whenever it assumes a
role on behalf of a customer, it always includes that customer's external ID value in the AssumeRole call.
As shown in the following diagram, even if another customer supplies Example Corp with your ARN, it
cannot control the external ID that Example Corp includes in its request to AWS. This helps prevent an
unauthorized customer from gaining access to your resources:
1. As before, when you start using Example Corp's service, you provide the ARN of AWS1:ExampleRole
to Example Corp.
2. When Example Corp uses that role ARN to assume the role AWS1:ExampleRole, Example Corp
includes your external ID ("12345") in the AssumeRole API call. The external ID matches the role's trust
policy, so the AssumeRole API call succeeds and Example Corp obtains temporary security credentials
to access resources in your AWS account.
3. Another AWS customer also starts using Example Corp's service, and as before, this customer also
provides the ARN of AWS1:ExampleRole for Example Corp to use.
4. But this time, when Example Corp attempts to assume the role AWS1:ExampleRole, it provides
the external ID associated with the other customer ("67890"), and the other customer has no way
to change this. Example Corp does this because the request to use the role came from the other
customer, so "67890" indicates the circumstance in which Example Corp is acting. Because you
added a condition with your own external ID ("12345") to the trust policy of AWS1:ExampleRole,
the AssumeRole API call fails, and the other customer is prevented from gaining unauthorized access
resources in your account (indicated by the red "X" in the diagram).
The external ID helps prevent any other customer from tricking Example Corp into unwittingly accessing
your resources—it mitigates the confused deputy problem.
152
AWS Identity and Access Management User Guide
Creating Roles
When Should I Use the External ID?
Use an external ID in the following situations:
• If you are an AWS account owner and you have configured a role for a third party that accesses other
AWS accounts in addition to yours, you should ask the third party for an external ID that it includes
when it assumes your role. Then you check for that external ID in your role's trust policy to ensure that
the external party can assume your role only when it is acting on your behalf.
• If you are in the position of assuming roles on behalf of different customers like Example Corp in our
previous scenario, then you should assign a unique external ID to each of your customers and instruct
them to add the external ID to their role's trust policy. You must then ensure that you always include
the correct external ID in your requests to assume roles.
You probably already have a unique identifier for each of your customers, and this unique ID is
sufficient for use as an external ID. The external ID is not a special value that you need to create
explicitly, or track separately, just for this purpose.
You should always specify the external ID in your AssumeRole API calls. In addition when a customer
gives you a role ARN, test whether you can assume the role both with and without the correct external
ID. If you can assume the role without the correct external ID, don't store the customer's role ARN in
your system until your customer has updated the role trust policy to require the correct external ID.
In this way you help your customers to do the right thing, which helps to keep both of you protected
against the confused deputy problem.
Creating a Role to Delegate Permissions to an AWS Service
Many AWS services require that you use roles to control what that service can access. A role that a
service assumes to perform actions on your behalf is called a service role (p. 98). When a role serves
a specialized purpose for a service, it is categorized as a service role for EC2 instances (p. 98) (for
example), or a service-linked role (p. 99). See the AWS documentation for each service to see if it uses
roles and to learn how to assign a role for the service to use.
For information about how roles help you to delegate permissions, see Roles Terms and
Concepts (p. 98).
Creating a Role for an AWS Service (Console)
You can use the AWS Management Console to create a role for a service. Because some services support
more than one service role, see the AWS documentation for your service to see which use case to choose.
You can learn how to assign the necessary trust and permissions policies to the role so that the service
can assume the role on your behalf.
To create a role for an AWS service (console)
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane of the IAM console, choose Roles, and then choose Create role.
3.
Choose the AWS Service role type, and then choose the service that you want to allow to assume
this role.
4.
Choose the use case for your service. If the specified service has only one use case, it is selected for
you. Use cases are defined by the service to include the trust policy that the service requires. Then
choose Next: Permissions.
5.
Choose one or more permissions policies to attach to the role. Depending on the use case that you
selected, the service might do any of the following:
• Define the permissions that the role uses
153
AWS Identity and Access Management User Guide
Creating Roles
• Allow you to choose from a limited set of permissions
• Allow you to choose from any permissions
• Allow you to select no policies at this time, create the policies later, and then attach them to the
role
Select the box next to the policy that assigns the permissions that you want the users to have, and
then choose Next: Review.
Note
The permissions that you specify are available to any entity that uses the role. By default, a
role has no permissions.
6.
For Role name, the degree of role name customization is defined by the service. If the service
defines the role's name, this option is not editable. In other cases, the service might define a prefix
for the role and allow you to type an optional suffix. Some services allow you to specify the entire
name of your role.
If possible, type a role name or role name suffix to help you identify the purpose of this role. Role
names must be unique within your AWS account. They are not distinguished by case. For example,
you cannot create roles named both PRODROLE and prodrole. Because various entities might
reference the role, you cannot edit the name of the role after it has been created.
7.
(Optional) For Role description, type a description for the new role.
8.
Review the role and then choose Create role.
Creating a Role for a Service (AWS CLI)
Creating a role from the AWS CLI involves multiple steps. When you use the console to create a role,
many of the steps are done for you, but with the AWS CLI you must explicitly perform each step yourself.
You must create the policy and assign an access policy to the role. If the service you are working with is
Amazon EC2, then you must also create an instance profile and add the role to it.
To create a role for an AWS service from the AWS CLI, use the following commands:
1.
Create a role: aws iam create-role
2.
Attach a managed access policy to the role: aws iam attach-role-policy
or
Create an inline access policy for the role: aws iam put-role-policy
If you are going to use the role with Amazon EC2 or another AWS service that uses Amazon EC2, you
must store the role in an instance profile. An instance profile is a container for a role that can be attached
to an Amazon EC2 instance when launched. An instance profile can contain only one role, and that limit
cannot be increased. If you create the role using the AWS Management Console, the instance profile
is created for you with the same name as the role. For more information about instance profiles, see
Using Instance Profiles (p. 180). For information about how to launch an EC2 instance with a role, see
Controlling Access to Amazon EC2 Resources in the Amazon EC2 User Guide for Linux Instances.
To create an instance profile and add a role to it from the AWS CLI, use the following commands:
• Create an instance profile: aws iam create-instance-profile
• Add the role to the instance profile: aws iam add-role-to-instance-profile
154
AWS Identity and Access Management User Guide
Creating Roles
The following example shows all four steps. The example assumes that you are running on a client
computer running Windows and have already configured your command line interface with your account
credentials and region. For more information, see Configuring the AWS Command Line Interface.
The sample trust policy referenced in the first command contains the following JSON code to enable the
Amazon EC2 service to assume the role.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Principal": {"Service": "ec2.amazonaws.com"},
"Action": "sts:AssumeRole"
}
The sample access policy referenced in the second command allows the role to perform only the
ListBucket action on an S3 bucket named example_bucket.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws-cn:s3:::example_bucket"
}
The AWS CLI commands to run for this example are the following:
# Create the role and attach the trust policy that enables EC2 to assume this role.
$ aws iam create-role --role-name Test-Role-for-EC2 --assume-role-policy-document file://
trustpolicyforec2.json
# Embed the permissions policy (in this example an inline policy) to the role to specify
what it is allowed to do.
$ aws iam put-role-policy --role-name Test-Role-for-EC2 --policy-name Permissions-PolicyFor-Ec2 --policy-document file://permissionspolicyforec2.json
# Create the instance profile required by EC2 to contain the role
$ aws iam create-instance-profile --instance-profile-name EC2-ListBucket-S3
# Finally, add the role to the instance profile
$ aws iam add-role-to-instance-profile --instance-profile-name EC2-ListBucket-S3 --rolename Test-Role-for-EC2
When you launch the EC2 instance, specify the instance profile name in the Configure Instance Details
page if you use the AWS console. If you use the aws ec2 run-instances CLI command, specify the -iam-instance-profile parameter.
Creating a Role for a Service (AWS API)
You can use the AWS API to create a service role.
To create a service role in code (API)
Use the following commands:
• Create a role: CreateRole
For the role's trust policy, you can specify a file location.
155
AWS Identity and Access Management User Guide
Creating Roles
• Attach a managed access policy to the role: AttachRolePolicy
or
Create an inline access policy for the role: PutRolePolicy
If you are going to use the role with Amazon EC2 or another AWS service that uses Amazon EC2, you
must store the role in an instance profile. An instance profile is a container for a role. Each instance
profile can contain only one role, and that limit cannot be increased. If you create the role in the AWS
Management Console, the instance profile is created for you with the same name as the role. For more
information about instance profiles, see Using Instance Profiles (p. 180). For information about how
to launch an Amazon EC2 instance with a role, see Controlling Access to Amazon EC2 Resources in the
Amazon EC2 User Guide for Linux Instances.
• Create an instance profile: CreateInstanceProfile
• Add the role to the instance profile: AddRoleToInstanceProfile
Creating a Role for a Third-Party Identity Provider (Federation)
Identity federation provides access to AWS resources to users by means of a third-party identity
provider (IdP). To set up identity federation, you configure the provider and then create an IAM role that
determines what permissions a federated user will have. For more information about federation and
identity providers, see Identity Providers and Federation (p. 105).
Creating a Role for Federated Users (AWS Management Console)
The steps for creating a role for federated users depends on your choice of third-party providers:
• To create a role for users federated with a Web Identity or OpenID Connect (OIDC) IdP, see Creating a
Role for Web Identity or OpenID Connect Federation (Console) (p. 158).
• To create a role for users federated with a SAML 2.0 IdP, see Creating a Role for SAML 2.0 Federation
(Console) (p. 162).
Creating a Role for Federated Access (AWS Command Line Interface)
The steps to create a role for the supported identity providers (OIDC or SAML) from the AWS CLI are
identical; —the difference is in the contents of the trust policy that you create in the prerequisite steps.
Begin by following the steps in the Prerequisites section for the type of provider you are using:
• For an OIDC provider, follow the steps in Prerequisites for an OIDC provider (p. 158).
• For a SAML provider, follow the steps in Prerequisites for a SAML provider (p. 162).
Creating a role from the AWS CLI involves multiple steps. When you use the console to create a role,
many of the steps are done for you, but with the CLI you must explicitly perform each step yourself. You
must create the trust policy first, create the role, and then assign an access policy to the role.
To create a role using the AWS CLI
Use the following commands:
• To create a role: aws iam create-role
• To attach an access policy to the role:
aws iam attach-role-policy to attach an existing managed policy
156
AWS Identity and Access Management User Guide
Creating Roles
or
aws iam put-role-policy to create an inline policy
The following example shows all the steps in a simple environment. The example assumes that you are
running the AWS CLI on a computer running Windows, and have already configured the AWS CLI with
your credentials. For more information, see Configuring the AWS Command Line Interface.
The commands to run are the following:
# Create the role and attach the trust policy that enables users in an account to assume
the role.
$ aws iam create-role --role-name Test-CrossAcct-Role --assume-role-policy-document file://
trustpolicyforcognitofederation.json
# Attach the permissions policy to the role to specify what it is allowed to do.
aws iam put-role-policy --role-name Test-CrossAcct-Role --policy-name Perms-Policy-ForCognitoFederation --policy-document file://permspolicyforcognitofederation.json
Creating a Role for Federated Access (Tools for Windows PowerShell)
The steps to create a role for the supported identity providers (OIDC or SAML) is identical; the difference
is in the contents of the trust policy you create in the prerequisite steps. Follow the steps in the
Prerequisites section for the type of provider you are using:
• For an OIDC provider, follow the steps in Prerequisites for an OIDC provider (p. 158).
• For a SAML provider, follow the steps in Prerequisites for a SAML provider (p. 162).
Creating a role using the Tools for Windows PowerShell involves multiple steps. When you use the
console to create a role, many of the steps are done for you, but with the Tools for Windows PowerShell
you must explicitly perform each step yourself. You must create the trust policy first, create the role, and
then assign an access policy to the role.
To create a role using the Tools for Windows PowerShell
Use the following commands:
• To create a role: New-IAMRole
• To attach an access policy to the role:
Register-IAMRolePolicy to attach an existing managed policy
-orWrite-IAMRolePolicy to create an inline policy
The following example shows all of the steps in a simple environment. The example assumes that you
have already configured the Tools for Windows PowerShell with your credentials. For more information,
see Using AWS Credentials.
The commands to run are the following:
# Create the role and attach the trust policy that enables users in an account to assume
the role.
PS C:\> New-IAMRole -RoleName Test-Federation-Role -AssumeRolePolicyDocument (Get-Content Raw C:\policies\trustpolicyforfederation.json)
157
AWS Identity and Access Management User Guide
Creating Roles
# Attach a managed permissions policy to the role to specify what it is allowed to do.
PS C:\> Register-IAMRolePolicy -RoleName Test-Federation-Role -PolicyArn arn:awscn:iam::aws:policy/PolicyForFederation
Creating a Role for Federated Access (IAM API)
Before you create the role, you must follow the steps in the Prerequisites section for the type of provider
you are using:
• For an OIDC provider, follow the steps in Prerequisites for an OIDC provider (p. 158).
• For a SAML provider, follow the steps in Prerequisites for a SAML provider (p. 162).
To create a role for identity federation using the IAM API
Use the following commands:
• To create a role: CreateRole
• To attach an access policy to the role:
AttachRolePolicy to attach an existing managed policy
or
PutRolePolicy to create an inline policy
Creating a Role for Web Identity or OpenID Connect Federation (Console)
Before you can create a role for web identity federation, you must first complete the following
prerequisite steps.
To prepare to create a role for web identity federation
1.
Begin by signing up as a developer with an IdP (or more than one). You also configure your app with
the provider; when you do, the provider gives you an application or audience ID that's unique to your
app. (Providers use different terminology for this process. This guide uses the term configure for the
process of identifying your app with the provider.) Each provider gives you an app ID that's unique to
that provider, so if you configure the same app with multiple providers, your app will have multiple
app IDs. You can configure multiple apps with each provider. The following external links provide
information about using one of the identity providers:
• Login with Amazon Developer Center
• Add Facebook Login to Your App or Website on the Facebook developers site.
2.
3.
• Using OAuth 2.0 for Login (OpenID Connect) on the Google developers site.
After getting the required information from the identity provider, you can create an identity provider
in IAM. For more information, see Creating OpenID Connect (OIDC) Identity Providers (p. 116).
Prepare the policies for the role that the IdP-authenticated users will assume. As with any role, a role
for the mobile app contains two policies. One is the trust policy that specifies who can assume the
role (the trusted entity or principal). The other policy (the access policy) specifies the actual AWS
actions and resources that the mobile app is allowed or denied access to (similar to user or resource
policies).
For web identity providers, we recommend that you use Amazon Cognito to manage identities. In
that case, the trust policy for the role must include a Statement similar to the following:
{
"Version": "2012-10-17",
158
AWS Identity and Access Management User Guide
Creating Roles
"Statement": {
"Effect": "Allow",
"Principal": {"Federated": "cognito-identity.amazonaws.com"},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {"cognito-identity.amazonaws.com:aud": "us-west-2:12345678-abcdabcd-abcd-123456"},
"ForAnyValue:StringLike": {"cognito-identity.amazonaws.com:amr":
"unauthenticated"}
}
}
}
Replace us-west-2:12345678-abcd-abcd-abcd-123456 with the actual identity pool ID that Amazon
Cognito assigned to you.
If you manually configure a web identity IdP, then the trust policy must grant an Allow effect for the
sts:AssumeRoleWithWebIdentity action. In this role, you use two values that ensure that only your
application can assume the role:
• For the Principal element, use the string {"Federated":providerUrl/providerArn}.
• For some common OpenID Connect (OIDC) IdPs, the providerUrl is the fully qualified URL. The
following are acceptable ways to specify the principal for some common IdPs:
"Principal":{"Federated":"cognito-identity.amazonaws.com"}
"Principal":{"Federated":"www.amazon.com"}
"Principal":{"Federated":"graph.facebook.com"}
"Principal":{"Federated":"accounts.google.com"}
• For other OIDC providers, use the ARN of the OIDC identity provider you created in Step 2, like
the following example:
"Principal":{"Federated":"arn:aws:iam::123456789012:oidc-provider/
server.example.com"}
• In the Condition element, use a StringEquals condition to limit permissions. Test whether the
identity pool ID (for Amazon Cognito) or the app ID (for other providers) matches the app ID that
you got when you configured the app with the IdP. This ensures that the request is coming from
your app. Test the app ID that you have against the following policy variables depending on the
IdP that you are using:
"Condition": {"StringEquals": {"cognito-identity.amazonaws.com:aud": "useast:12345678-ffff-ffff-ffff-123456"}}
"Condition": {"StringEquals": {"www.amazon.com:app_id": "amzn1.applicationoa2-123456"}}
"Condition": {"StringEquals": {"graph.facebook.com:app_id": "111222333444555"}}
"Condition": {"StringEquals": {"accounts.google.com:aud": "66677788899900pro0"}}
For OIDC providers, use the fully qualified URL of the OIDC IdP with the aud context key, like the
following example:
"Condition": {"StringEquals": {"server.example.com:aud": "appid_from_oidc_idp"}}
159
AWS Identity and Access Management User Guide
Creating Roles
Notice that the values for the principal in the role are specific to an IdP. A role can specify only one
principal. Therefore, if the mobile app allows users to sign in from more than one IdP, you must
create a role for each IdP that you want to support.
Note
Because the policy for the trusted entity uses policy variables that represent the IdP and
the app ID, you must set the policy's Version element to 2012-10-17 or a later supported
version.
The following example shows a trust policy for a role designed for a mobile app if the user signs in
from Login with Amazon. In the example, amzn1.application-oa2-123456 represents the app ID
that Amazon assigned when you configured the app using Login with Amazon.
{
"Version": "2012-10-17",
"Id": "RoleForLoginWithAmazon",
"Statement": [{
"Effect": "Allow",
"Principal": {"Federated": "www.amazon.com"},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {"StringEquals": {"www.amazon.com:app_id": "amzn1.applicationoa2-123456"}}
}]
}
The following example shows a policy for a role that the mobile app could assume if the user has
signed in from Facebook. In this example, 111222333444555 represents the app ID assigned by
Facebook.
{
}
"Version": "2012-10-17",
"Id": "RoleForFacebook",
"Statement": [{
"Effect": "Allow",
"Principal": {"Federated": "graph.facebook.com"},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {"StringEquals": {"graph.facebook.com:app_id": "111222333444555"}}
}]
The following example shows a policy for a role that the mobile app could assume if the user has
signed in from Google. In this example, 666777888999000 represents the app ID assigned by Google.
{
}
"Version": "2012-10-17",
"Id": "RoleForGoogle",
"Statement": [{
"Effect": "Allow",
"Principal": {"Federated": "accounts.google.com"},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {"StringEquals": {"accounts.google.com:aud": "666777888999000"}}
}]
The following example shows a policy for a role that the mobile app could assume if the application
is using Amazon Cognito. In this example, us-east:12345678-ffff-ffff-ffff-123456 represents
the identity pool ID assigned by Amazon Cognito.
160
AWS Identity and Access Management User Guide
Creating Roles
{
"Version": "2012-10-17",
"Id": "RoleForCognito",
"Statement": [{
"Effect": "Allow",
"Principal": {"Federated": "cognito-identity.amazonaws.com"},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {"StringEquals": {"cognito-identity.amazonaws.com:aud": "useast:12345678-ffff-ffff-ffff-123456"}}
}]
}
After you complete the prerequisites, you can create the role itself. The following procedure
describes how to create the role for web identity/OIDC federation in the AWS Management Console.
To create a role using the AWS CLI, Tools for Windows PowerShell, or AWS API, see the procedures at
Creating a Role for a Third-Party Identity Provider (Federation) (p. 156).
To create an IAM role for web identity federation
If you are using Amazon Cognito, you should use the Amazon Cognito console to set up the roles.
Otherwise, use the IAM console to create a role for web identity federation.
1.
Open the IAM console at https://console.amazonaws.cn/iam/.
2.
In the navigation pane, click Roles and then click Create role.
3.
Choose the Web identity role type.
4.
In the Identity provider list, select the identity provider that you're creating the role for:
• If you're creating a role for an individual web identity provider, select Login with Amazon,
Facebook, or Google.
Note
You must create a separate role for each identity provider that you want to support.
• Select Amazon Cognito if you're creating a role for Amazon Cognito.
Note
You only need to manually create a role for use with Amazon Cognito when you are
working on an advanced scenario. Otherwise, Amazon Cognito can create roles for you for
standard scenarios. For more information about Amazon Cognito, see Amazon Cognito
Identity in the AWS Mobile SDK for iOS Developer Guide and Amazon Cognito Identity in
the AWS Mobile SDK for Android Developer Guide.
5.
Type the identifier for your application. The name identifier setting changes depending on which
provider you select:
• If you're creating a role for Login with Amazon, type the app ID into the Application ID box.
• If you're creating a role for Amazon Cognito, type the ID of the identity pool that you have created
for your Amazon Cognito applications into the Identity Pool ID box.
• If you're creating a role for Facebook, type the app ID into the Application ID box.
• If you're creating a role for Amazon Cognito, type the audience name into the Audience box.
6.
(Optional) Click Add condition (optional) to create additional conditions that must be met before
users of your application can use the permissions that the role grants. For example, you can add a
condition that grants access to AWS resources only for a specific IAM user ID.
7.
Review your web identity information and then choose Next: Permissions.
8.
Choose one or more permissions policies to attach to the role. By default, roles have no permissions.
Select the box next to the policy that assigns the permissions that you want the web identity users
to have. Then choose Next: Review.
161
AWS Identity and Access Management User Guide
Creating Roles
9.
For Role name, type a role name that helps you identify the purpose of this role. Role names must
be unique within your AWS account. They are not distinguished by case. For example, you cannot
create roles named both PRODROLE and prodrole. Because various entities might reference the role,
you cannot edit the name of the role after it has been created.
10. (Optional) For Role description, type a description for the new role.
11. Review the role and then choose Create role.
Creating a Role for SAML 2.0 Federation (Console)
With identity federation, you can provide access to AWS resources for users who sign in from a thirdparty identity provider (IdP). To configure identity federation, you configure the provider and then you
create an IAM role that determines what permissions a federated user has. For more information about
federation and identity providers, see Identity Providers and Federation (p. 105).
Before you can create a role for SAML 2.0 federation, you must first complete the following prerequisite
steps:
To prepare to create a role for SAML 2.0 federation
1.
Before you create a role for SAML-based federation, you must create a SAML provider in IAM. For
more information, see Creating SAML Identity Providers (p. 121).
2.
Prepare the policies for the role that the SAML 2.0–authenticated users will assume. As with any
role, a role for the SAML federation contains two policies. One is the trust policy that specifies who
can assume the role (the trusted entity, or principal). The other policy (the access policy) specifies
the actual AWS actions and resources that the federated user is allowed or denied access to (similar
to a user or resource policy).
For SAML 2.0 providers, the policy must include a Statement element similar to the following:
The trust policy must grant an Allow effect for the sts:AssumeRoleWithSAML action. In this role, you
use two values that ensure that the role can be assumed only by your application:
• For the Principal element, use the string {"Federated":ARNofIdentityProvider}. Replace
ARNofIdentityProvider with the ARN of the SAML identity provider (p. 112) that you created in
Step 1.
• For the Condition element, use a StringEquals condition to test that the saml:aud attribute from
the SAML response matches the SAML federation endpoint for AWS.
Note
Because the policy for the trusted entity uses policy variables that represent values in
the SAML response, you must set the policy's Version element to 2012-10-17 or a later
supported version.
The following example shows a trust policy for a role designed for a SAML federated user:
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRoleWithSAML",
"Principal": {"Federated": "arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:samlprovider/PROVIDER-NAME"},
"Condition": {"StringEquals": {"SAML:aud": "https://signin.www.amazonaws.cn/saml"}}
}
}
162
AWS Identity and Access Management User Guide
Creating Roles
Replace the principal ARN with the actual ARN for the SAML provider that you created in IAM. It will
have your own account ID and the actual provider name.
After completing the prerequisite steps, you can create the role itself.
To create a role for SAML-based federation
1.
Make sure you've created a SAML provider in IAM, as described in About SAML 2.0-based
Federation (p. 112).
2.
In the navigation pane of the console, choose Roles and then choose Create role.
3.
Choose the SAML 2.0 federation role type.
4.
In the SAML Provider list, select the provider that you're creating the role for.
5.
Choose the SAML 2.0 access level method. Choose Allow programmatic access only to create a
role that can be assumed programmatically from the AWS API. Then choose Allow programmatic
and AWS Management Console access to create a role that can be assumed programmatically
and from the console. The roles created by both are similar, but the role that can also be assumed
from the console includes a trust policy with a particular condition. That condition explicitly ensures
that the SAML audience (SAML:aud attribute) is set to the AWS sign-in endpoint for SAML (https://
signin.aws.amazon.com/saml).
6.
If you're creating a role for programmatic access, select an attribute from the Attribute list. Then in
the Value box, type a value to include in the role. This restricts role access to users from the identity
provider whose SAML authentication response (assertion) includes the attributes that you specify.
You must specify at least one attribute to ensure that your role is limited to a subset of users at your
organization.
If you're creating a role for programmatic and console access, the SAML:aud attribute is automatically
added and set to the URL of the AWS SAML endpoint (https://signin.aws.amazon.com/saml).
7.
To add more attribute-related conditions to the trust policy, choose Add condition (optional), select
the additional condition, and specify a value.
Note
The list displays the most commonly used SAML attributes. IAM supports additional
attributes that you can use to create conditions. (For a list of the supported attributes, see
Available Keys for SAML Federation in the topic IAM Policy Elements Reference (p. 374).) If
you need a condition for a supported SAML attribute that's not in the list, you can manually
add that condition by editing the trust policy after you create the role.
8.
Review your SAML 2.0 trust information and then choose Next: Permissions.
9.
Choose one or more permissions policies to attach to the role. By default, roles have no permissions.
Select the box next to the policy that assigns the permissions that you want the federated users to
have. Then choose Next: Review.
10. For Role name, type a role name that helps you identify the purpose of this role. Role names must
be unique within your AWS account. They are not distinguished by case. For example, you cannot
create roles named both PRODROLE and prodrole. Because various entities might reference the role,
you cannot edit the name of the role after it has been created.
11. (Optional) For Role description, type a description for the new role.
12. Review the role and then choose Create role.
After you create the role, you complete the SAML trust by configuring your identity provider software
with information about AWS and the roles that you want your federated users to use. This is referred to
as configuring relying party trust between your IdP and AWS. For more information, see Configuring your
SAML 2.0 IdP with Relying Party Trust and Adding Claims (p. 123).
163
AWS Identity and Access Management User Guide
Creating Roles
Examples of Policies for Delegating Access
The following examples show how you can allow or grant an AWSaccount access to the resources in
another AWS account.
Topics
• Using Roles to Delegate Access to Another AWS Account's Resources (p. 164)
• Using a Policy to Delegate Access To Services (p. 164)
• Using a Resource-based Policy to Delegate Access to an Amazon S3 Bucket in Another
Account (p. 165)
• Using a Resource-based Policy to Delegate Access to an Amazon SQS Queue in Another
Account (p. 165)
• Cannot Delegate Access When the Account is Denied Access (p. 166)
Using Roles to Delegate Access to Another AWS Account's Resources
For a complete walkthrough that shows how to use IAM roles to grant users in one account access to
AWS resources that are in another account, see Tutorial: Delegate Access Across AWS Accounts Using IAM
Roles (p. 24).
Important
If your Principal element in a role trust policy contains an ARN that points to a specific IAM
role or user, then that ARN is transformed to a unique principal ID when the policy is saved.
This helps mitigate the risk of someone escalating their privileges by removing and recreating
the role or user. You don't normally see this ID in the console, because there is also a reverse
transformation back to the ARN when the trust policy is displayed. However, if you delete the
role or user, then the relationship is broken. The policy no longer applies, even if you recreate
the user or role because it does not match the principal ID stored in the trust policy. When this
happens, the principal ID shows up in the console because AWS can no longer map it back to an
ARN. The end result is that if you delete and recreate a user or role referenced in a trust policy's
Principal element, you must edit the role to replace the ARN. It will get transformed into the
new principal ID when you save the policy.
Using a Policy to Delegate Access To Services
The following example shows a policy that can be attached to a role. The policy enables two services,
Amazon EMR and AWS Data Pipeline, to assume the role. The services can then perform any tasks
granted by the permissions policy assigned to the role (not shown). Note that to specify multiple service
principals, you do not specify two Service elements; you can have only one. Instead, you use an array of
multiple service principals as the value of a single Service element.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"elasticmapreduce.amazonaws.com",
"datapipeline.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
164
AWS Identity and Access Management User Guide
Creating Roles
Using a Resource-based Policy to Delegate Access to an Amazon S3 Bucket in
Another Account
In this example, account A uses a resource-based policy (an Amazon S3 bucket policy) to grant account B
full access to account A's S3 bucket. Then account B creates an IAM user policy to delegate that access to
account A's bucket to one of the users in account B.
The S3 bucket policy in account A might look like the following policy. In this example, account A's S3
bucket is named mybucket, and account B's account number is 111122223333. It does not specify any
individual users or groups in account B, only the account itself.
{
}
"Version": "2012-10-17",
"Statement": {
"Sid": "AccountBAccess1",
"Effect": "Allow",
"Principal": {"AWS": "111122223333"},
"Action": "s3:*",
"Resource": [
"arn:aws-cn:s3:::mybucket",
"arn:aws-cn:s3:::mybucket/*"
]
}
Alternatively, account A can use Amazon S3 Access Control Lists (ACLs) to grant account B access to an
S3 bucket or a single object within a bucket. In that case, the only thing that changes is how account A
grants access to account B. Account B still uses a policy to delegate access to an IAM group in account
B, as described in the next part of this example. For more information about controlling access on S3
buckets and objects, go to Access Control in the Amazon Simple Storage Service Developer Guide.
The following policy sample completes the example above and shows the IAM group (or user) policy
that the administrator of account B might create to delegate read access to a group or user in account
B. Even though the policy above grants access to account B, individual groups and users in account B
cannot access the resource until a group or user policy explicitly grants permissions to the resource. The
permissions in this policy can only be a subset of those in the cross-account policy above. Account B
cannot grant more permissions to its groups and users than account A granted to account B in the first
policy. In this policy, the Action element is explicitly defined to allow only List actions, and the Resource
element of this policy matches the Resource for the bucket policy implemented by account A.
To implement this policy account B uses IAM to attach it to the appropriate user (or group) in account B.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "s3:List*",
"Resource": [
"arn:aws-cn:s3:::mybucket",
"arn:aws-cn:s3:::mybucket/*"
]
}
Using a Resource-based Policy to Delegate Access to an Amazon SQS Queue in
Another Account
In the following example, account A has an Amazon SQS queue that uses a resource-based policy
attached to the queue to grant queue access to account B. Then account B uses an IAM group policy to
delegate access to a group in account B.
165
AWS Identity and Access Management User Guide
Creating Roles
The following example queue policy gives account B permission to perform the SendMessage and
ReceiveMessage actions on account A's queue named queue1, but only between noon and 3:00 p.m. on
November 30, 2014. Account B's account number is 1111-2222-3333. Account A uses Amazon SQS to
implement this policy.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Principal": {"AWS": "111122223333"},
"Action": [
"sqs:SendMessage",
"sqs:ReceiveMessage"
],
"Resource": ["arn:aws-cn:sqs:*:123456789012:queue1"],
"Condition": {
"DateGreaterThan": {"aws:CurrentTime": "2014-11-30T12:00Z"},
"DateLessThan": {"aws:CurrentTime": "2014-11-30T15:00Z"}
}
}
Account B's policy for delegating access to a group in account B might look like the following example.
Account B uses IAM to attach this policy to a group (or user).
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sqs:*",
"Resource": "arn:aws-cn:sqs:*:123456789012:queue1"
}
In the preceding IAM user policy example, account B uses a wildcard to grant its user access to all
Amazon SQS actions on account A's queue. But, because account B can delegate access only to the extent
that account B has been granted access, the account B group that has the second policy can access the
queue only between noon and 3:00 p.m. on November 30, 2014, and the user can only perform the
SendMessage and ReceiveMessage actions, as defined in account A's Amazon SQS queue policy.
Cannot Delegate Access When the Account is Denied Access
By default, other AWS accounts and their users cannot access your AWS account resources. But if you use
a policy to explicitly deny an AWS account access to your resources, the deny propagates to the users
under that account whether or not the users have existing policies granting them access. This means that
an AWS account cannot delegate access to another account's resources if the other account has explicitly
denied access to the user's parent account.
For example, account A writes a bucket policy on account A's S3 bucket that explicitly denies account
B access to account A's bucket. But account B writes an IAM user policy that grants a user in account B
access to account A's bucket. The explicit deny applied to account A's S3 bucket propagates to the users
in account B and overrides the IAM user policy granting access to the user in account B. (For detailed
information how permissions are evaluated, see IAM Policy Evaluation Logic (p. 405).)
Account A's bucket policy might look like the following policy. In this example, account A's S3 bucket is
named mybucket, and account B's account number is 1111-2222-3333. Account A uses Amazon S3 to
implement this policy.
{
166
AWS Identity and Access Management User Guide
Using Roles
}
"Version": "2012-10-17",
"Statement": {
"Sid": "AccountBDeny",
"Effect": "Deny",
"Principal": {"AWS": "111122223333"},
"Action": "s3:*",
"Resource": "arn:aws-cn:s3:::mybucket/*"
}
To implement the following IAM user policy, account B uses IAM to attach it to the a user in account B.
{
}
"Version": "2012-10-17",
"Statement":{
"Effect":"Allow",
"Action":"s3:*",
"Resource":"arn:aws-cn:s3:::mybucket/*"
}
Account A's bucket policy explicitly denies account B access to mybucket. Because you only delegate a
subset of permissions that have been granted to you, account B's IAM user policy granting the user in
account B access to account A's bucket has no effect. The user in account B cannot access account A's
bucket.
Using IAM Roles
Before an IAM user, application, or service can use a role that you created, you must grant permissions
to switch to the role. You can use any policy attached to one of an IAM user's groups or to the user itself
to grant the necessary permissions. This section describes how to grant users permission to use a role,
and then how the user can switch to a role using the AWS Management Console, the Tools for Windows
PowerShell, the AWS Command Line Interface (AWS CLI) and the AssumeRole API.
Important
If you create a role programmatically instead of in the IAM console, then you have an option to
add a Path of up to 512 characters in addition to the RoleName, which can be up to 64 characters
long. However, if you intend to use a role with the Switch Role feature in the AWS console, then
the combined Path and RoleName cannot exceed 64 characters.
Topics
• Granting a User Permissions to Switch Roles (p. 167)
• Granting a User Permissions to Pass a Role to an AWS Service (p. 169)
• Switching to a Role (AWS Management Console) (p. 171)
• Switching to an IAM Role (AWS Command Line Interface) (p. 173)
• Switching to an IAM Role (Tools for Windows PowerShell) (p. 174)
• Switching to an IAM Role (API) (p. 176)
• Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances (p. 177)
• Revoking IAM Role Temporary Security Credentials (p. 182)
Granting a User Permissions to Switch Roles
When you create a role for cross-account access (p. 146), you establish trust from the account that
owns the role and the resources (trusting account) to the account that contains the users (trusted
account). To do this, you specify the trusted account number as the Principal in the role's trust policy.
167
AWS Identity and Access Management User Guide
Using Roles
That allows potentially any user in the trusted account to assume the role. To complete the configuration,
the administrator of the trusted account must give specific groups or users in that account permission to
switch to the role.
To grant a user permission to switch to a role, you create a new policy for the user or edit an existing
policy to add the required elements. You can then send the users a link that takes the user to the Switch
Role page with all the details already filled in. Alternatively, you can provide the user with the account
ID number or account alias that contains the role and the role name. The user then goes to the Switch
Role page and adds the details manually. For details on how a user switches roles, see Switching to a
Role (AWS Management Console) (p. 171).
Important
You cannot switch roles in the AWS Management Console to a role that requires an
ExternalID (p. 149) value. You can switch to such a role only by calling the AssumeRole API
that supports the ExternalID parameter.
Notes
• This topic discusses policies for a user, because we are ultimately granting permissions to a
user to accomplish a task. However, it is best practice not to grant permissions directly to an
individual user (p. 36). For easier management, we recommend assigning policies and granting
permissions to IAM groups and then making the users members of the appropriate groups.
• When you switch roles in the AWS Management Console, the console always uses your
original credentials to authorize the switch. This applies whether you sign in as an IAM user,
as a SAML-federated role, or as a web-identity federated role. For example, if you switch to
RoleA, it uses your original user or federated role credentials to determine if you are allowed
to assume RoleA. If you then try to switch to RoleB while you are using RoleA, it still uses your
original user or federated role credentials to authorize your attempt to switch to RoleB, not
the credentials for RoleA.
Creating or Editing the Policy
A policy that grants a user permission to assume a role must include a statement with the Allow effect
on the sts:AssumeRole action and the Amazon Resource Name (ARN) of the role in a Resource element,
as shown in the following example. Users that get the policy (either through group membership or
directly attached) are allowed to switch to the specified role.
Note
Note that if Resource is set to *, the user can assume any role in any account that trusts the
user's account (the role's trust policy specifies the user's account as Principal). As a best
practice, we recommend that you follow the principle of least privilege and specify the complete
ARN for only the role(s) that the user needs.
The following example shows a policy that lets the user assume roles in only one account and
additionally specifies by wildcard (*) that the user can only switch to a role in that account if the role
name begins with the letters "Test" followed by any other combination of characters.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/Test*"
}
Note
The permissions that the role grants to the user do not add to the permissions already granted
to the user. When a user switches to a role, the user temporarily gives up his or her original
168
AWS Identity and Access Management User Guide
Using Roles
permissions in exchange for those granted by the role. When the user exits the role, then the
original user permissions are automatically restored. For example, if the user's permissions allow
working with Amazon EC2 instances, but the role's permissions policy does not grant those
permissions, then while using the role the user cannot work with Amazon EC2 instances in the
console, and temporary credentials obtained via AssumeRole do not work with Amazon EC2
instances programmatically.
Providing Information to the User
After you create a role and grant your user permissions to switch to it, you must provide the user with
the role name and the account ID number or account alias that contains the role. You can make things
easier for your users by sending them a link that is preconfigured with the account ID and role name. You
can see the role link on the final page of the Create Role wizard or in the Role Summary page for any
cross-account enabled role.
Note
If you create the role with the AWS CLI , Tools for Windows PowerShell,or the AWS API, then
you can create the role with a path in addition to a name. If you do so, then you must provide
the complete path and role name to your users to type on the Switch Role page of the AWS
Management Console. For example: division_abc/subdivision_efg/role_XYZ.
Important
If you create the role programmatically instead of in the IAM console, then you have an option
to add a Path of up to 512 characters in addition to the RoleName, which can be up to 64
characters long. However, to use a role with the Switch Role feature in the AWS console, the
combined Path and RoleName cannot exceed 64 characters.
You can also use the following format to manually construct the link. Substitute your account ID or alias
and the role name for the two parameters in the request:
https://signin.aws.amazon.com/switchrole?
account=YourAccountIDorAliasHere&roleName=pathIfAny/YourRoleNameHere
We recommend that you direct your users to the topic Switching to a Role (AWS Management
Console) (p. 171) to step them through the process.
Note
For security purposes, you can use AWS CloudTrail to audit role switching. If CloudTrail is turned
on for the account, IAM logs actions that are performed with the role's temporary security
credentials. For more information, see CloudTrail Event Reference in the AWS CloudTrail User
Guide.
Granting a User Permissions to Pass a Role to an AWS Service
To configure many AWS services, you must pass an IAM role to the service that defines what that service
can do on your behalf. For example, to provide applications running on an Amazon EC2 instance with
AWS credentials, you pass a role to EC2 to use with the instance that provides those credentials. You
define what the credentials allow the applications running on the instance to do by attaching an IAM
policy that grants the required permissions to the role.
To pass a role (and its permissions) to an AWS service, a user must have permissions to pass the role to
the service. This helps administrators ensure that only approved users can configure a service with a role
that grants permissions. To allow a user to pass a role to an AWS service, you must grant the PassRole
permission to the user's IAM user, role, or group.
When a user passes a role ARN as a parameter to any API that uses the role to assign permissions to
the service, the service checks whether that user has the iam:PassRole permission. To limit the user to
passing only approved roles, you can filter the iam:PassRole permission with the Resources element of
the IAM policy statement.
169
AWS Identity and Access Management User Guide
Using Roles
Example 1
Imagine that you want to grant a user the ability to pass any of an approved set of roles to the Amazon
EC2 service upon launching an instance. You need three elements:
• An IAM permissions policy attached to the role that determines what the role can do. Scope
permissions to only the actions that the role needs to perform, and to only the resources that the role
needs for those actions. You can use AWS managed or customer-created IAM permissions policy.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [ "A list of the permissions the role is allowed to use" ],
"Resource": [ "A list of the resources the role is allowed to access" ]
}
• A trust policy for the role that allows the service to assume the role. For example, you could attach
the following trust policy to the role with the UpdateAssumeRolePolicy action. This trust policy allows
Amazon EC2 to use the role and the permissions attached to the role.
{
}
"Version": "2012-10-17",
"Statement": {
"Sid": "TrustPolicyStatementThatAllowsEC2ServiceToAssumeTheAttachedRole",
"Effect": "Allow",
"Principal": { "Service": "ec2.amazonaws.com" },
"Action": "sts:AssumeRole"
}
• An IAM permissions policy attached to the IAM user that allows the user to pass only those policies
that are approved. iam:PassRole usually is accompanied by iam:GetRole so that the user can get the
details of the role to be passed. In this example, the user can pass only roles with names that begin
with EC2-roles-for-XYZ-:
{
}
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"iam:GetRole",
"iam:PassRole"
],
"Resource": "arn:aws-cn:iam::*:role/EC2-roles-for-XYZ-*"
}]
Now the user can start an Amazon EC2 instance with an assigned role. Applications running on the
instance can access temporary credentials for the role through the instance profile metadata. The
permission policies attached to the role determine what the instance can do.
Example 2
Amazon Relational Database Service (Amazon RDS) supports a feature called Enhanced Monitoring. This
feature enables Amazon RDS to monitor a database instance using an agent. It also allows Amazon RDS
to log metrics to Amazon CloudWatch Logs. To enable this feature, you must create a service role to give
Amazon RDS permissions to monitor and write metrics to your logs.
170
AWS Identity and Access Management User Guide
Using Roles
To create a role for Amazon RDS Enhanced Monitoring
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
Choose Roles, and then choose Create role.
3.
Choose the AWS Service role type, and then choose the Amazon RDS Role for Enhanced
Monitoring service. Then choose Next: Permissions.
4.
Choose the AmazonRDSEnhancedMonitoringRole, permissions policy and then choose Next:
Review.
5.
For Role name, type a role name that helps you identify the purpose of this role. Role names must
be unique within your AWS account. They are not distinguished by case. For example, you cannot
create roles named both PRODROLE and prodrole. Because various entities might reference the role,
you cannot edit the name of the role after it has been created.
6.
(Optional) For Role description, type a description for the new role.
7.
Review the role and then choose Create role.
The role automatically gets a trust policy that grants the monitoring.rds.amazonaws.com service
permissions to assume the role. After it does, Amazon RDS can perform all of the actions that the
AmazonRDSEnhancedMonitoringRole policy allows.
The user that you want to enable Enhanced Monitoring needs a policy that includes a statement that
allows the user to pass the role, like the following. Use your account number and replace the role name
with the name you provided in step 3:
{
}
"SID": "PolicyStatementToAllowUserToPassOneSpecificRole",
"Effect": "Allow",
"Action": [ "iam:PassRole" ],
"Resource": "arn:aws-cn:iam:::role/RDS-Monitoring-Role"
You can combine this statement with statements in another policy or put it in its own policy. To instead
specify that the user can pass any role that begins with RDS-, you can replace the role name in the
resource ARN with a wildcard, for example:
"Resource": "arn:aws-cn:iam:::role/RDS-*"
Switching to a Role (AWS Management Console)
A role specifies a set of permissions that you can use to access AWS resources that you need. In that
sense, it is similar to a user in AWS Identity and Access Management (IAM). When you sign in as a user,
you get a specific set of permissions. However, you don't sign in to a role, but once signed in you can
switch to a role. This temporarily sets aside your original user permissions and instead gives you the
permissions assigned to the role. The role can be in your own account or any other AWS account. For
more information about roles, their benefits, and how to create them, see IAM Roles (p. 97), and
Creating IAM Roles (p. 146).
Important
When you switch roles in the AWS Management Console, the console always uses your original
credentials to authorize the switch. This applies whether you sign in as an IAM user, as a SAMLfederated role, or as a web-identity federated role. For example, if you switch to RoleA, it uses
your original user or federated role credentials to determine if you are allowed to assume RoleA.
If you then try to switch to RoleB while you are using RoleA, it still uses your original user or
171
AWS Identity and Access Management User Guide
Using Roles
federated role credentials to authorize your attempt to switch to RoleB, not the credentials for
RoleA.
This section describes how to use the IAM console to switch to a role:
• If your administrator provides you with a link, click the link and then skip to step Step 5 in the
following procedure. The link takes you to the appropriate web page and fills in the account ID (or
alias) and the role name for you.
Tip
You can manually construct the link yourself by using the following format:
https://signin.aws.amazon.com/switchrole?
account=account_id_number&roleName=role_name&displayName=text_to_display
Where your administrator provides the account_id_number and role_name to you. For
text_to_display, see the explanation in step 5 in the following procedure.
Important
If you create the role programmatically instead of in the IAM console, then you have an option
to add a Path of up to 512 characters in addition to the RoleName, which can be up to 64
characters long. However, to use a role with the Switch Role feature in the AWS console, the
combined Path and RoleName cannot exceed 64 characters.
• You can manually switch roles using the information your administrator provides by using the
following procedure:
To switch to a role
1.
Sign in to the AWS Management Console as an IAM user and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the IAM console, choose your user name on the navigation bar in the upper right. It typically looks
like this: [email protected]_ID_number_or_alias.
3.
For Identity, select Switch Role. If this is the first time selecting this option, a page appears with
more information. After reading it, click Switch Role. If you clear your browser cookies, this page can
appear again.
4.
On the Switch Role page, type the account ID number or the account alias and the name of the role
that was provided by your administrator.
Note
If your administrator created the role with a path, such as division_abc/subdivision_efg/
roleToDoXYZ, then you must type that complete path and name in the Role box. If you type
only the role name, the attempt to switch role fails.
Important
If you create the role programmatically instead of in the IAM console, then you have an
option to add a Path of up to 512 characters in addition to the RoleName, which can be
up to 64 characters long. However, to use a role with the Switch Role feature in the IAM
console, the combined Path and RoleName cannot exceed 64 characters. This is a limit of the
browser cookies that store the role name.
5.
(Optional) Type text that you want to appear on the navigation bar in place of your user name when
this role is active. A name is suggested, based on the account and role information, but you can
change it to whatever has meaning for you. You can also select a color to highlight the display name.
The name and color can help remind you when this role is active, which changes your permissions.
For example, for a role that gives you access to the test environment, you might specify a Display
Name of Test and select the green Display Color. For the role that gives you access to production,
you might specify a Display Name of Production and select red as the Display Color.
6.
Click Switch Role. The display name and color replace your user name on the navigation bar, and
you can start using the permissions that the role grants you.
172
AWS Identity and Access Management User Guide
Using Roles
Tip
The last several roles that you used appear on the Identity menu. The next time you need to
switch to one of those roles, you can simply click the desired role. You only need to enter the
account and role information manually if the role is not displayed on the Identity menu.
To stop using a role
1.
In the IAM console, select your role's Display Name on the right side of the navigation bar.
2.
Select Back to UserName. The role and its permissions are deactivated, and the permissions
associated with your IAM user and groups are automatically restored.
Switching to an IAM Role (AWS Command Line Interface)
A role specifies a set of permissions that you can use to access AWS resources that you need. In that
sense, it is similar to a user in AWS Identity and Access Management (IAM). When you sign in as a
user, you get a specific set of permissions. However, you don't sign in to a role, but once signed in as
a user you can switch to a role. This temporarily sets aside your original user permissions and instead
gives you the permissions assigned to the role. The role can be in your own account or any other AWS
account. For more information about roles, their benefits, and how to create and configure them, see
IAM Roles (p. 97), and Creating IAM Roles (p. 146).
Important
The permissions of your IAM user and any roles that you switch to are not cumulative. Only one
set of permissions is active at a time. When you switch to a role, you temporarily give up your
user permissions and work with the permissions that are assigned to the role. When you exit the
role, your user permissions are automatically restored.
You can run an AWS CLI command using a role only when you are signed in as an IAM user, as an
externally authenticated user (p. 105) (SAML (p. 112) or OIDC (p. 106)) already using a role, or when
run from within an Amazon EC2 instance that is attached to a role through its instance profile.
This section describes how to switch roles when you work at the command line with the AWS Command
Line Interface.
Imagine that you have an IAM user for working in the development environment and you occasionally
need to work with the production environment at the command line with the AWS CLI. You already
have an access key credential set available to you. This can be the access key pair assigned to your
standard IAM user; or, if you signed-in as a federated user, it can be the access key pair for the role
initially assigned to you. If your current permissions grant you the ability to assume a specific role, then
you can identify that role in a "profile" in the AWS CLI configuration files. That command is then run with
the permissions of the specified role, not the original identity. Note that when you specify that profile,
and thus use the new role, in an AWS CLI command, you cannot make use of your original permissions
in the development account at the same time because only one set of permissions can be in effect at a
time.
Note
For security purposes, you can use AWS CloudTrail to audit the use of roles in the account. To
identify a role's actions in CloudTrail logs, you can use the role session name. When the AWS CLI
assumes a role on a user's behalf as described in this topic, a role session name is automatically
created as AWS-CLI-session-nnnnnnnn, where nnnnnnnn is an integer that represents the time
in Unix epoch time (the number of seconds since midnight UTC on January 1, 1970). For more
information, see CloudTrail Event Reference in the AWS CloudTrail User Guide.
To switch to a role using the AWS CLI
1.
If you have never used the AWS CLI, then you must first configure your default CLI profile. Open a
command prompt and set up your AWS CLI installation to use the access key from your IAM user or
173
AWS Identity and Access Management User Guide
Using Roles
from your federated role. For more information, see Configuring the AWS Command Line Interface
in the AWS Command Line Interface User Guide.
$ aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json
2.
Create a new profile for the role in the .aws/config file. The following example creates a profile
called "prodaccess" that switches to the role ProductionAccessRole in the 123456789012 account.
You get the role ARN from the account administrator who created the role. When this profile is
invoked, the AWS CLI uses the credentials of the source_profile to request credentials for the
role. Because of that, the identity referenced as the source_profile must have sts:AssumeRole
permissions to the role specified in the role_arn.
[profile prodaccess]
role_arn = arn:aws-cn:iam::123456789012:role/ProductionAccessRole
source_profile = default
3.
After you create the new profile, any AWS CLI command that specifies the parameter --profile
prodaccess runs under the permissions attached to the IAM role ProductionAccessRole instead of
the default user.
$ aws iam list-users --profile prodaccess
This command works if the permissions assigned to the ProductionAccessRole enable listing the
users in the current AWS account.
4.
To return to the permissions granted by your original credentials, run commands without the -profile parameter. The AWS CLI reverts to using the credentials in your default profile, which you
configured in Step 1.
For more information, see Assuming a Role in the AWS Command Line Interface User Guide.
Switching to an IAM Role (Tools for Windows PowerShell)
A role specifies a set of permissions that you can use to access AWS resources that you need. In that
sense, it is similar to a user in AWS Identity and Access Management (IAM). When you sign in as a
user, you get a specific set of permissions. However, you don't sign in to a role, but once signed in you
can switch to a role. This temporarily sets aside your original user permissions and instead gives you
the permissions assigned to the role. The role can be in your own account or any other AWS account.
For more information about roles, their benefits, and how to create and configure them, see IAM
Roles (p. 97), and Creating IAM Roles (p. 146).
Important
The permissions of your IAM user and any roles that you switch to are not cumulative. Only one
set of permissions is active at a time. When you switch to a role, you temporarily give up your
user permissions and work with the permissions that are assigned to the role. When you exit the
role, your user permissions are automatically restored.
This section describes how to switch roles when you work at the command line with the AWS Tools for
Windows PowerShell.
Imagine that you have an account in the development environment and you occasionally need to work
with the production environment at the command line using the Tools for Windows PowerShell. You
already have one access key credential set available to you. These can be an access key pair assigned to
174
AWS Identity and Access Management User Guide
Using Roles
your standard IAM user; or, if you signed-in as a federated user, they can be the access key pair for the
role initially assigned to you. You can use these credentials to run the Use-STSRole cmdlet that passes
the ARN of a new role as a parameter. The command returns temporary security credentials for the
requested role. You can then use those credentials in subsequent PowerShell commands with the role's
permissions to access resources in production. While you use the role, you cannot make use of your user
privileges in the Development account because only one set of permissions can be in effect at a time.
Note
For security purposes, you can use AWS CloudTrail to audit the use of roles in the account. The
cmdlet Use-STSRole must include a -RoleSessionName parameter with a value between 2 and
64 characters long that can include letters, numbers, and the =,[email protected] characters. The role session
name identifies actions in CloudTrail logs that are performed with the temporary security
credentials. For more information, see CloudTrail Event Reference in the AWS CloudTrail User
Guide.
Note that all access keys and tokens are examples only and cannot be used as shown. Replace with the
appropriate values from your live environment.
To switch to a role from the Tools for Windows PowerShell
1.
Open a PowerShell command prompt and configure the default profile to use the access key from
your current IAM user or from your federated role. If you have previously used the Tools for Windows
PowerShell , then this is likely already done. Note that you can switch roles only if you are signed in
as an IAM user.
PS C:\> Set-AWSCredentials -AccessKey AKIAIOSFODNN7EXAMPLE -SecretKey wJalrXUtnFEMI/
K7MDENG/bPxRfiCYEXAMPLEKEY -StoreAs MyMainUserProfile
PS C:\> Initialize-AWSDefaults -ProfileName MyMainUserProfile -Region us-west-2
For more information, see Using AWS Credentials in the AWS Tools for Windows PowerShell User
Guide.
2.
To retrieve credentials for the new role, run the following command to switch to the RoleName role
in the 123456789012 account. You get the role ARN from the account administrator who created
the role. The command requires that you provide a session name as well. You can choose any text for
that. The following command requests the credentials and then captures the Credentials property
object from the returned results object and stores it in the $Creds variable.
PS C:\> $Creds = (Use-STSRole -RoleArn "arn:aws-cn:iam::123456789012:role/RoleName" RoleSessionName "MyRoleSessionName").Credentials
$Creds is an object that now contains the AccessKeyId, SecretAccessKey, and SessionToken
elements that you need in the following steps. The following sample commands illustrate typical
values:
PS C:\> $Creds.AccessKeyId
AKIAIOSFODNN7EXAMPLE
PS C:\> $Creds.SecretAccessKey
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
PS C:\> $Creds.SessionToken
AQoDYXdzEGcaEXAMPLE2gsYULo+Im5ZEXAMPLEeYjs1M2FUIgIJx9tQqNMBEXAMPLECvSRyh0FW7jEXAMPLEW
+vE/7s1HRp
XviG7b+qYf4nD00EXAMPLEmj4wxS04L/uZEXAMPLECihzFB5lTYLto9dyBgSDyEXAMPLE9/
g7QRUhZp4bqbEXAMPLENwGPy
Oj59pFA4lNKCIkVgkREXAMPLEjlzxQ7y52gekeVEXAMPLEDiB9ST3UuysgsKdEXAMPLE1TVastU1A0SKFEXAMPLEiywCC/
C
s8EXAMPLEpZgOs+6hz4AP4KEXAMPLERbASP+4eZScEXAMPLEsnf87eNhyDHq6ikBQ==
175
AWS Identity and Access Management User Guide
Using Roles
PS C:\> $Creds.Expiration
Thursday, June 18, 2015 2:28:31 PM
3.
To use these credentials for any subsequent command, include them with the -Credentials
parameter. For example, the following command uses the credentials from the role and works only if
the role is granted the iam:ListRoles permission and can therefore run the Get-IAMRoles cmdlet:
PS C:\> get-iamroles -Credential $Creds
4.
To return to your original credentials, simply stop using the -Credentials $Creds parameter and
allow PowerShell to revert to the credentials that are stored in the default profile.
Switching to an IAM Role (API)
A role specifies a set of permissions that you can use to access AWS resources that you need. In that
sense, it is similar to a user in AWS Identity and Access Management (IAM). An application assumes a role
to receive permissions to carry out required tasks and interact with AWS resources. The role can be in
your own account or any other AWS account. For more information about roles, their benefits, and how
to create and configure them, see IAM Roles (p. 97), and Creating IAM Roles (p. 146).
This section describes how to switch roles from within code that uses the AWS API.
Note that all access keys and tokens are examples only and cannot be used as shown. Replace with the
appropriate values from your live environment.
To assume a role, an application calls the AWS STS AssumeRole API and passes the ARN of the role to
use. The AssumeRole API returns a set of temporary security credentials that you can use in subsequent
AWS API calls to access resources in the account that owns the role. The temporary credentials have
whatever permissions are defined in the role's access policy. The call to AssumeRole can optionally pass a
supplemental policy that can further restrict (filter) the permissions of the temporary security credentials
that the AssumeRole API returns. You can call AssumeRole only with IAM user or IAM role credentials.
Note
For security purposes, you can use AWS CloudTrail to audit the use of roles in the account. The
call to AssumeRole must include a role session name between 2 and 64 characters long that can
include letters, numbers, and the =,[email protected] characters. The role session name is used in CloudTrail
logs to identify actions performed by the temporary security credentials. For more information,
see CloudTrail Event Reference in the AWS CloudTrail User Guide.
The following example in Python using the Boto3 interface to AWS (AWS SDK for Python (Boto) V3)
shows how to call AssumeRole and how to use the temporary security credentials returned by AssumeRole
to list all Amazon S3 buckets in the account that owns the role.
import boto3
#
#
#
#
#
#
#
The calls to AWS STS AssumeRole must be signed with the access key ID
and secret access key of an existing IAM user or by using existing temporary
credentials such as those from antoher role. The credentials can be in
environment variables or in a configuration file and will be discovered
automatically by the boto3.client() function. For more information, see the
Python SDK documentation:
http://boto3.readthedocs.io/en/latest/reference/services/sts.html#client
# create an STS client object that represents a live connection to the
# STS service
sts_client = boto3.client('sts')
176
AWS Identity and Access Management User Guide
Using Roles
# Call the assume_role method of the STSConnection object and pass the role
# ARN and a role session name.
assumedRoleObject = sts_client.assume_role(
RoleArn="arn:aws-cn:iam::account-of-role-to-assume:role/name-of-role",
RoleSessionName="AssumeRoleSession1"
)
# From the response that contains the assumed role, get the temporary
# credentials that can be used to make subsequent API calls
credentials = assumedRoleObject['Credentials']
# Use the temporary credentials that AssumeRole returns to make a
# connection to Amazon S3
s3_resource = boto3.resource(
's3',
aws_access_key_id = credentials['AccessKeyId'],
aws_secret_access_key = credentials['SecretAccessKey'],
aws_session_token = credentials['SessionToken'],
)
# Use the Amazon S3 resource object that is now configured with the
# credentials to access your S3 buckets.
for bucket in s3_resource.buckets.all():
print(bucket.name)
Using an IAM Role to Grant Permissions to Applications Running
on Amazon EC2 Instances
Applications that run on an EC2 instance must include AWS credentials in their AWS API requests. You
could have your developers store AWS credentials directly within the EC2 instance and allow applications
in that instance to use those credentials. But developers would then have to manage the credentials and
ensure that they securely pass the credentials to each instance and update each EC2 instance when it's
time to rotate the credentials. That's a lot of additional work.
Instead, you can and should use an IAM role to manage temporary credentials for applications that run
on an EC2 instance. When you use a role, you don't have to distribute long-term credentials to an EC2
instance. Instead, the role supplies temporary permissions that applications can use when they make
calls to other AWS resources. When you launch an EC2 instance, you specify an IAM role to associate with
the instance. Applications that run on the instance can then use the role-supplied temporary credentials
to sign API requests.
Using roles to grant permissions to applications that run on EC2 instances requires a bit of extra
configuration. An application running on an EC2 instance is abstracted from AWS by the virtualized
operating system. Because of this extra separation, an additional step is needed to assign an AWS role
and its associated permissions to an EC2 instance and make them available to its applications. This
extra step is the creation of an instance profile that is attached to the instance. The instance profile
contains the role and can provide the role's credentials to an application that runs on the instance. Those
credentials can then be used in the application's API calls to access resources and to limit access to only
those resources that the role specifies. Note that only one role can be assigned to an EC2 instance at a
time, and all applications on the instance share the same role and permissions.
Using roles in this way has several benefits. Because role credentials are temporary and rotated
automatically, you don't have to manage credentials, and you don't have to worry about long-term
security risks. In addition, if you use a single role for multiple instances, you can make a change to that
one role and the change is propagated automatically to all the instances.
Note
Although a role is usually assigned to an EC2 instance when you launch it, a role can also be
attached to an EC2 instance that is already running. To learn how to attach a role to a running
instance, see IAM Roles for Amazon EC2.
177
AWS Identity and Access Management User Guide
Using Roles
How Do Roles for EC2 Instances Work?
In the following figure, a developer runs an application on an EC2 instance that requires access to the S3
bucket named photos. An administrator creates the Get-pics role. The role includes policies that grant
read permissions for the bucket and that allow the developer to launch the role with an EC2 instance.
When the application runs on the instance, it can use the role's temporary credentials to access the
photos bucket. The administrator doesn't have to grant the developer permission to access the photos
bucket, and the developer never has to share or manage credentials.
1. The administrator uses IAM to create the Get-pics role. In the role's trust policy, the administrator
specifies that only EC2 instances can assume the role. In the role's access policy, the administrator
specifies read-only permissions for the photos bucket.
2. A developer launches an EC2 instance and assigns the Get-pics role to that instance.
Note
If you use the IAM console, the instance profile is managed for you and is mostly transparent
to you. However, if you use the AWS CLI or API to create and manage the role and EC2
instance, then you must create the instance profile and assign the role to it as separate steps.
Then, when you launch the instance, you must specify the instance profile name instead of
the role name.
3. When the application runs, it obtains temporary security credentials from Amazon EC2 instance
metadata, as described in Retrieving Security Credentials from Instance Metadata. These are
temporary security credentials (p. 193) that represent the role and are valid for a limited period of
time.
With some AWS SDKs, the developer can use a provider that manages the temporary security
credentials transparently. (The documentation for individual AWS SDKs describes the features
supported by that SDK for managing credentials.)
Alternatively, the application can get the temporary credentials directly from the instance
metadata of the EC2 instance. Credentials and related values are available from the iam/securitycredentials/role-name category (in this case, iam/security-credentials/Get-pics) of the
metadata. If the application gets the credentials from the instance metadata, it can cache the
credentials.
4. Using the retrieved credentials, the application accesses the photo bucket. Because of the policy
attached to the Get-pics role, the application has read-only permissions.
178
AWS Identity and Access Management User Guide
Using Roles
The temporary security credentials that are available on the instance are automatically rotated
before they expire so that a valid set is always available. The application just needs to make sure that
it gets a new set of credentials from the instance metadata before the current ones expire. If the
AWS SDK manages credentials, the application doesn't need to include additional logic to refresh
the credentials. However, if the application gets temporary security credentials from the instance
metadata and has cached them, it should get a refreshed set of credentials every hour, or at least
15 minutes before the current set expires. The expiration time is included in the information that is
returned in the iam/security-credentials/role-name category.
Permissions Required for Using Roles with Amazon EC2
To launch an instance with a role, the developer must have permission to launch EC2 instances and
permission to pass IAM roles.
The following sample policy allows users to use the AWS Management Console to launch an instance
with a role. The policy includes wildcards (*) to allow a user to pass any role and to perform all Amazon
EC2 actions. The ListInstanceProfiles action allows users to view all of the roles that are available in
the AWS account.
Example policy that grants a user permission to use the Amazon EC2 console to launch an
instance with any role
{
}
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"iam:PassRole",
"iam:ListInstanceProfiles",
"ec2:*"
],
"Resource": "*"
}]
Restricting Which Roles Can Be Passed to EC2 Instances (Using PassRole)
You can use the PassRole permission to restrict which role a user can pass to an EC2 instance when
the user launches the instance. This helps prevent the user from running applications that have more
permissions than the user has been granted—that is, from being able to obtain elevated privileges. For
example, imagine that user Alice has permissions only to launch EC2 instances and to work with Amazon
S3 buckets, but the role she passes to an EC2 instance has permissions to work with IAM and Amazon
DynamoDB. In that case, Alice might be able to launch the instance, log into it, get temporary security
credentials, and then perform IAM or DynamoDB actions that she's not authorized for.
To restrict which roles a user can pass to an EC2 instance, you create a policy that allows the PassRole
action. You then attach the policy to the user (or to an IAM group that the user belongs to) who will
launch EC2 instances. In the Resource element of the policy, you list the role or roles that the user is
allowed to pass to EC2 instances. When the user launches an instance and associates a role with it,
Amazon EC2 checks whether the user is allowed to pass that role. Of course, you should also ensure that
the role that the user can pass does not include more permissions than the user is supposed to have.
Note
PassRole is not an API action in the same way that RunInstances or ListInstanceProfiles is.
Instead, it's a permission that AWS checks whenever a role ARN is passed as a parameter to an
API (or the console does this on the user's behalf). It helps an administrator to control which
roles can be passed by which users. In this case, it ensures that the user is allowed to attach a
specific role to an Amazon EC2 instance.
179
AWS Identity and Access Management User Guide
Using Roles
Example policy that grants a user permission to launch an EC2 instance with a specific role
The following sample policy allows users to use the Amazon EC2 API to launch an instance with a role.
The Resource element specifies the Amazon Resource Name (ARN) of a role. By specifying the ARN,
the policy grants the user the permission to pass only the Get-pics role. If the user tries to specify a
different role when launching an instance, the action fails.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/Get-pics"
}
]
How Do I Get Started?
To understand how roles work with EC2 instances, you need to use the IAM console to create a role,
launch an EC2 instance that uses that role, and then examine the running instance. You can examine the
instance metadata to see how the role credentials are made available to an instance. You can also see
how an application that runs on an instance can use the role. Use the following resources to learn more.
Related Information
For more information about creating roles or roles for EC2 instances, see the following information:
• For more information about using IAM roles with Amazon EC2 instances, go to the Amazon EC2 User
Guide for Linux Instances.
• To create a role, see Creating IAM Roles (p. 146)
• For more information about using temporary security credentials, see Temporary Security
Credentials (p. 193).
• If you work with the IAM API or CLI, you must create and manage IAM instance profiles. For more
information about instance profiles, see Using Instance Profiles (p. 180).
• For more information about role credentials in the instance metadata, see Retrieving Security
Credentials from Instance Metadata in the Amazon EC2 User Guide for Linux Instances.
Using Instance Profiles
An instance profile is a container for an IAM role that you can use to pass role information to an EC2
instance when the instance starts.
Managing Instance Profiles using the AWS Management Console
If you use the AWS Management Console to create a role for Amazon EC2, the console automatically
creates an instance profile and gives it the same name as the role. When you then use the Amazon EC2
console to launch an instance with an IAM role, you can select a role to associate with the instance. In the
console, the list that's displayed is actually a list of instance profile names. The console does not create
an instance profile for a role that is not associated with Amazon EC2.
180
AWS Identity and Access Management User Guide
Using Roles
Managing Instance Profiles using the AWS CLI, Tools for Windows PowerShell, and AWS API
If you manage your roles from the AWS CLI, Tools for Windows PowerShell, or the AWS API, you create
roles and instance profiles as separate actions. You can give the roles and instance profiles different
names, so you have to know the names of your instance profiles as well as the names of roles they
contain so that you can choose the correct instance profile when you launch an EC2 instance.
Note
An instance profile can contain only one IAM role, although a role can be included in multiple
instance profiles. This limit of one role per instance cannot be increased.
You can use the following commands to work with instance profiles in an AWS account.
Create an instance profile
• AWS CLI: aws iam create-instance-profile
• Tools for Windows PowerShell: New-IAMInstanceProfile
• AWS API: CreateInstanceProfile
Add a role to an instance profile
• AWS CLI: aws iam add-role-to-instance-profile
• Tools for Windows PowerShell: Add-IAMRoleToInstanceProfile
• AWS API: AddRoleToInstanceProfile
List instance profiles
• AWS CLI: aws iam list-instance-profiles, aws iam list-instance-profiles-for-role
• Tools for Windows PowerShell: Get-IAMInstanceProfiles
• AWS API: ListInstanceProfiles, ListInstanceProfilesForRole
Get information about an instance profile
• AWS CLI: aws iam get-instance-profile
• Tools for Windows PowerShell: Get-IAMInstanceProfile
• AWS API: GetInstanceProfile
Remove a role from an instance profile
• AWS CLI: aws iam remove-role-from-instance-profile
• Tools for Windows PowerShell: Remove-IAMRoleFromInstanceProfile
• AWS API: RemoveRoleFromInstanceProfile
Delete an instance profile
• AWS CLI: aws iam delete-instance-profile
• Tools for Windows PowerShell: Remove-IAMInstanceProfile
• AWS API: DeleteInstanceProfile
You can also attach a role to an already running EC2 instance by using the following commands. For
more information, see IAM Roles for Amazon EC2.
Attach an instance profile with a role to a stopped or running EC2 instance
181
AWS Identity and Access Management User Guide
Using Roles
• AWS CLI: aws ec2 associate-iam-instance-profile
• Tools for Windows PowerShell: Register-Ec2IamInstanceProfile
• AWS API: AssociateIamInstanceProfile
Get information about an instance profile attached to an EC2 instance
• AWS CLI: aws ec2 describe-iam-instance-profile-associations
• Tools for Windows PowerShell: Get-EC2IamInstanceProfileAssociation
• AWS API: DescribeIamInstanceProfileAssociations
Detach an instance profile with a role from a stopped or running EC2 instance
• AWS CLI: aws ec2 disassociate-iam-instance-profile
• Tools for Windows PowerShell: Unregister-Ec2IamInstanceProfile
• AWS API: DisassociateIamInstanceProfile
Revoking IAM Role Temporary Security Credentials
Warning
If you follow the steps on this page, all users with current sessions created by assuming the role
are denied access to all AWS actions and resources. This can result in users losing unsaved work.
When you enable users to access the AWS Management Console with a long session duration time (such
as 12 hours), their temporary credentials do not expire as quickly. If users inadvertently expose their
credentials to an unauthorized third party, that party has access for the duration of the session. However,
you can immediately revoke all permissions to the role's credentials issued before a certain point in time
if you need to. All temporary credentials for that role issued before the specified time become invalid.
This forces all users to reauthenticate and request new credentials.
Note
You cannot revoke the session for a service-linked role (p. 99).
When you revoke permissions for a role using the procedure in this topic, AWS attaches a new inline
policy to the role that denies all permissions to all actions. It includes a condition that applies the
restrictions only if the user assumed the role before the point in time when you revoke the permissions. If
the user assumes the role after you revoked the permissions, then the deny policy does not apply to that
user.
Important
This deny policy applies to all users of the specified role, not just those with longer duration
console sessions.
Minimum Permissions to Revoke Session Permissions from a Role
To successfully revoke session permissions from a role, you must have the AttachRolePolicy permission
for the role. This allows you to add the AWSRevokeOlderSessions policy to the role.
Revoking Session Permissions
To revoke the session permissions from a role, take the following steps:
To immediately deny all permissions to any current user of role credentials
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
182
AWS Identity and Access Management User Guide
Managing Roles
2.
In the navigation pane of the IAM Dashboard, choose Roles, and then choose the name (not the
check box) of the role whose permissions you want to revoke.
3.
On the Summary page for the selected role, choose the Revoke sessions tab.
4.
On the Revoke sessions tab, choose Revoke active sessions.
5.
AWS asks you to confirm the action. Choose Revoke active sessions on the dialog box.
IAM immediately attaches a policy named AWSRevokeOlderSessions to the role. The policy denies
all access to users who assumed the role before the moment you chose Revoke active sessions. Any
user who assumes the role after you chose Revoke active sessions is not affected.
Important
When you update existing policy permissions, or when you apply a new policy to a user or a
resource, it may take a few minutes for policy updates to take effect.
Note
Don't worry about remembering to delete the policy. Any user who assumes the role after you
revoked sessions is not affected by the policy. If you choose to Revoke Sessions again later, then
the date/time stamp in the policy is refreshed and it again denies all permissions to any user
who assumed the role before the new specified time.
Valid users whose sessions are revoked in this way must acquire temporary credentials for a new session
to continue working. Note that the AWS CLI caches credentials until they expire. To force the CLI to
delete and refresh cached credentials that are no longer valid, run one of the following commands:
Linux, macOS, or Unix
$ rm -r ~/.aws/cli/cache
Windows
C:\> del /s /q %UserProfile%\.aws\cli\cache
For more information, see Disabling Permissions for Temporary Security Credentials (p. 214).
Managing IAM Roles
Occasionally you need to modify or delete the roles that you have created. To change a role you can
modify the policies associated with the role, change who can access the role, and edit the permissions
that the role grants to users. You can also delete roles that are no longer needed. You can manage your
roles from the AWS Management Console, the AWS CLI, and the API.
Topics
• Modifying a Role (p. 183)
• Deleting Roles or Instance Profiles (p. 188)
Modifying a Role
You can change or modify a role in the following ways:
• To change who can assume a role, modify the role's trust policy.
Note
If the role is a service-linked role (p. 99), the role's trust policy cannot be modified. Servicelinked roles appear with (Service-linked role) in the Trusted entities column of the table.
183
AWS Identity and Access Management User Guide
Managing Roles
• To change the permissions allowed by the role, modify the role's permissions policy (or policies).
Note
If the role is a service-linked role (p. 99), the role's permissions can be modified only from
the service that depends on the role. Service-linked roles appear with (Service-linked role) in
the Trusted entities column of the table. See the AWS documentation for your service to see
whether it supports this feature.
• To change the description of the role, modify the description text.
You can use the AWS Management Console, the AWS Command Line Tools, the Tools for Windows
PowerShell, or the IAM API to make these changes.
Modifying a Role (Console)
You can use the AWS Management Console to modify a role.
To change which trusted principals can access the role (console)
1.
In the navigation pane of the IAM console, choose Roles.
2.
In the list of roles in your account, choose the name of the role that you want to modify.
3.
Choose the Trust relationships tab, and then choose Edit trust relationship.
4.
Edit the trust policy as needed. To add additional trusted principals, specify them in the Principal
element. Remember that policies are written in the JSON format, and JSON arrays are surrounded
by square brackets [ ] and separated by commas. As an example, the following policy snippet shows
how to reference two AWS accounts in the Principal element:
"Principal": {
"AWS": [
"arn:aws-cn:iam::111122223333:root",
"arn:aws-cn:iam::444455556666:root"
]
},
Remember that adding an account to the trust policy of a role is only half of establishing the trust
relationship. By default, no users in the trusted accounts can assume the role until the administrator
for that account grants the users the permission to assume the role. To do that, the administrator
adds the Amazon Resource Name (ARN) of the role to an Allow element for the sts:AssumeRole
action. For more information, see the next procedure and the topic Granting a User Permissions to
Switch Roles (p. 167).
If your role can be used by one or more trusted services rather than AWS accounts, then the policy
might contain an element similar to the following:
"Principal": {
"Service": [
"opsworks.amazonaws.com",
"ec2.amazonaws.com"
]
},
5.
When you are done editing, choose Update Trust Policy to save your changes.
For more information about policy structure and syntax, see Overview of IAM Policies (p. 232) and
the IAM Policy Elements Reference (p. 374).
184
AWS Identity and Access Management User Guide
Managing Roles
To allow users in a trusted external account to use the role (console)
For more information and detail about this procedure, see Granting a User Permissions to Switch
Roles (p. 167).
1.
Sign in to the trusted external AWS account.
2.
Decide whether to attach the permissions to a user or to a group. In the navigation pane of the IAM
console, choose Users or Groups accordingly.
3.
Choose the name of the user or group to which you want to grant access, and then choose the
Permissions tab.
4.
Do one of the following:
• To edit a customer managed policy, choose the name of the policy and then choose Edit policy.
You cannot edit an AWS managed policy. AWS managed policies appear with the AWS icon
(
). For more information about the difference between AWS managed policies and customer
managed policies, see Managed Policies and Inline Policies (p. 235).
• To edit an inline policy, choose the arrow next to the name of the policy and choose Edit policy.
5.
In the policy editor, add a new Statement element that specifies the following:
{
}
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws-cn:iam::AWS account ID that contains the role:role/role name"
Replace the values in red with the actual values from the ARN of the role in the original account that
users in this trusted external account can use.
Remember that you can have only one Statement keyword. However, a statement can have several
elements in an array, with elements separated by commas in their own curly braces { } and all of the
elements surrounded by square brackets [ ].
6.
Follow the prompts on screen to finish editing the policy.
For more information about editing customer managed policies in the AWS Management Console,
see Editing Customer Managed Policies (p. 252).
For more information about editing inline policies in the AWS Management Console, see Working
with Inline Policies (Console) (p. 256).
To change the permissions allowed by a role (console)
1.
In the navigation pane of the IAM console, choose Roles.
2.
Choose the name of the role to modify, and then choose the Permissions tab.
3.
Do one of the following:
• To edit an existing customer managed policy, choose the name of the policy and then choose Edit
policy.
Note
You cannot edit an AWS managed policy. AWS managed policy appear with the AWS icon
(
). For more information about the difference between AWS managed policies and
customer managed policies, see Managed Policies and Inline Policies (p. 235).
• To attach an existing managed policy, choose Add permissions.
185
AWS Identity and Access Management User Guide
Managing Roles
• To edit an existing inline policy, choose the arrow next to the name of the policy and choose Edit
Policy.
• To embed a new inline policy, choose Add inline policy.
For example policies that delegate permissions through roles, see Example Policies (p. 298).
For more information about permissions, see Overview of IAM Policies (p. 232).
To change the description of a role (console)
1.
In the navigation pane of the IAM console, choose Roles.
2.
Choose the name of the role to modify.
3.
Next to Role description and on the far right, choose Edit.
4.
Type a new description in the box and choose Save.
Modifying a Role (AWS CLI, AWS Tools for Windows PowerShell, AWS API)
You can use the AWS Command Line Interface or IAM API to modify a role.
To change the trusted principals that can access the role (AWS CLI, AWS Tools for Windows
PowerShell, AWS API)
1.
If you don't know the name of the role that you want to modify, use one of the following commands
to list the roles in your account:
• AWS CLI: aws iam list-roles
• AWS Tools for Windows PowerShell: Get-IAMRoles
• IAM API: ListRoles
2.
(Optional) To view the current trust policy for a role, use one of the following commands:
• AWS CLI: aws iam get-role
• AWS Tools for Windows PowerShell: Get-IAMRole
• IAM API: GetRole
3.
To modify the trusted principals that can access the role, create a text file with the updated trust
policy. You can use any text editor to construct the policy.
For example, the following policy snippet shows how to reference two AWS accounts in the
Principal element:
"Principal": {
"AWS": [
"arn:aws-cn:iam::111122223333:root",
"arn:aws-cn:iam::444455556666:root"
]
},
Remember that adding an account to the trust policy of a role is only half of establishing the trust
relationship. By default, no users in the trusted accounts can assume the role until the administrator
for that account grants the users the permission to assume the role. To do this, the administrator
must add the Amazon Resource Name (ARN) of the role to an Allow element for the sts:AssumeRole
action. For more information, see the next procedure and the topic Granting a User Permissions to
Switch Roles (p. 167).
4.
To update the trust policy, use one of the following commands:
186
AWS Identity and Access Management User Guide
Managing Roles
• AWS CLI: aws iam update-assume-role-policy
• AWS Tools for Windows PowerShell: Update-IAMAssumeRolePolicy
• IAM API: UpdateAssumeRolePolicy
To allow users in a trusted external account to use the role (AWS CLI, AWS Tools for Windows
PowerShellAWS API)
For more information and detail about this procedure, see Granting a User Permissions to Switch
Roles (p. 167).
1.
Begin by creating a policy that grants permissions to assume the role. For example, the following
policy contains the minimum necessary permissions:
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws-cn:iam::AWS account ID that contains the role:role/role name"
}
Create a JSON file that contains a policy similar to the preceding example. Replace the values in red
with the actual values from the ARN of the role that users are allowed to assume. After you have
created the policy, use one of the following commands to upload it to IAM:
• AWS CLI: aws iam create-policy
• AWS Tools for Windows PowerShell: New-IAMPolicy
• IAM API: CreatePolicy
The output of this command contains the ARN of the policy. Make a note of this ARN because you
will need to use it in a later step.
2.
Decide which user or group to attach the policy to. If you don't know the name of the user or group
that you want to modify, use one of these commands to list the users or group in your account:
• AWS CLI: aws iam list-users or aws iam list-groups
• AWS Tools for Windows PowerShell: Get-IAMUsers or Get-IAMGroups
• IAM API: ListUsers or ListGroups
3.
Use one of the following commands to attach the policy that you created in a previous step to the
user or group:
• AWS CLI: aws iam attach-user-policy or aws iam attach-group-policy
• AWS Tools for Windows PowerShell: Register-IAMUserPolicy or Register-IAMGroupPolicy
• IAM API: AttachUserPolicy or AttachGroupPolicy
To change the permissions allowed by a role (AWS CLI, AWS Tools for Windows PowerShell,
AWS API)
1.
(Optional) To view the current permissions associated with a role, use the following commands:
• AWS CLI: aws iam list-role-policies (to list inline policies) and aws iam list-attached-role-policies
(to list managed policies)
187
AWS Identity and Access Management User Guide
Managing Roles
• AWS Tools for Windows PowerShell: Get-IAMRolePolicies (to list inline policies) and GetIAMAttachedRolePolicies (to list managed policies)
• IAM API: ListRolePolicies (to list inline policies) and ListAttachedRolePolicies (to list managed
policies)
2.
The command to update permissions for the role differs depending on whether you are updating a
managed policy or an inline policy.
To update a managed policy, use one of the following commands to create a new version of the
managed policy:
• AWS CLI: aws iam create-policy-version
• AWS Tools for Windows PowerShell: New-IAMPolicyVersion
• IAM API: CreatePolicyVersion
To update an inline policy, use one of the following commands:
• AWS CLI: aws iam put-role-policy
• AWS Tools for Windows PowerShell: Write-IAMRolePolicy
• IAM API: PutRolePolicy
To change the description of a role (AWS CLI, AWS API)
1.
(Optional) To view the current description for a role, use the following commands:
• AWS CLI: aws iam get-role
• IAM API: GetRole
2.
To update a role's description, use one of the following commands:
• AWS CLI: aws iam update-role-description
• IAM API: UpdateRoleDescription
Deleting Roles or Instance Profiles
If you no longer need a role, we recommend that you delete the role and its associated permissions. That
way you don’t have an unused entity that is not actively monitored or maintained.
If the role was associated with an EC2 instance, then you can also remove the role from the instance
profile and then delete the instance profile.
Warning
Make sure that you do not have any Amazon EC2 instances running with the role or instance
profile you are about to delete. Deleting a role or instance profile that is associated with a
running instance will break any applications that is running on the instance.
Deleting a Service-Linked Role
If the role is a service-linked role (p. 99), review the documentation for the linked service to learn how
to delete the role. You can view the service-linked roles in your account by going to the IAM Roles page
in the console. Service-linked roles appear with (Service-linked role) in the Trusted entities column of
the table. A banner on the role's Summary page also indicates that the role is a service-linked role.
If the service does not include documentation for deleting the service-linked role, then you can use
the IAM console, API, or CLI to delete the role. For more information, see Deleting a Service-Linked
Role (p. 143).
188
AWS Identity and Access Management User Guide
Managing Roles
Deleting an IAM Role (Console)
When you use the AWS Management Console to delete a role, IAM also automatically deletes the policies
associated with the role. It also deletes any Amazon EC2 instance profile that contains the role.
Important
In some cases, a role might be associated with an Amazon EC2 instance profile, and the role
and the instance profile might the exact same name. In that case you can use the AWS console
to delete the role and the instance profile. This linkage happens automatically for roles and
instance profiles that you create them in the console. If you created the role from the AWS CLI,
Tools for Windows PowerShell, or the AWS API, then the role and the instance profile might
have different names. In that case you cannot use the console to delete them. Instead, you must
use the AWS CLI, Tools for Windows PowerShell, or AWS API to first remove the role from the
instance profile. You must then take a separate step to delete the role.
To delete a role (console)
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Roles, and then select the check box next to the role name that you
want to delete, not the name or row itself.
3.
For Role actions at the top of the page, choose Delete role.
4.
In the confirmation dialog box, review the service last accessed data, which shows when each of the
selected roles last accessed an AWS service. This helps you to confirm whether the role is currently
active. If you want to proceed, choose Yes, Delete. If you are sure, you can proceed with the deletion
even if the service last accessed data is still loading.
Note
You cannot use the console to delete an instance profile, except when it has the exact same
name as the role. In addition, you must delete the instance profile as part of the process of
deleting a role as described in the preceding procedure. To delete an instance profile without
also deleting the role, you must use the AWS CLI, Tools for Windows PowerShell, or AWS API.
For more information, see the following sections.
Deleting an IAM Role (AWS CLI)
When you use the AWS CLI to delete a role, you must first delete the policies associated with the role.
Also, if you want to delete the associated instance profile that contains the role, you must delete it
separately.
To use the AWS CLI to delete a role (AWS CLI)
1.
If you don't know the name of the role that you want to delete, type the following command to list
the roles in your account:
$ aws iam list-roles
A list of roles with their Amazon Resource Name (ARN) is displayed. Use the role name, not the ARN,
to refer to roles with the CLI commands. For example, if a role has the following ARN: arn:awscn:iam::123456789012:role/myrole, you refer to the role as myrole.
2.
Remove the role from all instance profiles that the role is in.
a.
To list all instance profiles that the role is associated with, type the following command:
$ aws iam list-instance-profiles-for-role --role-name role-name
189
AWS Identity and Access Management User Guide
Managing Roles
b.
To remove the role from an instance profile, type the following command for each instance
profile:
$ aws iam remove-role-from-instance-profile --instance-profile-name instanceprofile-name --role-name role-name
3.
Delete all policies that are associated with the role.
a.
To list all policies that are in the role, type the following command:
$ aws iam list-role-policies --role-name role-name
b.
To delete each policy from the role, type the following command for each policy:
$ aws iam delete-role-policy --role-name role-name --policy-name policy-name
4.
Type the following command to delete the role:
$ aws iam delete-role --role-name role-name
5.
If you do not plan to reuse the instance profiles that were associated with the role, you can type the
following command to delete them:
$ aws iam delete-instance-profile --instance-profile-name instance-profile-name
Deleting an IAM Role (Tools for Windows PowerShell)
When you use Windows PowerShell to delete a role, you must first delete the policies associated with the
role. Also, if you want to delete the associated instance profile that contains the role, you must delete it
separately.
To use the Tools for Windows PowerShell to delete a role (Tools for Windows PowerShell)
1.
If you don't know the name of the role that you want to delete, type the following command to list
the roles in your account:
PS C:\> Get-IAMRoles | Select RoleName
Use the role name, not the ARN, to refer to roles with the PowerShell cmdlets. For example, if a
role has the following ARN: arn:aws-cn:iam::123456789012:role/myrole, you refer to the role as
myrole.
2.
Remove the role from all instance profiles that the role is in. The following command gets the list of
all instance profiles that contain the role, removes the role from each instance profile in the list, and
then deletes the now empty instance profiles. If you plan to reuse the instance profiles, then you can
omit the last cmdlet in the command.
PS C:\> Get-IAMInstanceProfileForRole -RoleName RoleName | RemoveIAMRoleFromInstanceProfile -RoleName RoleName | Remove-IAMInstanceProfile
3.
Delete all policies that are associated with the role. The following command gets the list of all
policies that are attached to the role and detaches each one.
PS C:\> Get-IAMAttachedRolePolicies -RoleName RoleName | Unregister-IAMRolePolicy RoleName RoleName
190
AWS Identity and Access Management User Guide
Roles vs. Resource-based Policies
4.
Type the following command to delete the role:
PS C:\> Remove-IAMRole -RoleName RoleName
Deleting an IAM Role (AWS API)
When you use the IAM API to delete a role, you must first delete the policies associated with the role.
Also, if you want to delete the associated instance profile that contains the role, you must delete it
separately.
To use the AWS API to delete a role (API)
1.
To list all instance profiles that a role is in, call ListInstanceProfilesForRole.
To remove the role from all instance profiles that the role is in, call RemoveRoleFromInstanceProfile.
You must pass the role name and instance profile name.
If you are not going to reuse an instance profile that was associated with the role, you call
DeleteInstanceProfile to delete it.
2.
To list all policies for a role, call ListRolePolicies.
To delete all policies that are associated with the role, call DeleteRolePolicy. You must pass the role
name and policy name.
3.
Call DeleteRole to delete the roll.
Related Information
For general information about instance profiles, see Using Instance Profiles (p. 180).
For general information about service-linked roles, see Using Service-Linked Roles (p. 139).
How IAM Roles Differ from Resource-based Policies
For some AWS services, you can grant cross-account access to your resources. To do this, you attach a
policy directly to the resource that you want to share, instead of using a role as a proxy. The resource
that you want to share must support resource-based policies (p. 223). Unlike a user-based policy, a
resource-based policy specifies who (in the form of a list of AWS account ID numbers) can access that
resource.
Cross-account access with a resource-based policy has an advantage over a role. With a resource that
is accessed through a resource-based policy, the user still works in the trusted account and does not
have to give up his or her user permissions in place of the role permissions. In other words, the user
continues to have access to resources in the trusted account at the same time as he or she has access to
the resource in the trusting account. This is useful for tasks such as copying information to or from the
shared resource in the other account.
The disadvantage is that not all services support resource-based policies. A few of the AWS services that
support resource-based policies are listed here:
• Amazon S3 buckets – The policy is attached to the bucket, but the policy controls access to both the
bucket and the objects in it. For more information, go to Access Control in the Amazon Simple Storage
Service Developer Guide.
• Amazon Simple Notification Service (Amazon SNS) topics – For more information, go to Managing
Access to Your Amazon SNS Topics in the Amazon Simple Notification Service Developer Guide.
191
AWS Identity and Access Management User Guide
Roles vs. Resource-based Policies
• Amazon Simple Queue Service (Amazon SQS) queues – For more information, go to Appendix: The
Access Policy Language in the Amazon Simple Queue Service Developer Guide.
For a complete list of the growing number of AWS services that support attaching permission policies to
resources instead of principals, see AWS Services That Work with IAM (p. 363) and look for the services
that have Yes in the Resource Based column.
About Delegating AWS Permissions in a Resource-based Policy
After a resource grants your AWS account permissions as a principal in its resource-based policy, you can
then delegate permissions to specific users or groups under your AWS account. You attach a policy to the
user or group that you want to delegate the permissions to. Note that you can only delegate permissions
equivalent to, or less than, the permissions granted to your account by the resource owning account.
For example, if your account is granted full access to the resources of another AWS account, then you
can delegate full access, list access, or any other partial access to users under your AWS account. If, on
the other hand, your account is granted list access only, then you can delegate only list access. If you
try to delegate more permissions than your account has, your users will still have only list access only.
This is illustrated in the following figure. For information about attaching a policy to a user or group, see
Working with Policies (p. 250).
1. Account A gives account B full access to account A's S3 bucket by naming account B as a principal in
the policy. As a result, account B is authorized to perform any action on account A's bucket, and the
account B administrator can delegate access to its users in account B.
2. The account B administrator grants user 1 read-only access to account A's S3 bucket. User 1 can view
the objects in account A's bucket. The level of access account B can delegate is equivalent to, or less
than, the access the account has. In this case, the full access granted to account B is filtered to read
only for user 1.
192
AWS Identity and Access Management User Guide
Temporary Security Credentials
3. The account B administrator does not give access to user 2. Because users by default do not have
any permissions except those that are explicitly granted, user 2 does not have access to account A's
Amazon S3 bucket.
Important
In the preceding example, if account B had used wildcards (*) to give user 1 full access to all its
resources, user 1 would automatically have access to any resources that account B has access
to, including access granted by other accounts to those accounts' resources. In this case, user
1 would have access to any Account A resources granted to account B, in addition to those
explicitly granted to user 1.
IAM evaluates a user's permissions at the time the user makes a request. Therefore, if you use
wildcards (*) to give users full access to your resources, users are able to access any resources
that your AWS account has access to, even resources you add or gain access to after creating the
user's policy.
For information about permissions, policies, and the access policy language that you use to write policies,
see Access Management (p. 222).
Important
Give access only to entities you trust, and give the minimum amount of access necessary.
Whenever the trusted entity is another AWS account, that account can in turn delegate access to
any of its IAM users. The trusted AWS account can delegate access only to the extent that it has
been granted access; it cannot delegate more access than the account itself has been granted.
Temporary Security Credentials
You can use the AWS Security Token Service (AWS STS) to create and provide trusted users with
temporary security credentials that can control access to your AWS resources. Temporary security
credentials work almost identically to the long-term access key credentials that your IAM users can use,
with the following differences:
• Temporary security credentials are short-term, as the name implies. They can be configured to last for
anywhere from a few minutes to several hours. After the credentials expire, AWS no longer recognizes
them or allows any kind of access from API requests made with them.
• Temporary security credentials are not stored with the user but are generated dynamically and
provided to the user when requested. When (or even before) the temporary security credentials expire,
the user can request new credentials, as long as the user requesting them still has permissions to do
so.
These differences lead to the following advantages for using temporary credentials:
• You do not have to distribute or embed long-term AWS security credentials with an application.
• You can provide access to your AWS resources to users without having to define an AWS identity for
them. Temporary credentials are the basis for roles and identity federation (p. 97).
• The temporary security credentials have a limited lifetime, so you do not have to rotate them or
explicitly revoke them when they're no longer needed. After temporary security credentials expire,
they cannot be reused. You can specify how long the credentials are valid, up to a maximum limit.
AWS STS and AWS Regions
Temporary security credentials are generated by AWS STS. By default, AWS STS is a global service with
a single endpoint at https://sts.amazonaws.com. However, you can also choose to make AWS STS
193
AWS Identity and Access Management User Guide
Common Scenarios for Temporary Credentials
API calls to endpoints in any other supported region. This can reduce latency (server lag) by sending
the requests to servers in a region that is geographically closer to you. No matter which region your
credentials come from, they work globally. For more information, see Activating and Deactivating AWS
STS in an AWS Region (p. 218).
Common Scenarios for Temporary Credentials
Temporary credentials are useful in scenarios that involve identity federation, delegation, cross-account
access, and IAM roles.
Identity Federation
You can manage your user identities in an external system outside of AWS and grant users who sign in
from those systems access to perform AWS tasks and access your AWS resources. IAM supports two types
of identity federation. In both cases, the identities are stored outside of AWS. The distinction is where the
external system resides—in your data center or an external third party on the web. For more information
about external identity providers, see Identity Providers and Federation (p. 105).
• Enterprise identity federation – You can authenticate users in your organization's network, and then
provide those users access to AWS without creating new AWS identities for them and requiring them to
sign in with a separate user name and password. This is known as the single sign-on (SSO) approach to
temporary access. AWS STS supports open standards like Security Assertion Markup Language (SAML)
2.0, with which you can use Microsoft AD FS to leverage your Microsoft Active Directory. You can also
use SAML 2.0 to manage your own solution for federating user identities. For more information, see
About SAML 2.0-based Federation (p. 112).
• Custom federation broker – You can use your organization's authentication system to grant access
to AWS resources. For an example scenario, see Creating a URL that Enables Federated Users to
Access the AWS Management Console (Custom Federation Broker) (p. 132).
• Federation using SAML 2.0 – You can use your organization's authentication system and SAML to
grant access to AWS resources. For more information and an example scenario, see About SAML 2.0based Federation (p. 112).
• Web identity federation – You can let users sign in using a well-known third party identity provider
such as Login with Amazon, Facebook, Google, or any OpenID Connect (OIDC) 2.0 compatible provider.
You can exchange the credentials from that provider for temporary permissions to use resources
in your AWS account. This is known as the web identity federation approach to temporary access.
When you use web identity federation for your mobile or web application, you don't need to create
custom sign-in code or manage your own user identities. Using web identity federation helps you
keep your AWS account secure, because you don't have to distribute long-term security credentials,
such as IAM user access keys, with your application. For more information, see About Web Identity
Federation (p. 106).
AWS STS web identity federation supports Login with Amazon, Facebook, Google, and any OpenID
Connect (OICD)-compatible identity provider.
Note
For mobile applications, we recommend that you use Amazon Cognito. You can use this
service with the AWS Mobile SDK for iOS and the AWS Mobile SDK for Android and Fire
OS to create unique identities for users and authenticate them for secure access to your
AWS resources. Amazon Cognito supports the same identity providers as AWS STS, and also
supports unauthenticated (guest) access and lets you migrate user data when a user signs in.
Amazon Cognito also provides APIs for synchronizing user data so that it is preserved as users
move between devices. For more information, see the following:
• Amazon Cognito Identity in the AWS Mobile SDK for iOS Developer Guide
• Amazon Cognito Identity in the AWS Mobile SDK for Android Developer Guide
194
AWS Identity and Access Management User Guide
Requesting Temporary Security Credentials
Roles for Cross-account Access
Many organizations maintain more than one AWS account. Using roles and cross-account access, you can
define user identities in one account, and use those identities to access AWS resources in other accounts
that belong to your organization. This is known as the delegation approach to temporary access. For
more information, see Creating a Role to Delegate Permissions to an IAM User (p. 146).
Roles for Amazon EC2
If you run applications on Amazon EC2 instances and those applications need access to AWS resources,
you can provide temporary security credentials to your instances when you launch them. These
temporary security credentials are available to all applications that run on the instance, so you don't
need to store any long-term credentials on the instance. For more information, see Using an IAM Role to
Grant Permissions to Applications Running on Amazon EC2 Instances (p. 177).
Other AWS Services
You can use temporary security credentials to access most AWS services. For a list of the services that
accept temporary security credentials, see AWS Services That Work with IAM (p. 363).
Requesting Temporary Security Credentials
To request temporary security credentials, you can use the AWS STS API actions. You can use AWS
Security Token Service (AWS STS) to create and provide trusted users with temporary security credentials
that can control access to your AWS resources. For more information about AWS STS, see Temporary
Security Credentials (p. 193).
To call the APIs, you can use one of the AWS SDKs, which are available for a variety of programming
languages and environments, including Java, .NET, Python, Ruby, Android, and iOS. The SDKs take care
of tasks such as cryptographically signing your requests, retrying requests if necessary, and handling
error responses. You can also use the AWS STS Query API, which is described in the AWS Security Token
Service API Reference. Finally, two command line tools support the AWS STS commands: the AWS
Command Line Interface, and the AWS Tools for Windows PowerShell.
The AWS STS API actions return temporary security credentials that consist of an access key and a
session token. The access key consists of an access key ID and a secret key. Users (or an application that
the user runs) can use these credentials to access your resources. When the credentials are created,
they are associated with an IAM access control policy that limits what the user can do when using the
credentials. For more information, see Using Temporary Security Credentials to Request Access to AWS
Resources (p. 204).
Important
Although temporary security credentials are short lived, users who have temporary access can
make lasting changes to your AWS resources. For example, if a user with temporary access
launches an Amazon EC2 instance, the instance can continue to run and incur charges to your
AWS account even after the user's temporary security credentials expire.
Note
The size of the security token that STS APIs return is not fixed. We strongly recommend that you
make no assumptions about the maximum size. As of this writing, the typical size is less than
4096 bytes, but that can vary. Also, future updates to AWS might require larger sizes.
Using AWS STS with AWS Regions
You can send AWS STS API calls either to a global endpoint or to one of the regional endpoints. If you
choose an endpoint closer to you, you can reduce latency and improve the performance of your API
calls. You also can choose to direct your calls to an alternative regional endpoint if you can no longer
195
AWS Identity and Access Management User Guide
Requesting Temporary Security Credentials
communicate with the original endpoint. If you are using one of the various AWS SDKs, then use that
SDK's method to select a region before you make the API call. If you are manually constructing HTTP
API requests, then you must direct the request to the correct endpoint yourself. For more information,
see the AWS STS section of Regions and Endpoints and Activating and Deactivating AWS STS in an AWS
Region (p. 218).
Following are the APIs that you can use to acquire temporary credentials for use in your AWS
environment and applications.
AssumeRole—Cross-Account Delegation and Federation
Through a Custom Identity Broker
This API action is useful for allowing existing IAM users to access AWS resources that they don't already
have access to, such as resources in another AWS account. It is also useful for existing IAM users as a
means to temporarily gain privileged access. You must call this API using existing IAM user credentials.
For more information, see Creating a Role to Delegate Permissions to an IAM User (p. 146).
This call must be made using valid AWS security credentials. When you make this call, you pass the
following information:
• The Amazon Resource Name (ARN) of the role that the app should assume.
• The duration, which specifies how long the temporary security credentials are valid. The minimum
is 15 minutes (900 seconds) and the maximum (and the default) is 1 hour (3600 seconds). You need
to pass this value only if you want the temporary credentials to expire before 1 hour. This is separate
from the duration of a console session that you might request using these credentials. The request to
the federation endpoint for a console sign-in token takes a SessionDuration parameter that specifies
the maximum length of the console session, separately from the DurationSeconds parameter on
this API. For more information, see Creating a URL that Enables Federated Users to Access the AWS
Management Console (Custom Federation Broker) (p. 132).
• A role session name, which is a string value that you can use to identify the session. This value can be
captured and logged by CloudTrail to help you distinguish between your role users during an audit.
• Optionally, a policy (in JSON format). This policy is combined with the policy associated with the role.
If specified, the permissions are the intersection of those granted to the role and those granted by
this policy. You can use this policy to you further restrict the access permissions that are associated
with the temporary credentials, beyond the restrictions already established by the role access policy.
Note that this policy cannot be used to elevate privileges beyond what the assumed role is allowed to
access.
• An optional ExternalID value that can be used when delegating access to your account to a thirdparty. This value helps ensure that only the specified third-party can access the role. For more
information, see How to Use an External ID When Granting Access to Your AWS Resources to a Third
Party (p. 149).
The following example shows a sample request and response using AssumeRole. In this example, the
request includes the name for the session named Bob. The Policy parameter includes a JSON document
that specifies that the resulting credentials have permissions to access only Amazon S3.
Example Request
https://sts.amazonaws.com/
?Version=2011-06-15
&Action=AssumeRole
&RoleSessionName=Bob
&RoleArn=arn:aws-cn::iam::123456789012:role/demo
&Policy=%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Sid%22%3A
%20%22Stmt1%22%2C%22Effect%22%3A%20%22Allow%22%2C%22Action%22%3A%20%22s3%3A*%22%2C
%22Resource%22%3A%20%22*%22%7D%5D%7D
196
AWS Identity and Access Management User Guide
Requesting Temporary Security Credentials
&DurationSeconds=3600
&ExternalId=123ABC
&AUTHPARAMS
Note
The policy value shown in the example above is the URL-encoded version of the following
policy:
{"Version":"2012-10-17","Statement":
[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:*","Resource":"*"}]}
Also, note that the AUTHPARAMS parameter in the preceding example is meant as a placeholder
for the authentication information—that is, the signature—that you must include with AWS
HTTP API requests. We recommend using the AWS SDKs to create API requests, and one benefit
of doing so is that the SDKs handle request signing for you. If you must create and sign API
requests manually, go to Signing AWS Requests By Using Signature Version 4 in the Amazon
Web Services General Reference to learn how to sign a request.
This API supports a parameter for DurationSeconds that specifies how long the temporary credentials
are valid. This is not the same as the duration of a console session that might request using those
temporary credentials. You can request a console sign-in token by calling the federation endpoint and
supplying the temporary credentials to get a sign-in token for the console. That console request uses a
different SessionDuration parameter of up to 12 hours. For more information, see Creating a URL that
Enables Federated Users to Access the AWS Management Console (Custom Federation Broker) (p. 132).
In addition to the temporary security credentials, the response includes the Amazon Resource Name
(ARN) for the federated user and the expiration time of the credentials.
Example Response
<AssumeRoleResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<AssumeRoleResult>
<Credentials>
<SessionToken>
AQoDYXdzEPT//////////wEXAMPLEtc764bNrC9SAPBSM22wDOk4x4HIZ8j4FZTwdQW
LWsKWHGBuFqwAeMicRXmxfpSPfIeoIYRqTflfKD8YUuwthAx7mSEI/qkPpKPi/kMcGd
QrmGdeehM4IC1NtBmUpp2wUE8phUZampKsburEDy0KPkyQDYwT7WZ0wq5VSXDvp75YU
9HFvlRd8Tx6q6fE8YQcHNVXAkiY9q6d+xo0rKwT38xVqr7ZD0u0iPPkUL64lIZbqBAz
+scqKmlzm8FDrypNC9Yjc8fPOLn9FX9KSYvKTr4rvx3iSIlTJabIQwj2ICCR/oLxBA==
</SessionToken>
<SecretAccessKey>
wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY
</SecretAccessKey>
<Expiration>2011-07-15T23:28:33.359Z</Expiration>
<AccessKeyId>AKIAIOSFODNN7EXAMPLE</AccessKeyId>
</Credentials>
<AssumedRoleUser>
<Arn>arn:aws-cn:sts::123456789012:assumed-role/demo/Bob</Arn>
<AssumedRoleId>ARO123EXAMPLE123:Bob</AssumedRoleId>
</AssumedRoleUser>
<PackedPolicySize>6</PackedPolicySize>
</AssumeRoleResult>
<ResponseMetadata>
<RequestId>c6104cbe-af31-11e0-8154-cbc7ccf896c7</RequestId>
</ResponseMetadata>
</AssumeRoleResponse>
Note
AssumeRole stores the policy in a packed format. AssumeRole returns the size as a percentage
of the maximum size allowed so you can adjust the calling parameters. For more information
about the size constraints on the policy, go to AssumeRole in the AWS Security Token Service API
Reference.
197
AWS Identity and Access Management User Guide
Requesting Temporary Security Credentials
AssumeRoleWithWebIdentity—Federation Through a Webbased Identity Provider
This API returns a set of temporary security credentials for federated users who are authenticated
through a public identity provider such as Login with Amazon, Facebook, Google, or any OpenID Connect
(OIDC)-compatible identity provider. This API is useful for creating mobile applications or client-based
web applications that require access to AWS in which users do not have their own AWS or IAM identities.
For more information, see About Web Identity Federation (p. 106).
Note
Instead of directly calling AssumeRoleWithWebIdentity, we recommend that you use Amazon
Cognito and the Amazon Cognito credentials provider with the AWS SDKs for mobile
development. For more information, see the following:
• Amazon Cognito Identity in the AWS Mobile SDK for Android Developer Guide
• Amazon Cognito Identity in the AWS Mobile SDK for iOS Developer Guide
If you are not using Amazon Cognito, you call the AssumeRoleWithWebIdentity action of AWS STS. This is
an unsigned call, meaning that the app does not need to have access to any AWS security credentials in
order to make the call. When you make this call, you pass the following information:
• The Amazon Resource Name (ARN) of the role that the app should assume. If your app supports
multiple ways for users to sign in, you must define multiple roles, one per identity provider. The call to
AssumeRoleWithWebIdentity should include the ARN of the role that is specific to the provider through
which the user signed in.
• The token that the app gets from the IdP after the app authenticates the user.
• The duration, which specifies how long the temporary security credentials are valid. The minimum
is 15 minutes (900 seconds) and the maximum (and the default) is 1 hour (3600 seconds). You need
to pass this value only if you want the temporary credentials to expire before 1 hour. This is separate
from the duration of a console session that you might request using these credentials. The request to
the federation endpoint for a console sign-in token takes a SessionDuration parameter that specifies
the maximum length of the console session, separately from the DurationSeconds parameter on
this API. For more information, see Creating a URL that Enables Federated Users to Access the AWS
Management Console (Custom Federation Broker) (p. 132).
• A role session name, which is a string value that you can use to identify the session. This value can be
captured and logged by CloudTrail to help you distinguish between your role users during an audit.
• Optionally, a policy (in JSON format). This policy is combined with the policy associated with the role.
If specified, the permissions are the intersection of those granted to the role and those granted by
this policy. You can use this policy to you further restrict the access permissions that are associated
with the temporary credentials, beyond the restrictions already established by the role access policy.
Note that this policy cannot be used to elevate privileges beyond what the assumed role is allowed to
access.
Note
Because a call to AssumeRoleWithWebIdentity is not signed (encrypted), you should only
include this optional policy if the request is not being transmitted through an untrusted
intermediary who could alter the policy to remove the restrictions.
When you call AssumeRoleWithWebIdentity, AWS verifies the authenticity of the token. For example,
depending on the provider, AWS might make a call to the provider and include the token that the
app has passed. Assuming that the identity provider validates the token, AWS returns the following
information to you:
• A set of temporary security credentials. These consist of an access key ID, a secret access key, and a
session token.
198
AWS Identity and Access Management User Guide
Requesting Temporary Security Credentials
• The role ID and the ARN of the assumed role.
• A SubjectFromWebIdentityToken value that contains the unique user ID.
When you have the temporary security credentials, you can use them to make AWS API calls. This is
the same process as making an AWS API call with long-term security credentials, except that you must
include the session token, which lets AWS verify that the temporary security credentials are valid.
Your app should cache the credentials. As noted, by default the credentials expire after an hour. If you
are not using the AmazonSTSCredentialsProvider action in the AWS SDK, it's up to you and your app to
call AssumeRoleWithWebIdentity again to get a new set of temporary security credentials before the old
ones expire.
AssumeRoleWithSAML—Federation Through an Enterprise
Identity Provider Compatible with SAML 2.0
This API returns a set of temporary security credentials for federated users who are authenticated by
your organization's existing identity system and who use SAML 2.0 (Security Assertion Markup Language)
to pass authentication and authorization information to AWS. This API is useful in organizations that
have integrated their identity systems (such as Windows Active Directory or OpenLDAP) with software
that can produce SAML assertions to provide information about user identity and permissions (such as
Active Directory Federation Services or Shibboleth). For more information, see About SAML 2.0-based
Federation (p. 112).
This is an unsigned call, which means that the app does not need to have access to any AWS security
credentials in order to make the call. When you make this call, you pass the following information:
• The Amazon Resource Name (ARN) of the role that the app should assume.
• The ARN of the SAML provider created in IAM that describes the identity provider.
• The SAML assertion, encoded in base-64, that was provided by the SAML identity provider in its
authentication response to the sign-in request from your app.
• The duration, which specifies how long the temporary security credentials are valid. The maximum
(and the default) is 1 hour (3600 seconds). You need to pass this value only if you want the
temporary credentials to expire before 1 hour. The minimum duration for the credentials is 15
minutes (900 seconds). This is separate from the duration of a console session that you might
request using these credentials. The request to the federation endpoint for a console sign-in token
takes a SessionDuration parameter that specifies the maximum length of the console session,
separately from the DurationSeconds parameter on this API. For more information, see Creating
a URL that Enables Federated Users to Access the AWS Management Console (Custom Federation
Broker) (p. 132).
• A policy (in JSON format). This policy is combined with the policy associated with the role. If specified,
the permissions are the intersection of those granted to the role and those granted by this policy. You
can use this policy to further restrict the access permissions that are associated with the temporary
credentials, beyond the restrictions already established by the role access policy. Note that this policy
cannot be used to elevate privileges beyond what the assumed role is allowed to access.
When you call AssumeRoleWithSAML, AWS verifies the authenticity of the SAML assertion. Assuming that
the identity provider validates the assertion, AWS returns the following information to you:
• A set of temporary security credentials. These consist of an access key ID, a secret access key, and a
session token.
• The role ID and the ARN of the assumed role.
• An Audience value that contains the value of the Recipient attribute of the SubjectConfirmationData
element of the SAML assertion.
• An Issuer value that contains the value of the Issuer element of the SAML assertion.
199
AWS Identity and Access Management User Guide
Requesting Temporary Security Credentials
• A NameQualifier element that contains a hash value built from the Issuer value, the AWS account
ID, and the friendly name of the SAML provider. When combined with the Subject element, they can
uniquely identify the federated user.
• A Subject element that contains the value of the NameID element in the Subject element of the SAML
assertion.
• A SubjectType element that indicates the format of the Subject element. The value can be
persistent, transient, or the full Format URI from the Subject and NameID elements used in your
SAML assertion. For information about the NameID element's Format attribute, see Configuring SAML
Assertions for the Authentication Response (p. 125).
When you have the temporary security credentials, you can use them to make AWS API calls. This is
the same process as making an AWS API call with long-term security credentials, except that you must
include the session token, which lets AWS verify that the temporary security credentials are valid.
Your app should cache the credentials. By default the credentials expire after an hour. If you are not
using the AmazonSTSCredentialsProvider action in the AWS SDK, it's up to you and your app to call
AssumeRoleWithSAML again to get a new set of temporary security credentials before the old ones expire.
GetFederationToken—Federation Through a Custom Identity
Broker
This API returns a set of temporary security credentials for federated users. This API differs from
AssumeRole in that the default expiration period is substantially longer (up to 36 hours instead of up
to 1 hour). The longer expiration period can help reduce the number of calls to AWS because you do
not need to get new credentials as often. For more information, see Requesting Temporary Security
Credentials (p. 195).
The GetFederationToken call returns temporary security credentials that consist of the security
token, access key, secret key, and expiration. You can use GetFederationToken if you want to manage
permissions inside your organization (for example, using the proxy application to assign permissions). To
view a sample application that uses GetFederationToken, go to Identity Federation Sample Application
for an Active Directory Use Case in the AWS Sample Code & Libraries.
The following example shows a sample request and response that uses GetFederationToken. In this
example, the request includes the name for a federated user named Jean. The Policy parameter includes
a JSON document that specifies that the resulting credentials have permissions to access only Amazon
S3. In addition to the temporary security credentials, the response includes the Amazon Resource Name
(ARN) for the federated user and the expiration time of the credentials.
Example Request
https://sts.amazonaws.com/
?Version=2011-06-15
&Action=GetFederationToken
&Name=Jean
&Policy=%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Sid%22%3A
%22Stmt1%22%2C%22Effect%22%3A%22Allow%22%2C%22Action%22%3A%22s3%3A*%22%2C%22Resource%22%3A
%22*%22%7D%5D%7D
&DurationSeconds=3600
&AUTHPARAMS
Note
The policy value shown in the example above is the URL-encoded version of this policy:
{"Version":"2012-10-17","Statement":
[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:*","Resource":"*"}]}
200
AWS Identity and Access Management User Guide
Requesting Temporary Security Credentials
Also, note that the &AUTHPARAMS parameter in the preceding example is meant as a placeholder
for the authentication information—that is, the signature—that you must include with AWS
HTTP API requests. We recommend using the AWS SDKs to create API requests, and one benefit
of doing so is that the SDKs handle request signing for you. If you must create and sign API
requests manually, go to Signing AWS Requests By Using Signature Version 4 in the Amazon
Web Services General Reference to learn how to sign a request.
Example Response
<GetFederationTokenResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<GetFederationTokenResult>
<Credentials>
<SessionToken>
AQoDYXdzEPT//////////wEXAMPLEtc764bNrC9SAPBSM22wDOk4x4HIZ8j4FZTwdQW
LWsKWHGBuFqwAeMicRXmxfpSPfIeoIYRqTflfKD8YUuwthAx7mSEI/qkPpKPi/kMcGd
QrmGdeehM4IC1NtBmUpp2wUE8phUZampKsburEDy0KPkyQDYwT7WZ0wq5VSXDvp75YU
9HFvlRd8Tx6q6fE8YQcHNVXAkiY9q6d+xo0rKwT38xVqr7ZD0u0iPPkUL64lIZbqBAz
+scqKmlzm8FDrypNC9Yjc8fPOLn9FX9KSYvKTr4rvx3iSIlTJabIQwj2ICCEXAMPLE==
</SessionToken>
<SecretAccessKey>
wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY
</SecretAccessKey>
<Expiration>2011-07-15T23:28:33.359Z</Expiration>
<AccessKeyId>AKIAIOSFODNN7EXAMPLE;</AccessKeyId>
</Credentials>
<FederatedUser>
<Arn>arn:aws-cn:sts::123456789012:federated-user/Jean</Arn>
<FederatedUserId>123456789012:Jean</FederatedUserId>
</FederatedUser>
<PackedPolicySize>6</PackedPolicySize>
</GetFederationTokenResult>
<ResponseMetadata>
<RequestId>c6104cbe-af31-11e0-8154-cbc7ccf896c7</RequestId>
</ResponseMetadata>
</GetFederationTokenResponse>
Note
GetFederationToken stores the policy in a packed format. The action returns the size as a
percentage of the maximum size allowed so that you can adjust the calling parameters. For
more information about size constraints on the policy, go to GetFederationToken in the AWS
Security Token Service API Reference.
If you prefer to grant permissions at the resource level (for example, you attach a policy to an Amazon
S3 bucket), you can omit the Policy parameter. However, if you do not include a policy for the federated
user, the temporary security credentials will not grant any permissions. In this case, you must use
resource policies to grant the federated user access to your AWS resources.
For example, if your AWS account number is 111122223333, and you have an Amazon S3 bucket that
you want to allow Susan to access even though her temporary security credentials don't include a policy
for the bucket, you would need to ensure that the bucket has a policy with an ARN that matches Susan's
ARN, such as arn:aws-cn:sts::111122223333:federated-user/Susan.
GetSessionToken—Temporary Credentials for Users in
Untrusted Environments
This API returns a set of temporary security credentials to an existing IAM user. Because the credentials
are temporary, they provide enhanced security when you have an IAM user who accesses your resources
through a less secure environment, such as a mobile device or web browser. For more information, see
201
AWS Identity and Access Management User Guide
Requesting Temporary Security Credentials
Requesting Temporary Security Credentials (p. 195) or GetSessionToken in the AWS Security Token
Service API Reference.
By default, temporary security credentials for an IAM user are valid for a maximum of 12 hours, but you
can request a duration as short as 15 minutes or as long as 36 hours.
GetSessionToken returns temporary security credentials consisting of a security token, an access
key ID, and a secret access key. The following example shows a sample request and response using
GetSessionToken. The response also includes the expiration time of the temporary security credentials.
Example Request
https://sts.amazonaws.com/
?Version=2011-06-15
&Action=GetSessionToken
&DurationSeconds=3600
&AUTHPARAMS
Note
The &AUTHPARAMS parameter in the preceding example is meant as a placeholder for the
authentication information—that is, the signature—that you must include with AWS HTTP API
requests. We recommend using the AWS SDKs to create API requests, and one benefit of doing
so is that the SDKs handle request signing for you. If you must create and sign API requests
manually, go to Signing AWS Requests By Using Signature Version 4 in the Amazon Web Services
General Reference to learn how to sign a request.
Example Response
<GetSessionTokenResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<GetSessionTokenResult>
<Credentials>
<SessionToken>
AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/L
To6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3z
rkuWJOgQs8IZZaIv2BXIa2R4OlgkBN9bkUDNCJiBeb/AXlzBBko7b15fjrBs2+cTQtp
Z3CYWFXG8C5zqx37wnOE49mRl/+OtkIKGO7fAE
</SessionToken>
<SecretAccessKey>
wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY
</SecretAccessKey>
<Expiration>2011-07-11T19:55:29.611Z</Expiration>
<AccessKeyId>AKIAIOSFODNN7EXAMPLE</AccessKeyId>
</Credentials>
</GetSessionTokenResult>
<ResponseMetadata>
<RequestId>58c5dbae-abef-11e0-8cfe-09039844ac7d</RequestId>
</ResponseMetadata>
</GetSessionTokenResponse>
Note
The call to AWS STS can be to the global endpoint or to any of the regional endpoints for which
you activate your AWS account. For more information, see the AWS STS section of Regions and
Endpoints.
Also, note that the &AUTHPARAMS parameter in the preceding example is meant as a placeholder
for the authentication information—that is, the signature—that you must include with AWS
HTTP API requests. We recommend using the AWS SDKs to create API requests, and one benefit
of doing so is that the SDKs handle request signing for you. If you must create and sign API
requests manually, go to Signing AWS Requests By Using Signature Version 4 in the Amazon
Web Services General Reference to learn how to sign a request.
202
AWS Identity and Access Management User Guide
Requesting Temporary Security Credentials
Comparing the AWS STS APIs
The following table compares features of the actions (APIs) in AWS STS that return temporary security
credentials.
Comparing your API options
AWS STS
API
Who can call
Credential Passed
lifetime
policy
(min/
support*
max/
default)
Restrictions on resulting
temporary credentials
AssumeRoleIAM user or user with
existing temporary
security credentials
15m/1hr/1hr
Yes
Cannot call GetFederationToken
or GetSessionToken.
AssumeRoleWithSAML
Any user; caller
must pass a SAML
authentication
response
that indicates
authentication from
a known identity
provider
15m/1hr/1hr
Yes
Cannot call GetFederationToken
or GetSessionToken.
AssumeRoleWithWebIdentity
Any user; caller must
pass a web identity
token that indicates
authentication from
a known identity
provider
15m/1hr/1hr
Yes
Cannot call GetFederationToken
or GetSessionToken.
GetFederationToken
IAM user
IAM user: Yes
15m/36hr/12hr
Cannot call IAM APIs directly.
SSO to console is allowed.*
Cannot call AWS STS APIs.
GetSessionToken
IAM user
IAM user: No
15m/36hr/12hr
Cannot call IAM APIs unless MFA
information is included with the
request.
Cannot call AWS STS APIs except
AssumeRole.
Single sign-on (SSO) to console
is not allowed, but any IAM user
with a password can sign into
the console.*
• Passed policy support. You can pass an IAM policy as a parameter to most of the AWS STS APIs to
be used in conjunction with other policies affecting the user (if any) to determine what the user is
allowed to do with the temporary credentials that result from the API call. For more information, see
the following topics:
• Permissions for AssumeRole, AssumeRoleWithSAML, and AssumeRoleWithWebIdentity (p. 208)
• Permissions for GetFederationToken (p. 210)
203
AWS Identity and Access Management User Guide
Using Temporary Security Credentials
to Request Access to AWS Resources
• Permissions for GetSessionToken (p. 213)
• Single sign-on (SSO) to the console. To support SSO, AWS lets you call a federation endpoint
(https://signin.www.amazonaws.cn/federation) and pass temporary security credentials. The
endpoint returns a token that you can use to construct a URL that signs a user directly into the console
without requiring a password. For more information, see Enabling SAML 2.0 Federated Users to
Access the AWS Management Console (p. 129) and How to Enable Cross-Account Access to the AWS
Management Console in the AWS Security Blog.
Using Temporary Security Credentials to Request
Access to AWS Resources
You can use temporary security credentials to make programmatic requests for AWS resources with the
AWS SDKs or API calls, the same way that you can use long-term security credentials such as IAM user
credentials. However, there are a few differences:
• When you make a call using temporary security credentials, the call must include a session token,
which is returned along with those temporary credentials. AWS uses the session token to validate the
temporary security credentials.
• The temporary credentials expire after a specified interval. After the credentials expire, any calls that
you make with those credentials will fail, so you must get a new set of credentials.
If you are using the AWS SDKs, the AWS Command Line Interface (AWS CLI), or the Tools for Windows
PowerShell, the way in which you get and use temporary security credentials differs depending on the
context. If you are running code, AWS CLI, or Tools for Windows PowerShell commands inside an EC2
instance, you can take advantage of roles for Amazon EC2. Otherwise, you can call an AWS STS API to
get the temporary credentials, and then use them explicitly to make calls to AWS services.
Note
You can use AWS Security Token Service (AWS STS) to create and provide trusted users with
temporary security credentials that can control access to your AWS resources. For more
information about AWS STS, see Temporary Security Credentials (p. 193). AWS STS is a global
service that has a default endpoint at https://sts.amazonaws.com. This endpoint is in the
region, although credentials that you get from this and other endpoints are valid globally
and work with services and resources in any region. You can also choose to make AWS STS
API calls to endpoints in any of the supported regions. This can reduce latency by making the
requests from servers in a region that is geographically closer to you. No matter which region
your credentials come from, they work globally. For more information, see Activating and
Deactivating AWS STS in an AWS Region (p. 218).
Contents
• Using Temporary Credentials in Amazon EC2 Instances (p. 204)
• Using Temporary Security Credentials with the AWS SDKs (p. 205)
• Using Temporary Security Credentials with the AWS CLI (p. 205)
• Using Temporary Security Credentials with the Tools for Windows PowerShell (p. 206)
• Using Temporary Security Credentials with APIs (p. 207)
• More Information (p. 207)
Using Temporary Credentials in Amazon EC2 Instances
If you want to run AWS CLI commands or code inside an EC2 instance, the recommended way to get
credentials is to use roles for Amazon EC2. You create an IAM role that specifies the permissions that you
204
AWS Identity and Access Management User Guide
Using Temporary Security Credentials
to Request Access to AWS Resources
want to grant to applications that run on the EC2 instances. When you launch the instance, you associate
the role with the instance.
Applications, AWS CLI, and Tools for Windows PowerShell commands that run on the instance can then
get automatic temporary security credentials from the instance metadata. You do not have to explicitly
get the temporary security credentials—the AWS SDKs, AWS CLI, and Tools for Windows PowerShell
automatically get the credentials from the EC2 instance metadata service and use them. The temporary
credentials have the permissions that you define for the role that is associated with the instance.
For more information and for examples, see the following:
• Using IAM Roles to Grant Access to AWS Resources on Amazon Elastic Compute Cloud — AWS SDK for
Java
• Granting Access Using an IAM Role — AWS SDK for .NET
• Creating a Role — AWS SDK for Ruby
Using Temporary Security Credentials with the AWS SDKs
To use temporary security credentials in code, you programmatically call an AWS STS API like
AssumeRole, extract the resulting credentials and session token, and then use those values as credentials
for subsequent calls to AWS. The following example shows pseudocode for how to use temporary
security credentials if you're using an AWS SDK:
assumeRoleResult = AssumeRole(role-arn);
tempCredentials = new SessionAWSCredentials(
assumeRoleResult.AccessKeyId,
assumeRoleResult.SecretAccessKey,
assumeRoleResult.SessionToken);
s3Request = CreateAmazonS3Client(tempCredentials);
For an example written in Python (using the AWS SDK for Python (Boto)) that shows how to call
AssumeRole to get temporary security credentials, and then use those credentials to make a call to
Amazon S3, see Switching to an IAM Role (API) (p. 176).
For details about how to call AssumeRole, GetFederationToken, and other APIs, and about how to get
the temporary security credentials and session token from the result, see the documentation for the
SDK that you're working with. You can find the documentation for all the AWS SDKs on the main AWS
documentation page.
You must make sure that you get a new set of credentials before the old ones expire. In some SDKs, you
can use a provider that manages the process of refreshing credentials for you; check the documentation
for the SDK you're using.
Using Temporary Security Credentials with the AWS CLI
You can use temporary security credentials with the AWS CLI. This can be useful for testing policies.
Using the AWS CLI, you can call an AWS STS API like AssumeRole or GetFederationToken and then
capture the resulting output. The following example shows a call to AssumeRole that sends the output to
a file. In the example, the profile parameter is assumed to be a profile in the AWS CLI configuration file
and is assumed to reference credentials for an IAM user who has permissions to assume the role.
$ aws sts assume-role --role-arn arn:aws-cn:iam::123456789012:role/role-name --rolesession-name "RoleSession1" --profile IAM-user-name > assume-role-output.txt
205
AWS Identity and Access Management User Guide
Using Temporary Security Credentials
to Request Access to AWS Resources
When the command is finished, you can extract the access key ID, secret access key, and session token
from wherever you've routed it, either manually or by using a script. You can then assign these values to
environment variables.
When you run AWS CLI commands, the AWS CLI looks for credentials in a specific order—first in
environment variables and then in the configuration file. Therefore, after you've put the temporary
credentials into environment variables, the AWS CLI uses those credentials by default. (If you specify
a profile parameter in the command, the AWS CLI skips the environment variables and looks in the
configuration file, which lets you override the credentials in the environment variables if you need to.)
The following example shows how you might set the environment variables for temporary security
credentials and then call an AWS CLI command. Because no profile parameter is included in the AWS
CLI command, the AWS CLI looks for credentials first in environment variables and therefore uses the
temporary credentials.
Linux
$
$
$
$
export AWS_ACCESS_KEY_ID=AKIAI44QH8DHBEXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoDYXdzEJr...<remainder of security token>
aws ec2 describe-instances --region us-west-1
Windows
C:\>
C:\>
C:\>
C:\>
SET
SET
SET
aws
AWS_ACCESS_KEY_ID=AKIAI44QH8DHBEXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SESSION_TOKEN=AQoDYXdzEJr...<remainder of token>
ec2 describe-instances --region us-west-1
Using Temporary Security Credentials with the Tools for
Windows PowerShell
You can use temporary security credentials with the AWS Tools for Windows PowerShell. This can be
useful for testing policies.
With the Tools for Windows PowerShell, you can call an AWS STS API action like AssumeRole or
GetFederationToken and then capture the resulting output. The following example shows a PowerShell
command that calls AssumeRole and stores the resulting role object in the variable $role. The
StoredCredentials parameter is assumed to be a profile in the Tools for Windows PowerShell
configuration file set up by Set-AWSCredentials or Initialized-AWSDefaults and is assumed to
reference credentials for an IAM user who has permissions to assume the role.
PS C:\> $role = Use-STSRole -RoleArn arn:aws-cn:iam::123456789012:role/MySampleRole RoleSessionName RoleSession1 -StoredCredentials IAM-user-name
When the command is finished, you can extract the access key ID, secret access key, and session token
from the variable.
PS C:\> $role.AssumedRoleUser
Arn
AssumedRoleId
--------------arn:aws-cn:sts::123456789012:assumed-role/clirole/RoleSession1
AROAJVIFQ5TJISRUTVTUE:RoleSession1
PS C:\> $role.Credentials.AccessKeyId
AKIAIOSFODNN7EXAMPLE
206
AWS Identity and Access Management User Guide
Controlling Permissions for Temporary Security Credentials
PS C:\> $role.Credentials.SecretAccessKey
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
PS C:\> $role.Credentials.SessionToken
AQoDYXdzEPT//////////
wEXAMPLEtc764bNrC9SAPBSM22wDOk4x4HIZ8j4FZTwdQWLWsKWHGBuFqwAeMicRXmxfpSPfIeoIYRqT
flfKD8YUuwthAx7mSEI/qkPpKPi/
kMcGdQrmGdeehM4IC1NtBmUpp2wUE8phUZampKsburEDy0KPkyQDYwT7WZ0wq5VSXDvp75YU9
HFvlRd8Tx6q6fE8YQcHNVXAkiY9q6d+xo0rKwT38xVqr7ZD0u0iPPkUL64lIZbqBAz
+scqKmlzm8FDrypNC9Yjc8fPOLn9FX9KSYv
KTr4rvx3iSIlTJabIQwj2ICCR/oLxBA==
PS C:\> $role.Credentials.Expiration
Wednesday, July 08, 2015 3:22:32 PM
The following example shows how you might use the variable-stored credentials and then use them to
call an AWS CLI command.
PS C:\> Get-EC2Instance -Region us-west-2 -Credential $role.Credentials
Using Temporary Security Credentials with APIs
If you're making direct HTTPS API requests to AWS, you can sign those requests with the temporary
security credentials that you get from the AWS Security Token Service (AWS STS). To do this, you use the
access key ID and secret access key that you receive from AWS STS the same way you would use longterm credentials to sign a request. You also add to your API request the session token that you receive
from AWS STS. You add the session token to an HTTP header or to a query string parameter named XAmz-Security-Token. You add the session token to the HTTP header or the query string parameter, but
not both. For more information about signing HTTPS API requests, see Signing AWS API Requests in the
AWS General Reference.
More Information
For more information about using AWS STS with other AWS services, see the following links:
• Amazon S3. See Making Requests Using IAM User Temporary Credentials or Making Requests Using
Federated User Temporary Credentials in the Amazon Simple Storage Service Developer Guide .
• Amazon SNS. See Using Temporary Security Credentials in the Amazon Simple Notification Service
Developer Guide.
• Amazon SQS. See Using Temporary Security Credentials in the Amazon Simple Queue Service Developer
Guide.
• Amazon SimpleDB. See Using Temporary Security Credentials in the Amazon SimpleDB Developer
Guide.
Controlling Permissions for Temporary Security
Credentials
You can use AWS Security Token Service (AWS STS) to create and provide trusted users with temporary
security credentials that can control access to your AWS resources. For more information about AWS STS,
see Temporary Security Credentials (p. 193). After AWS STS issues temporary security credentials, they
are valid through the expiration period and cannot be revoked. However, the permissions assigned to
temporary security credentials are evaluated each time a request is made that uses the credentials, so
you can achieve the effect of revoking the credentials by changing their access rights after they have
been issued.
207
AWS Identity and Access Management User Guide
Controlling Permissions for Temporary Security Credentials
The following topics assume you have a working knowledge of AWS permissions and policies. For more
information on these topics, see Access Management (p. 222).
Topics
• Permissions for AssumeRole, AssumeRoleWithSAML, and AssumeRoleWithWebIdentity (p. 208)
• Permissions for GetFederationToken (p. 210)
• Permissions for GetSessionToken (p. 213)
• Disabling Permissions for Temporary Security Credentials (p. 214)
• Granting Permissions to Create Temporary Security Credentials (p. 216)
Permissions for AssumeRole, AssumeRoleWithSAML, and
AssumeRoleWithWebIdentity
The permission policy of the role that is being assumed determines the permissions for the temporary
security credentials returned by AssumeRole, AssumeRoleWithSAML, and AssumeRoleWithWebIdentity. You
define these permissions when you create or update the role.
Optionally, you can pass a separate policy as a parameter of the AssumeRole, AssumeRoleWithSAML, or
AssumeRoleWithWebIdentity API call. You use the passed policy to scope down the permissions assigned
to the temporary security credentials—that is, to allow only a subset of the permissions that are allowed
by the permission policy of the role. You cannot use the passed policy to grant permissions that are in
excess of those allowed by the permission policy of the role; it is a filter only. If you do not pass a policy
as a parameter of the AssumeRole, AssumeRoleWithSAML, or AssumeRoleWithWebIdentity API call, then
the permissions attached to the temporary security credentials are the same as the permissions defined
in the role permissions policy of the role that is being assumed.
When the temporary security credentials returned by AssumeRole, AssumeRoleWithSAML, and
AssumeRoleWithWebIdentity are used to make AWS requests, AWS determines whether to allow or deny
access by evaluating all of the following policies:
• The combination of the role permission policy of the role that was assumed and the policy passed as a
parameter to the API, as discussed previously.
• Any resource-based policies (such as an Amazon S3 bucket policy) attached to the resource that is
being accessed by the temporary security credentials.
AWS uses all of these policies to arrive at an "allow" or "deny" authorization decision that follows the IAM
policy evaluation logic (p. 405).
It is important to understand that the policies that are attached to the IAM user or the credentials that
made the original call to AssumeRole are not evaluated by AWS when making the "allow" or "deny"
authorization decision. The user temporarily gives up its original permissions in favor of the permissions
assigned by the assumed role. In the case of the AssumeRoleWithSAML and AssumeRoleWithWebIdentity
APIs, there are no policies to evaluate because the caller of the API is not an AWS identity.
Example: Assigning Permissions Using AssumeRole
You can use the AssumeRole API action with different kinds of policies. Here are a few examples.
Role Permission Policy
In this example, you call the AssumeRole API and do not include the optional Policy parameter. The
permissions assigned to the temporary security credentials that are returned by the call to AssumeRole—
that is, the permissions assigned to the assumed role user—are determined by the permission policy of
the role being assumed. The following example is a role permission policy that grants the assumed role
208
AWS Identity and Access Management User Guide
Controlling Permissions for Temporary Security Credentials
user permission to list all objects contained in an S3 bucket named productionapp, and to get, put, and
delete objects within that bucket.
Example Role Permission Policy
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws-cn:s3:::productionapp"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": "arn:aws-cn:s3:::productionapp/*"
}
]
Policy Passed as a Parameter
Imagine that you want to allow a user to assume the same role as in the previous example, but you want
the assumed role user to have permission only to get and put objects—but not delete objects—in the
productionapp S3 bucket. One way to accomplish this is to create a new role and specify the desired
permissions in that role's permission policy. Another way to accomplish this is to call the AssumeRole
API and include the optional Policy parameter as part of the API call. For example, imagine that the
following policy is passed as a parameter of the API call. The assumed role user would have permissions
to perform only these actions:
• List all objects in the productionapp bucket.
• Get and put objects in the productionapp bucket.
Note that because the s3:DeleteObject permission is not specified in the following policy, it is filtered
out and the assumed role user is not granted the s3:DeleteObject permission. When you pass a policy as
a parameter of the AssumeRole API call, the effective permissions of the assumed role user consist of only
those permissions that are granted both in the role permission policy and the passed policy.
Example Policy Passed with AssumeRole API call
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws-cn:s3:::productionapp"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject"
],
"Resource": "arn:aws-cn:s3:::productionapp/*"
209
AWS Identity and Access Management User Guide
Controlling Permissions for Temporary Security Credentials
}
]
}
Resource-based Policy
Some AWS resources support resource-based policies, and these policies provide another mechanism
to define permissions that affect temporary security credentials. Only a few resources, like Amazon S3
buckets, Amazon SNS topics, and Amazon SQS queues support resource-based policies. The following
example expands on the previous examples, using an S3 bucket named productionapp. The following
policy is attached to the bucket.
When you attach the following policy to the productionapp bucket, all users are denied permission to
delete objects from the bucket (note the Principal element in the policy). This includes all assumed
role users, even though the role permission policy grants the DeleteObject permission. An explicit Deny
statement always takes precedence over an explicit Allow statement.
Example Bucket Policy
{
}
"Version": "2012-10-17",
"Statement": {
"Principal": {"AWS": "*"},
"Effect": "Deny",
"Action": "s3:DeleteObject",
"Resource": "arn:aws-cn:s3:::productionapp/*"
}
For more information about how multiple policies are combined and evaluated by AWS, see IAM Policy
Evaluation Logic (p. 405).
Permissions for GetFederationToken
The permissions for the temporary security credentials returned by GetFederationToken are determined
by a combination of the following:
• The policy or policies that are attached to the IAM user whose credentials are used to call
GetFederationToken.
• The policy that is passed as a parameter in the call.
The passed policy is attached to the temporary security credentials that result from the
GetFederationToken API call—that is, to the federated user. When the federated user makes an AWS
request, AWS evaluates the policy attached to the federated user in combination with the policy or
policies attached to the IAM user whose credentials were used to call GetFederationToken.
Important
AWS allows the federated user's request only when both the attached policy and the IAM user
policy explicitly allow the federated user to perform the requested action.
The permissions assigned to the federated user are defined in one of two places:
• The policy passed as a parameter of the GetFederationToken API call. (This is most common.)
• A resource-based policy that explicitly names the federated user in the Principal element of the
policy. (This is less common.)
This means that in most cases if you do not pass a policy with the GetFederationToken API call, the
resulting temporary security credentials have no permissions. The only exception is when the credentials
210
AWS Identity and Access Management User Guide
Controlling Permissions for Temporary Security Credentials
are used to access a resource that has a resource-based policy that specifically references the federated
user in the Principal element of the policy.
The following figures show a visual representation of how the policies interact to determine permissions
for the temporary security credentials returned by a call to GetFederationToken.
Example: Assigning Permissions Using GetFederationToken
You can use the GetFederationToken API action with different kinds of policies. Here are a few examples.
Policy Attached to the IAM User
In this example, you have a browser-based client application that relies on two back-end web services.
One back-end service is your own authentication server that uses your own identity system to
authenticate the client application. The other back-end service is an AWS service that provides some
of the client application's functionality. The client application is authenticated by your server, and your
server creates or retrieves the appropriate access policy. Your server then calls the GetFederationToken
API to obtain temporary security credentials, and returns those credentials to the client application.
The client application can then make requests directly to the AWS service with the temporary security
credentials. This architecture allows the client application to make AWS requests without embedding
long-term AWS credentials.
Your authentication server calls the GetFederationToken API with the long-term security credentials
of an IAM user named token-app, but the long-term IAM user credentials remain on your server and
are never distributed to the client. The following example policy is attached to the token-app IAM user
and defines the broadest set of permissions that your federated users (clients) will need. Note that the
sts:GetFederationToken permission is required for your authentication service to obtain temporary
security credentials for the federated users.
Note
AWS provides a sample Java application to serve this purpose, which you can download here:
Token Vending Machine for Identity Registration - Sample Java Web Application.
Example Policy Attached to IAM User token-app that Calls GetFederationToken
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:GetFederationToken",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "*"
},
211
AWS Identity and Access Management User Guide
Controlling Permissions for Temporary Security Credentials
{
"Effect": "Allow",
"Action": "sqs:*",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "*"
},
{
}
]
}
"Effect": "Allow",
"Action": "sns:*",
"Resource": "*"
Although the preceding policy grants several permissions, by itself it is not enough to grant any
permissions to the federated user. If the IAM user that has the permissions defined in the preceding
policy calls GetFederationToken and does not pass a policy as a parameter of the API call, the resulting
federated user has no effective permissions.
Policy Passed as Parameter
The most common way to ensure that the federated user is assigned appropriate permission is to pass a
policy as a parameter of the GetFederationToken API call. Expanding on our previous example, imagine
that GetFederationToken is called with the credentials of the IAM user token-app and imagine that the
following policy is passed as a parameter of the API call. The federated user would have permission to
perform only these actions:
• List the contents of the Amazon S3 bucket named productionapp.
• Perform the Amazon S3 GetObject, PutObject, and DeleteObject actions on items in the
productionapp bucket.
The federated user is assigned these permissions because the permissions have been granted to both the
IAM user who called GetFederationToken (via the policy attached to the IAM user) and to the federated
user (via the passed policy). The federated user could not perform actions in Amazon SNS, Amazon SQS,
Amazon DynamoDB, or in any S3 bucket except productionapp, even though those permissions are
granted to the IAM user associated with the GetFederationToken call. This is true because the effective
permissions for the federated user consist of only those permissions that are granted in both the IAM
user policy and the passed policy.
Example Policy Passed as Parameter of GetFederationToken API call
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": ["arn:aws-cn:s3:::productionapp"]
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
212
AWS Identity and Access Management User Guide
Controlling Permissions for Temporary Security Credentials
}
]
}
"Resource": ["arn:aws-cn:s3:::productionapp/*"]
Resource-based Policies
Some AWS resources support resource-based policies, and these policies provide another mechanism to
grant permissions directly to a federated user. Only some AWS services support resource-based policies.
For example, Amazon S3 has buckets, Amazon SNS has topics, and Amazon SQS has queues that you can
attach policies to. For a list of all services that support resource-based policies, see AWS Services That
Work with IAM (p. 363) and review the "Resource Based" column of the tables. If you use one of these
services and resource-based policies makes sense for your scenario, you assign permissions directly to a
federated user by specifying the Amazon Resource Name of the federated user in the Principal element
of the resource-based policy. The following example illustrates this. The following example expands on
the previous examples, using an S3 bucket named productionapp.
The following policy is attached to the bucket. The policy allows a federated user named Carol to access
the bucket. When the following resource-based policy is in place, and the example policy described
earlier is attached to IAM user token-app, the federated user named Carol has permission to perform the
s3:GetObject, s3:PutObject, and s3:DeleteObject actions on the bucket named productionapp. This
is true even when no policy is passed as a parameter of the GetFederationToken API call. That's because
in this case the federated user named Carol has been explicitly granted permissions by the following
resource-based policy.
Remember, a federated user is granted permissions only when those permissions are explicitly granted to
both the IAM user and the federated user. Permissions can be granted to the federated user by the policy
passed as a parameter of the GetFederationToken API call, or by a resource-based policy that explicitly
names the federated user in the Principal element of the policy, as in the following example.
Example Bucket Policy that Allows Access to Federated User
{
"Version": "2012-10-17",
"Statement": {
"Principal": {"AWS": "arn:aws-cn:sts::ACCOUNT-ID-WITHOUT-HYPHENS:federated-user/
Carol"},
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": ["arn:aws-cn:s3:::productionapp/*"]
}
}
Permissions for GetSessionToken
If GetSessionToken is called with the credentials of an IAM user, the temporary security credentials have
the same permissions as the IAM user.
The temporary credentials that you get when you call GetSessionToken have the following capabilities
and limitations:
• You can use the credentials to access the AWS Management Console by passing the credentials to
the federation single sign-on endpoint at https://signin.aws.amazon.com/federation. For more
information, see Creating a URL that Enables Federated Users to Access the AWS Management Console
(Custom Federation Broker) (p. 132).
213
AWS Identity and Access Management User Guide
Controlling Permissions for Temporary Security Credentials
• You cannot use the credentials to call IAM or AWS STS APIs. You can use them to call APIs for other
AWS services.
Compare this API and its limitations and capability with the other APIs that create temporary security
credentials at Comparing the AWS STS APIs (p. 203)
Disabling Permissions for Temporary Security Credentials
Temporary security credentials are valid until they expire, and they cannot be revoked. However, because
permissions are evaluated each time an AWS request is made using the credentials, you can achieve the
effect of revoking the credentials by changing the permissions for the credentials even after they have
been issued. If you remove all permissions from the temporary security credentials, subsequent AWS
requests that use those credentials will fail. The mechanisms for changing or removing the permissions
assigned to temporary security credentials are explained in the following sections.
Note
When you update existing policy permissions, or when you apply a new policy to a user or a
resource, it may take a few minutes for policy updates to take effect.
Topics
• Denying Access to the Creator of the Temporary Security Credentials (p. 214)
• Denying Access to Temporary Security Credentials by Name (p. 215)
• Denying Access to Temporary Security Credentials Issued Before a Specific Time (p. 216)
Denying Access to the Creator of the Temporary Security Credentials
To change or remove the permissions assigned to temporary security credentials, you can change or
remove the permissions that are associated with the creator of the credentials. The creator of the
credentials is determined by the AWS STS API that was used to obtain the credentials. The mechanisms
for changing or removing the permissions associated with this creator are explained in the following
sections.
Denying Access to Credentials Created by AssumeRole, AssumeRoleWithSAML, or
AssumeRoleWithWebIdentity
To change or remove the permissions assigned to the temporary security credentials obtained by calling
the AssumeRole, AssumeRoleWithSAML, or AssumeRoleWithWebIdentity APIs, you edit or delete the role
access policy that defines the permissions for the assumed role. The temporary security credentials
obtained by assuming a role can never have more permissions than those defined in the access policy
of the assumed role, and the permissions assigned to temporary security credentials are evaluated
each time they are used to make an AWS request. When you edit or delete the access policy of a role,
the changes affect the permissions of all temporary security credentials associated with that role,
including credentials that were issued before you changed the role's access policy. You can immediately
revoke all permissions to a session by following the steps at Revoking IAM Role Temporary Security
Credentials (p. 182).
For more information about editing a role access policy, see Modifying a Role (p. 183).
Denying Access to Credentials Created by GetFederationToken or GetSessionToken
To change or remove the permissions assigned to the temporary security credentials obtained by calling
the GetFederationToken or GetSessionToken APIs, you edit or delete the policies that are attached
to the IAM user whose credentials were used to call GetFederationToken or GetSessionToken. The
temporary security credentials that were obtained by calling GetFederationToken or GetSessionToken
can never have more permissions than the IAM user whose credentials were used to obtain them. In
addition the permissions assigned to temporary security credentials are evaluated each time they are
used to make an AWS request. It is important to note that when you edit or delete the permissions of an
214
AWS Identity and Access Management User Guide
Controlling Permissions for Temporary Security Credentials
IAM user, the changes affect the IAM user as well as all temporary security credentials created by that
user.
For information about how to change or remove the policies associated with the IAM user
whose credentials were used to call GetFederationToken or GetSessionToken, seeWorking with
Policies (p. 250).
Denying Access to Temporary Security Credentials by Name
You can deny access to temporary security credentials without affecting the permissions of the IAM user
or role that created the credentials. You do this by specifying the Amazon Resource Name (ARN) of the
temporary security credentials in the Principal element of a resource-based policy. (Only some AWS
services support resource-based policies.)
Denying Access to Federated Users
For example, imagine you have an IAM user named token-app whose credentials are used to call
GetFederationToken. The GetFederationToken API call resulted in temporary security credentials
associated with a federated user named Bob (the federated user's name is taken from the Name
parameter of the API call). To deny federated user Bob's access to an S3 bucket called EXAMPLE-BUCKET,
you attach the following example bucket policy to EXAMPLE-BUCKET. It is important to note that
this affects the federated user's Amazon S3 permissions only—any other permissions granted to the
federated user remain intact.
{
}
"Version": "2012-10-17",
"Statement": {
"Principal": {"AWS": "arn:aws-cn:sts::ACCOUNT-ID-WITHOUT-HYPHENS:federated-user/Bob"},
"Effect": "Deny",
"Action": "s3:*",
"Resource": "arn:aws-cn:s3:::EXAMPLE-BUCKET"
}
You can specify the ARN of the IAM user whose credentials were used to call GetFederationToken in
the Principal element of the bucket policy, instead of specifying the federated user. In that case, the
Principal element of the preceding policy would look like this:
"Principal": {"AWS": "arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:user/token-app"}
It is important to note that specifying the ARN of IAM user token-app in the policy will result in denying
access to all federated users created by token-app, not only the federated user named Bob.
Denying Access to Assumed Role Users
It is also possible to specify the ARN of the temporary security credentials that were created by assuming
a role. The difference is the syntax used in the Principal element of the resource-based policy. For
example, a user assumes a role called Accounting-Role and specifies a RoleSessionName of Mary
(RoleSessionName is a parameter of the AssumeRole API call). To deny access to the temporary security
credentials that resulted from this API call, the Principal element of the resource-based policy would
look like this:
"Principal": {"AWS": "arn:aws-cn:sts::ACCOUNT-ID-WITHOUT-HYPHENS:assumed-role/AccountingRole/Mary"}
You can also specify the ARN of the IAM role in the Principal element of a resourced-based policy, as
in the following example. In this case, the policy will result in denying access to all temporary security
credentials associated with the role named Accounting-Role.
215
AWS Identity and Access Management User Guide
Controlling Permissions for Temporary Security Credentials
"Principal": {"AWS": "arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/Accounting-Role"}
Denying Access to Temporary Security Credentials Issued Before a Specific Time
It is possible to deny access only to temporary security credentials that were created before a specific
time and date. You do this by specifying a value for the aws:TokenIssueTime key in the Condition
element of a policy. The following policy shows an example. You attach a policy similar to the following
example to the IAM user that created the temporary security credentials. The policy denies all
permissions but only when the value of aws:TokenIssueTime is earlier than the specified date and
time. The value of aws:TokenIssueTime corresponds to the exact time at which the temporary security
credentials were created. The aws:TokenIssueTime value is only present in the context of AWS requests
that are signed with temporary security credentials, so the Deny statement in the policy will not affect
requests that are signed with the long-term credentials of the IAM user.
The following policy can also be attached to a role. In that case, the policy affects only the temporary
security credentials that were created by the role before the specified date and time. If the credentials
were created by the role after the specified date and time, the Condition element in the policy is
evaluated to false, so the Deny statement has no effect.
Example Policy that Denies All Permissions to Temporary Credentials by Issue Time
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Deny",
"Action": "*",
"Resource": "*",
"Condition": {"DateLessThan": {"aws:TokenIssueTime": "2014-05-07T23:47:00Z"}}
}
Valid users whose sessions are revoked in this way must acquire temporary credentials for a new session
to continue working. Note that the AWS CLI caches credentials until they expire. To force the CLI to
delete and refresh cached credentials that are no longer valid, run one of the following commands:
Linux, MacOS, or Unix
$ rm -r ~/.aws/cli/cache
Windows
C:\> del /s /q %UserProfile%\.aws\cli\cache
Granting Permissions to Create Temporary Security Credentials
By default, IAM users do not have permission to create temporary security credentials for federated
users and roles. However, by default IAM users can call GetSessionToken with their own permissions and
thereby create temporary credentials for others..
Note
Although you can grant permissions directly to a user, we strongly recommend that you
grant permissions to a group. This makes management of the permissions much easier. When
someone no longer needs to perform the tasks associated with the permissions, you simply
remove them from the group. If someone else needs to perform that task, add them to the
group to grant the permissions.
216
AWS Identity and Access Management User Guide
Controlling Permissions for Temporary Security Credentials
To grant an IAM group permission to create temporary security credentials for federated users or roles,
you attach a policy that grants one or both of the following privileges:
• For federated users to access an IAM role, grant access to AWS STS AssumeRole.
• For federated users that don't need a role, grant access to AWS STS GetFederationToken.
For more information about the differences between the AssumeRole and GetFederationToken APIs, see
Requesting Temporary Security Credentials (p. 195).
Example : A policy that grants permission to assume a role
The following example policy grants permission to call AssumeRole for the UpdateApp role in AWS
account 123123123123. When AssumeRole is used, the user (or application) that creates the security
credentials on behalf of a federated user cannot delegate any permissions not already specified in the
role access policy.
{
}
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws-cn:iam::123123123123:role/UpdateAPP"
}]
Example : A policy that grants permission to create temporary security credentials for a
federated user
The following example policy grants permission to access GetFederationToken.
{
}
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "sts:GetFederationToken",
"Resource": "*"
}]
Important
When you give an IAM user permission to create temporary security credentials for federated
users with GetFederationToken, be aware that this permits the IAM user to delegate his or her
own permissions. For more information about delegating permissions across IAM users and
AWS accounts, see Examples of Policies for Delegating Access (p. 164). For more information
about controlling permissions in temporary security credentials, see Controlling Permissions for
Temporary Security Credentials (p. 207).
Example : A policy that grants a user limited permission to create temporary security
credentials for federated users
When you let an IAM user call GetFederationToken to create temporary security credentials for
federated users, it is a best practice to restrict as much as practical the permissions that the IAM user is
allowed to delegate. For example, the following policy shows how to let an IAM user create temporary
security credentials only for federated users whose names start with Manager.
{
217
AWS Identity and Access Management User Guide
Activating and Deactivating AWS STS in an AWS Region
}
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "sts:GetFederationToken",
"Resource": ["arn:aws-cn:sts::123456789012:federated-user/Manager*"]
}]
Activating and Deactivating AWS STS in an AWS
Region
By default, the AWS Security Token Service (AWS STS) is available as a global service, and all AWS STS
requests go to a single endpoint at https://sts.amazonaws.com. You can optionally send your AWS STS
requests to endpoints in any of the AWS regions shown in the table that follows. All regions are enabled
by default, but you can disable any regions that you know you don't need.
You might choose to send your AWS STS requests to a regional endpoint for the following reasons:
• Reduce latency – By making your AWS STS calls to an endpoint that is geographically closer to your
services and applications, you can access AWS STS services with lower latency and better response
times.
• Build in Redundancy – By adding code to your application that switches your AWS STS API calls to
a different region, you ensure that if the first region stops responding, your application continues to
operate. This redundancy is not automatic; you must build the functionality into your code.
When you activate a region for an account, you enable the STS endpoints in that region to issue
temporary credentials for users and roles in that account when a request is made to an endpoint in the
region. The credentials are still recognized and usable globally. It is not the account of the caller, but the
account from which temporary credentials are requested that must activate the region.
For example, imagine a user in account A wants to send an sts:AssumeRole API request to the STS
regional endpoint https://sts.us-west-2.amazonaws.com. The request is for temporary credentials
for the role named Developer in account B. Because the request is to create credentials for an entity in
account B, account B must activate the us-west-2 region. Users from account A (or any other account)
can call the us-west-2 endpoint to request credentials for account B whether or not the region is
activated in their accounts.
To activate or deactivate AWS STS in a region
Note
All regions are activated by default. You need to activate a region only if it was previously
deactivated.
1.
Sign in as an IAM user with permissions to perform IAM administration tasks ("iam:*") for the
account for which you want to activate AWS STS in a new region.
2.
Open the IAM console and in the navigation pane choose Account Settings.
3.
Expand the Security Token Service Regions list, find the region that you want to use, and then
choose Activate or Deactivate.
Writing Code to Use AWS STS Regions
After you activate a region for your AWS account, you can direct AWS STS API calls to that region. The
following Java code snippet demonstrates how to configure an AWSSecurityTokenServiceClient object
to make requests from the EU (Ireland) (eu-west-1) region with the setEndpoint method.
218
AWS Identity and Access Management User Guide
Activating and Deactivating AWS STS in an AWS Region
AWSSecurityTokenServiceClient stsClient = new AWSSecurityTokenServiceClient();
stsClient.setEndpoint("sts.eu-west-1.amazonaws.com");
Important
Do not use the setRegion method to set a regional endpoint for AWS STS because, for backward
compatibility, that method continues to resolve to the original single global endpoint of
sts.amazonaws.com.
In the example, the first line instantiates an AWSSecurityTokenServiceClient object called stsClient.
The second line configures the stsClient object by calling its setEndpoint method and passing the URL
of the endpoint as the only parameter. All API calls that use this stsClient object are now directed to
the specified endpoint.
For all other language and programming environment combinations, refer to the documentation for the
relevant SDK.
Nothing else about using AWS STS in a region changes. As always, the credentials retrieved from the
AWS STS endpoint in a region are not limited to that region; you can use them globally.
The following table lists the regions and their endpoints. It indicates which ones are activated by default
and which ones you can activate or deactivate.
Region Name
Endpoint
Can be
activated/
deactivated
--Global--
sts.amazonaws.com
No
US East (Ohio)
sts.us-east-2.amazonaws.com
Yes
US East (N. Virginia)
sts.us-east-1.amazonaws.com
No
US West (N. California)
sts.us-west-1.amazonaws.com
Yes
US West (Oregon)
sts.us-west-2.amazonaws.com
Yes
Canada (Central)
sts.ca-central-1.amazonaws.com
Yes
Asia Pacific (Tokyo)
sts.ap-northeast-1.amazonaws.com
Yes
Asia Pacific (Seoul)
sts.ap-northeast-2.amazonaws.com
Yes
Asia Pacific (Mumbai)
sts.ap-south-1.amazonaws.com
Yes
Asia Pacific (Singapore)
sts.ap-southeast-1.amazonaws.com
Yes
Asia Pacific (Sydney)
sts.ap-southeast-2.amazonaws.com
Yes
EU (Frankfurt)
sts.eu-central-1.amazonaws.com
Yes
EU (Ireland)
sts.eu-west-1.amazonaws.com
Yes
EU (London)
sts.eu-west-2.amazonaws.com
Yes
South America (São Paulo) sts.sa-east-1.amazonaws.com
Note
Yes
Calls to regional endpoints, such as us-west-2.amazonaws.com, are logged in AWS CloudTrail
the same as any call to a regional service. Calls to the global endpoint, sts.amazonaws.com, are
219
AWS Identity and Access Management User Guide
Sample Applications That Use Temporary Credentials
logged as calls to a global service. For more information, see Logging IAM Events with AWS
CloudTrail (p. 323).
Sample Applications That Use Temporary Credentials
You can use AWS Security Token Service (AWS STS) to create and provide trusted users with temporary
security credentials that can control access to your AWS resources. For more information about AWS STS,
see Temporary Security Credentials (p. 193). To see how you can use AWS STS to manage temporary
security credentials, you can download the following sample applications that implement complete
example scenarios:
• Identity Federation Sample Application for an Active Directory Use Case. Demonstrates how to use
permissions that are tied to a user defined in Active Directory (.NET/C#) to issue temporary security
credentials for accessing Amazon S3 files and buckets.
• AWS Management Console Federation Proxy Sample Use Case. Demonstrates how to create a custom
federation proxy that enables single sign-on (SSO) so that existing Active Directory users can sign into
the AWS Management Console (.NET/C#).
• Integrate Shibboleth with AWS Identity and Access Management. Shows how to use Shibboleth and
SAML (p. 112) to provide users with single sign-on (SSO) access to the AWS Management Console.
Samples for Web Identity Federation
The following sample applications illustrate various ways to use web identity federation, which lets you
trade authentication from a known identity provider like Login with Amazon, Amazon Cognito, Facebook,
or Google for temporary AWS security credentials that your app can use to access AWS services.
Note
As an alternative to the approaches that are illustrated in the following samples, we recommend
you use Amazon Cognito with the AWS SDKs for mobile development. Amazon Cognito is
the simplest way to manage identity for mobile apps, and it provides additional features like
synchronization and cross-device identity. For more information about Amazon Cognito, see
Amazon Cognito Identity in the AWS Mobile SDK for Android Developer Guide and Authenticate
Users with Amazon Cognito Identity in the AWS Mobile SDK for iOS Developer Guide.
• Web Identity Federation Playground. This website provides an interactive demonstration of web
identity federation (p. 106) and the AssumeRoleWithWebIdentity API.
• Build and Deploy a Federated Web Identity Application with AWS Elastic Beanstalk and Login with
Amazon. This blog post describes how to use AssumeRoleWithWebIdentity to obtain temporary
security credentials through web identity federation and Login with Amazon. It also explains how to
use those credentials in a Python web application that runs on Elastic Beanstalk to make calls to AWS.
• Authenticating Users of AWS Mobile Applications with a Token Vending Machine at AWS Articles
& Tutorials. This sample demonstrates a server-based proxy application that serves temporary
credentials to remote clients (such as mobile apps) so that the clients can sign web requests to AWS.
This sample can be used with the sample client that is part of the AWS Mobile SDK for Android and the
AWS Mobile SDK for iOS. For more information, see Credential Management for Mobile Applications,
which provides details on how to secure AWS resources when you use the token vending machine
(TVM) with mobile applications.
Additional Resources for Temporary Security
Credentials
The following scenarios and applications can guide you in using temporary security credentials:
220
AWS Identity and Access Management User Guide
Additional Resources for Temporary Credentials
• About Web Identity Federation (p. 106). This section discusses how to configure IAM roles when you
use web identity federation and the AssumeRoleWithWebIdentity API.
• Token Vending Machine for Identity Registration. This sample Java web application uses the
GetFederationToken API to serve temporary security credentials to remote clients.
For more information on policies and permissions in AWS see the following topics:
• Access Management (p. 222)
• IAM Policy Evaluation Logic (p. 405).
• Managing Access Permissions to Your Amazon S3 Resources in Amazon Simple Storage Service
Developer Guide.
221
AWS Identity and Access Management User Guide
Permissions
Access Management
When you create IAM users, IAM groups, or IAM roles, you must explicitly give permissions to these
entities so that users can access your AWS resources.
This section describes permissions, which are rights that you grant to a user, group, or role that define
what tasks users are allowed to perform in your AWS account. To define permissions, you use policies,
which are documents in JSON format.
To learn more, we recommend you read the following sections:
• Overview of AWS IAM Permissions (p. 222) — This section discusses types of permissions, how to
grant them, and how to manage permissions.
• Overview of IAM Policies (p. 232) — This section discusses how to specify what actions are allowed,
which resources to allow the actions on, and what the effect will be when the user requests access to
the resources.
• Working with Policies (p. 250) — This section describes how to create and manage policies by using
the AWS Management Console, the AWS CLI, and the IAM API.
• Testing IAM Policies with the IAM Policy Simulator (p. 283) — This section describes how to test user
and group policies using the IAM Policy Simulator.
• Using Policy Validator (p. 292) — This section describes how to use the Policy Validator when you
have policies that do not comply with the AWS policy grammar.
• AWS IAM Policy Reference (p. 373) — This section describes the elements, variables, and evaluation
logic used in policies.
• Example Policies for Administering IAM Resources (p. 227) — This section lists policies that let users
perform tasks specific to IAM, like administer users, groups, and credentials.
• Example Policies (p. 298) — This section lists policies that let users perform tasks with other AWS
services, like Amazon S3, Amazon EC2, and DynamoDB.
Overview of AWS IAM Permissions
Permissions let you specify who has access to AWS resources, and what actions they can perform on
those resources. Every IAM user starts with no permissions. In other words, by default, users can do
222
AWS Identity and Access Management User Guide
Identity-Based (IAM) Permissions
and Resource-Based Permissions
nothing, not even view their own access keys. To give a user permission to do something, you can add the
permission to the user (that is, attach a policy to the user) or add the user to a group that has the desired
permission.
For example, you might grant a user permission to list his or her own access keys. You might also expand
that permission and also let each user create, update, and delete their own keys.
When you give permissions to a group, all users in that group get those permissions. For example, you
can give the Admins group permission to perform any of the IAM actions on any of the AWS account
resources. Another example: You can give the Managers group permission to describe the AWS account's
Amazon EC2 instances.
For information about how to delegate basic permissions to your users, groups, and roles, see Delegating
Permissions to Administer IAM Users, Groups, and Credentials (p. 225). For additional examples of
policies that illustrate basic permissions, see Example Policies for Administering IAM Resources (p. 227).
Identity-Based (IAM) Permissions and Resource-Based
Permissions
Permissions can be assigned in two ways: as identity-based or as resource-based.
• Identity-based IAM permissions are attached to an IAM user, group, or role. These permissions let
you specify what that user, group, or role can do. For example, you can assign permissions to the IAM
user named Bob, stating that he has permission to use the Amazon Elastic Compute Cloud (Amazon
EC2) RunInstances action and that he has permission to get items from an Amazon DynamoDB
table named MyCompany. The user Bob might also be granted access to manage his own IAM security
credentials. Identity-based permissions can be managed or inline (p. 235).
• Resource-based permissions are attached to a resource. You can specify resource-based permissions
for Amazon S3 buckets, Amazon Glacier vaults, Amazon SNS topics, Amazon SQS queues, and AWS
Key Management Service encryption keys. Resource-based permissions let you specify who has access
to the resource and what actions they can perform on it. Resource-based policies are inline only, not
managed.
Note
There's a difference between resource-based permissions and resource-level permissions.
Resource-based permissions are permissions you can attach directly to a resource, as described
in this topic. Resource-level permissions refers to the ability to specify not just what actions
users can perform, but which resources they're allowed to perform those actions on. Some AWS
services let you specify permissions for actions, but don't let you specify the individual resources
for those actions. Other services let you specify permissions for a combination of actions and
individual resources.
Resource-based permissions are supported only by some AWS services. For a list of which
services support resource-based and resource-level permissions, see AWS Services That Work
with IAM (p. 363).
The following figure illustrates both types of permissions. The first column shows permissions attached
to identities (two users and two groups). Some of those permissions identify specific resources that the
actions can be used against. Those actions support resource-level permissions. The second column shows
permissions attached to resources. Those services support resource-based permissions.
223
AWS Identity and Access Management User Guide
Identity-Based (IAM) Permissions
and Resource-Based Permissions
Note
When you attach a policy to an AWS resource (including the trust policy of an IAM role), AWS
validates, processes, and transforms the policy you write before storing it. When AWS returns
the policy in response to a user query, AWS transforms the policy back into a human-readable
format. This can result in differences in what you see in the policy: non-significant whitespace
can be removed, and elements within JSON maps can be re-ordered. Because of these possible
changes, you should not compare JSON policy documents as strings.
A user who has specific permissions might request a resource that also has permissions attached to it. In
that case, both sets of permissions are evaluated when AWS determines whether to grant access to the
resource. For information about how policies are evaluated, see IAM Policy Evaluation Logic (p. 405).
Note
Amazon S3 supports policies both for IAM users and for resources (referred to in Amazon S3
as bucket policies). In addition, Amazon S3 supports a permission mechanism known as an ACL
that's independent of IAM policies and permissions. You can use IAM policies in combination
with Amazon S3 ACLs. For more information, see Access Control in the Amazon Simple Storage
Service Developer Guide.
224
AWS Identity and Access Management User Guide
Resource Creators Do Not Automatically Have Permissions
Resource Creators Do Not Automatically Have
Permissions
Someone using the AWS account's security credentials has permission to perform any action on resources
that belong to the account. However, this isn't true for IAM users. An IAM user might be granted access to
create a resource, but the user's permissions, even for that resource, are limited to what's been explicitly
granted. The user's permission can be revoked at any time by the account owner or by another user who
has been granted access to manage user permissions.
Granting Permissions Across AWS Accounts
You can directly grant IAM users in your own account access to your resources. If users from another
account need access to your resources, you can create an IAM role, which is an entity that includes
permissions but that isn't associated with a specific user. Users from other accounts can then use the role
and access resources according to the permissions you've assigned to the role. For more information, see
IAM Roles (p. 97).
Note
For services that support resource-based policies as described in Identity-Based (IAM)
Permissions and Resource-Based Permissions (p. 223) (such as Amazon S3, Amazon SNS, and
Amazon SQS), an alternative to using roles is to attach a policy to the resource (bucket, topic, or
queue) that you want to share. The resource-based policy can specify the AWS account that has
permissions to access the resource.
Permissions For One Service to Access Another
Some AWS services access other AWS services. For example, Auto Scaling manages Amazon EC2
instances. Other AWS services make use of Amazon S3 buckets, Amazon SNS topics, Amazon SQS
queues, and so on.
For details about how to configure permissions properly so that an AWS service is able to accomplish the
tasks you intend, refer to the documentation for the service you are calling.
Configuring a service with an IAM role to work on your behalf
When you want to configure an AWS service to work on your behalf, you typically provide the ARN for an
IAM role that defines what the service is allowed to do. AWS checks to ensure that you have permissions
to pass a role to a service. For more information, see Granting a User Permissions to Pass a Role to an
AWS Service (p. 169).
Delegating Permissions to Administer IAM Users,
Groups, and Credentials
IAM users must explicitly be given permissions to administer users or credentials for themselves or
for other IAM users. This topic describes IAM policies that let IAM users manage other users and user
credentials.
Topics
• Overview (p. 226)
• Permissions for Working in the AWS Management Console (p. 227)
• Example Policies for Administering IAM Resources (p. 227)
225
AWS Identity and Access Management User Guide
Delegating Permissions to Administer
IAM Users, Groups, and Credentials
Overview
In general, the permissions that are required in order to administer users, groups, and credentials
correspond to the API actions for the task. For example, in order to create users, a user must have the
iam:CreateUser permission (API command: CreateUser). To allow a user to create other IAM users, you
could attach a policy like the following one to that user:
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "iam:CreateUser",
"Resource": "*"
}
In a policy, the value of the Resource element depends on the action and what resources the action can
affect. In the preceding example, the policy allows a user to create any user (* is a wildcard that matches
all strings). In contrast, a policy that allows users to change only their own access keys (API actions
CreateAccessKey and UpdateAccessKey) typically has a Resource element where the ARN includes a
variable that resolves to the current user's name, as in the following example (replace ACCOUNT-IDWITHOUT-HYPHENS with your AWS account ID):
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"iam:CreateAccessKey",
"iam:UpdateAccessKey"
],
"Resource": "arn:aws-cn:iam::accountid:user/${aws:username}"
}
In the previous example, ${aws:username} is a variable that resolves to the user name of the current
user. For more information about policy variables, see IAM Policy Variables Overview (p. 395).
Using a wildcard character (*) in the action name often makes it easier to grant permissions for all
the actions related to a specific task. For example, to allow users to perform any IAM action, you can
use iam:* for the action. To allow users to perform any action related just to access keys, you can
use iam:*AccessKey* in the Action element of a policy statement. This gives the user permission
to perform the CreateAccessKey, DeleteAccessKey, GetAccessKeyLastUsed, ListAccessKeys, and
UpdateAccessKey actions. (If an action is added to IAM in the future that has "AccessKey" in the name,
using iam:*AccessKey* for the Action element will also give the user permission to that new action.) The
following example shows a policy that allows users to perform all actions pertaining to their own access
keys (replace ACCOUNT-ID-WITHOUT-HYPHENS with your AWS account ID):
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "iam:*AccessKey*",
"Resource": "arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:user/${aws:username}"
}
Some tasks, such as deleting a group, involve multiple actions: You must first remove users from the
group, then detach or delete the group's policies, and then actually delete the group. If you want a user
226
AWS Identity and Access Management User Guide
Delegating Permissions to Administer
IAM Users, Groups, and Credentials
to be able to delete a group, you must be sure to give the user permissions to perform all of the related
actions.
Permissions for Working in the AWS Management Console
The preceding examples show policies that allow a user to perform the actions with the AWS CLI or
the AWS SDKs. If users want to use the AWS Management Console to administer users, groups, and
permissions, they need additional permissions. As users work with the console, the console issues
requests to IAM to list users and groups, get the policies associated with a user or group, get AWS
account information, and so on.
For example, if user Bob wants to use the console to change his own access keys, he goes to the IAM
console and chooses Users. This action causes the console to make a ListUsers request. If Bob doesn't
have permission for the iam:ListUsers action, the console is denied access when it tries to list users. As
a result, Bob can't get to his own name and to his own access keys, even if he has permissions for the
CreateAccessKey and UpdateAccessKey actions.
If you want to give users permissions to administer users, groups, and credentials with the AWS
Management Console, you need to include permissions for the actions that the console performs. For
some examples of policies that you can use to grant a user for these permissions, see Example Policies
for Administering IAM Resources (p. 227).
Example Policies for Administering IAM Resources
Following are examples of IAM policies that allow users to perform tasks associated with managing IAM
users, groups, and credentials. This includes policies that permit users manage their own passwords, and
access keys.
For examples of policies that let users perform tasks with other AWS services, like Amazon S3, Amazon
EC2, and DynamoDB, see Example Policies (p. 298).
Topics
• Allow Users to Manage Their Own Passwords (from the My Password Page) (p. 227)
• Allow Users to Manage Their Own Passwords, Access Keys, and SSH Keys (p. 228)
• Allow a User to List the Account's Groups, Users, Policies, and More for Reporting Purposes (p. 229)
• Allow a User to Manage a Group's Membership (p. 229)
• Allow a User to Manage IAM Users (p. 230)
• Allow Users to Set Account Password Policy (p. 231)
• Allow Users to Generate and Retrieve IAM Credential Reports (p. 231)
• Allow All IAM Actions (Admin Access) (p. 231)
Allow Users to Manage Their Own Passwords (from the My Password Page)
If the account's password policy (p. 65) is set to allow all users to change their own passwords, you don't
need to attach any permissions to individual users or groups. All users are able to go to the My Password
page (p. 73) in the AWS Management Console that lets them change their own password.
If the account's password policy is not set to allow all users to change their own passwords, you can
attach the following policy to selected users or groups to allow those users to change only their own
passwords. This policy only allows users to use the special My Password page in the console; it does not
give users permissions to work through the dashboard in the IAM console.
{
"Version": "2012-10-17",
"Statement": [
227
AWS Identity and Access Management User Guide
Delegating Permissions to Administer
IAM Users, Groups, and Credentials
{
"Effect": "Allow",
"Action": "iam:GetAccountPasswordPolicy",
"Resource": "*"
},
{
}
]
}
"Effect": "Allow",
"Action": "iam:ChangePassword",
"Resource": "arn:aws-cn:iam::account-id-without-hyphens:user/${aws:username}"
If users do not use the console to change their own password, they do not need the
iam:GetAccountPasswordPolicy permission. They can instead run the aws iam change-password
command from the AWS CLI, or make a request with the ChangePassword action.
For information about letting selected users manage passwords using the Users section of the IAM
console, see the next section.
Allow Users to Manage Their Own Passwords, Access Keys, and SSH Keys
The following policy allows users to perform these actions in the AWS Management Console:
• Create, change, or remove their own password. This includes the CreateLoginProfile,
DeleteLoginProfile, GetLoginProfile, and UpdateLoginProfile actions.
• Create or delete their own access key (access key ID and secret access key). This includes the
CreateAccessKey, DeleteAccessKey, GetAccessKeyLastUsed, ListAccessKeys, and UpdateAccessKey
actions.
• Create or delete their own SSH keys. This includes the UploadSSHPublicKey, DeleteSSHPublicKey,
GetSSHPublicKey, ListSSHPublicKeys, and UpdateSSHPublicKey actions.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:*LoginProfile",
"iam:*AccessKey*",
"iam:*SSHPublicKey*"
],
"Resource": "arn:aws-cn:iam::account-id-without-hyphens:user/${aws:username}"
},
{
"Effect": "Allow",
"Action": [
"iam:ListAccount*",
"iam:GetAccountSummary",
"iam:GetAccountPasswordPolicy",
"iam:ListUsers"
],
"Resource": "*"
}
]
The actions in the preceding policy include wildcards (for example, iam:*LoginProfile,iam:*AccessKey*,
and iam:*SSHPublicKey*). This is a convenient way to include a set of related actions. If you want to
remove permissions for any one of the related actions, you must instead list each of the individual
228
AWS Identity and Access Management User Guide
Delegating Permissions to Administer
IAM Users, Groups, and Credentials
actions. For example, if you don't want users to be able to delete a password, you must individually
list iam:CreateLoginProfile, iam:GetLoginProfile, and iam:UpdateLoginProfile, and omit
iam:DeleteLoginProfile.
The second element in the Statement arrary, including iam:GetAccountSummary,
iam:GetAccountPasswordPolicy, iam:ListAccount*, and iam:ListUsers permissions, allows the
user to see certain information on the IAM console dashboard, such as whether a password policy is
enabled, how many groups the account has, what the account URL and alias are, etc. For example, the
GetAccountSummary action returns an object that contains a collection of information about the account
that is then displayed on the IAM console dashboard.
The following policy is like the previous one but excludes the permissions that are needed only for
console access. This policy lets users manage their credentials with the AWS CLI, Tools for Windows
PowerShell, the AWS SDKs, or the IAM HTTP query API.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"iam:*LoginProfile",
"iam:*AccessKey*",
"iam:*SSHPublicKey*"
],
"Resource": "arn:aws-cn:iam::account-id-without-hyphens:user/${aws:username}"
}
Allow a User to List the Account's Groups, Users, Policies, and More for
Reporting Purposes
The following policy allows the user to call any IAM action that starts with the string Get or List.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"iam:Get*",
"iam:List*"
],
"Resource": "*"
}
The benefit of using Get* and List* actions is that if new types of entities are added to IAM in the
future, the access granted in the policy to Get* and List* all actions would automatically allow the user
to list those new entities.
Allow a User to Manage a Group's Membership
The following policy allows the user to update the membership of the group called MarketingGroup. To
use the following policy, replace ACCOUNT-ID-WITHOUT-HYPHENS with your AWS account ID.
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"iam:AddUserToGroup",
229
AWS Identity and Access Management User Guide
Delegating Permissions to Administer
IAM Users, Groups, and Credentials
"iam:RemoveUserFromGroup",
"iam:GetGroup"
}
}
],
"Resource": "arn:aws-cn:iam::account-id-without-hyphens:group/MarketingGroup"
Allow a User to Manage IAM Users
The following policy allows a user to perform all the tasks associated with managing IAM users but not
to perform actions on other entities, such as creating groups or policies. Allowed actions include these:
• Creating the user (the CreateUser action).
• Deleting the user. This task requires permissions to perform all of the following actions:
DeleteSigningCertificate, DeleteLoginProfile, RemoveUserFromGroup, and DeleteUser.
• Listing users in the account and in groups (the GetUser, ListUsers and ListGroupsForUser actions).
• Listing and removing policies for the user (the ListUserPolicies, ListAttachedUserPolicies,
DetachUserPolicy, DeleteUserPolicy actions)
• Renaming or changing the path for the user (the UpdateUser action). The Resource element must
include an ARN that covers both the source path and the target path. For more information on paths,
see Friendly Names and Paths (p. 356).
{
}
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowUsersToPerformUserActions",
"Effect": "Allow",
"Action": [
"iam:CreateUser",
"iam:ListUsers",
"iam:GetUser",
"iam:UpdateUser",
"iam:DeleteUser",
"iam:ListGroupsForUser",
"iam:ListUserPolicies",
"iam:ListAttachedUserPolicies",
"iam:DeleteSigningCertificate",
"iam:DeleteLoginProfile",
"iam:RemoveUserFromGroup",
"iam:DetachUserPolicy",
"iam:DeleteUserPolicy"
],
"Resource": "*"
},
{
"Sid": "AllowUsersToSeeStatsOnIAMConsoleDashboard",
"Effect": "Allow",
"Action": [
"iam:GetAccount*",
"iam:ListAccount*"
],
"Resource": "*"
}
]
A number of the permissions included in the preceding policy allow the user to perform tasks in the AWS
Management Console. Users who perform user-related tasks from the AWS CLI, the AWS SDKs, or the
230
AWS Identity and Access Management User Guide
Delegating Permissions to Administer
IAM Users, Groups, and Credentials
IAM HTTP query API only might not need certain permissions. For example, if users already know the
ARN of policies to detach from a user, they do not need the iam:ListAttachedUserPolicies permission.
The exact list of permissions that a user requires depends on the tasks that the user must perform while
managing other users.
The following permissions in the policy allow access to user tasks via the AWS Management Console:
• iam:GetAccount*
• iam:ListAccount*
Allow Users to Set Account Password Policy
You might give some users permissions to get and update your AWS account's password policy (p. 65).
The following example policy grants these permissions.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"iam:GetAccountPasswordPolicy",
"iam:UpdateAccountPasswordPolicy"
],
"Resource": "*"
}
Allow Users to Generate and Retrieve IAM Credential Reports
You can give users permission to generate and download a report that lists all users in your AWS account
and the status of their various credentials, including passwords, access keys, and signing certificates. The
following example policy grants these permissions.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"iam:GenerateCredentialReport",
"iam:GetCredentialReport"
],
"Resource": "*"
}
For more information about credential reports, see Getting Credential Reports for Your AWS
Account (p. 82).
Allow All IAM Actions (Admin Access)
You might give some users administrative permissions to perform all actions in IAM, including managing
passwords, access keys, and user certificates. The following example policy grants these permissions.
Warning
When you give a user full access to IAM, there is no limit to the permissions that user can grant
to him/herself or others. The user can create new IAM entities (users or roles) and grant those
entities full access to all resources in your AWS account. When you give a user full access to IAM,
you are effectively giving them full access to all resources in your AWS account. This includes
access to delete all resources. You should grant these permissions to only trusted administrators.
231
AWS Identity and Access Management User Guide
Policies
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "iam:*",
"Resource": "*"
}
Overview of IAM Policies
This section provides an overview of IAM policies. A policy is a document that formally defines
permissions.
For a complete reference to the IAM policy syntax and grammar, see AWS IAM Policy Reference (p. 373).
Topics
• Managed Policies and Inline Policies (p. 235)
• Versioning for Managed Policies (p. 240)
• Deprecated AWS Managed Policies (p. 243)
• Controlling Access to Managed Policies (p. 243)
• Creating a New Policy (p. 247)
• Working with Policies (p. 250)
• Understanding Policy Summaries in the AWS Management Console (p. 258)
• Testing IAM Policies with the IAM Policy Simulator (p. 283)
• Using Policy Validator (p. 292)
• Service Last Accessed Data (p. 293)
• Example Policies (p. 298)
Introduction
To assign permissions to a user, group, role, or resource, you create a policy, which is a document that
defines permissions. The policy document includes the following elements:
• Effect – whether the policy allows or denies access
• Action – the list of actions that are allowed or denied by the policy
• Resource – the list of resources on which the actions can occur
• Condition (Optional) – the circumstances under which the policy grants permission
To learn about these and other policy elements, see IAM Policy Elements Reference (p. 374).
Policies are documents that are created using JSON. A policy consists of one or more statements, each of
which describes one set of permissions. Here's an example of a simple policy.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws-cn:s3:::example_bucket"
}
232
AWS Identity and Access Management User Guide
Policies
You can attach this policy to an IAM user or group. If that's the only policy for the user or group, the
user or group is allowed to perform only this one action (ListBucket) on one Amazon S3 bucket
(example_bucket).
To specify resource-based permissions, you can attach a policy to the resource, such as an Amazon
SNS topic, an Amazon S3 bucket, or an Amazon Glacier vault. In that case, the policy has to include
information about who is allowed to access the resource, known as the principal. (For user-based policies,
the principal is the IAM user that the policy is attached to, or the user who gets the policy from a group.)
The following example shows a policy that might be attached to an Amazon S3 bucket and that grants
permission to a specific AWS account to perform any Amazon S3 actions in mybucket. This includes both
working with the bucket and with the objects in it. (Because the policy grants trust only to the account,
individual users in the account must still be granted permissions for the specified Amazon S3 actions.)
{
}
"Version": "2012-10-17",
"Id": "S3-Account-Permissions",
"Statement": [{
"Sid": "1",
"Effect": "Allow",
"Principal": {"AWS": ["arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:root"]},
"Action": "s3:*",
"Resource": [
"arn:aws-cn:s3:::mybucket",
"arn:aws-cn:s3:::mybucket/*"
]
}]
IAM policies control access regardless of the interface. For example, you could provide a user with a
password to access the AWS Management Console, and the policies for that user (or any groups the user
belongs to) would control what the user can do in the AWS Management Console. Or, you could provide
the user with AWS access keys for making API calls to AWS, and the policies would control what actions
the user could call through a library or client that uses those access keys for authentication.
For basic example policies that cover common scenarios, see Example Policies (p. 298).
AWS managed policies and the Policy Generator are available from the IAM console in the AWS
Management Console. For more information about creating policies in the console, see Working with
Policies (p. 250). Also, you can use the AWS Policy Generator online to create policies for AWS products
without accessing the console.
Important
You cannot save any policy that does not comply with the established policy syntax. You can
use Policy Validator to detect and correct invalid policies. One click takes you to an editor
that shows both the existing policy and a copy with the recommended changes. You can
accept the changes or make further modifications. For more information, see Using Policy
Validator (p. 292).
Note
When you apply a custom policy, IAM checks its syntax. However, because IAM evaluates policies
at run time using a specific request context (in which multiple policies might be in effect), it
cannot check the validity of all resources, actions, and permissions in a custom policy at the time
that you apply the policy. If you need help in creating a policy, we recommend using an AWS
managed policy or the Policy Generator.
Multiple Statements and Multiple Policies
You can attach more than one policy to an entity. If you have multiple permissions to grant to an entity,
you can put them in separate policies, or you can put them all in one policy.
233
AWS Identity and Access Management User Guide
Policies
Generally, each statement in a policy includes information about a single permission. If your policy
includes multiple statements, a logical OR is applied across the statements at evaluation time. Similarly,
if multiple policies are applicable to a request, a logical OR is applied across the policies at evaluation
time.
Users often have multiple policies that apply to them (but aren't necessarily attached to them).
For example, IAM user Bob could have policies attached to him, and other policies attached to the
groups he's in. In addition, he might be accessing an Amazon S3 bucket that has its own bucket policy
(resource-based policy). All applicable policies are evaluated and the result is always that access is either
granted or denied. For more information about the evaluation logic we use, see IAM Policy Evaluation
Logic (p. 405).
Policy Structure
Each policy is a JSON document. As illustrated in the following figure, a policy includes:
• Optional policy-wide information (at the top of the document)
• One or more individual statements
Each statement includes the core information about a single permission. If a policy includes multiple
statements, AWS applies a logical OR across the statements at evaluation time. If multiple policies are
applicable to a request, AWS applies a logical OR across the policies at evaluation time.
The information in a statement is contained within a series of elements. For information about these
elements, see IAM Policy Elements Reference (p. 374).
Example Policy with Multiple Statements
Policies often include multiple statements, where each statement grants permissions to a different set
of resources or grants permissions under a specific condition. For example, the following policy has three
statements, each of which grants a separate set of permissions. Assume that the user or group that
the policy is attached to is in AWS account 123456789012. (Policies can't reference resources in other
accounts.) The statements do the following:
• The first statement, with a Sid (Statement ID) element set to FirstStatement, lets users manage
their own passwords. The Resource element in this statement is "*" (which means "all resources"), but
234
AWS Identity and Access Management User Guide
Managed Policies and Inline Policies
in practice, the ChangePassword API (or equivalent change-password CLI command) affects only the
password for the user who makes the request.
• The second statement ("Sid": "SecondStatement") lets the user list all the Amazon S3 buckets in
their AWS account. The Resource element in this statement is "*" (which means "all resources"), but
because policies don't grant access to resources in other accounts, the user can list only the buckets
in their own AWS account. (This permission is necessary for the user to access a bucket from the AWS
Management Console.)
• The third statement ("Sid": "ThirdStatement") lets the user list and retrieve any object that is in a
bucket called confidential-data.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Sid": "FirstStatement",
"Effect": "Allow",
"Action": ["iam:ChangePassword"],
"Resource": "*"
},
{
"Sid": "SecondStatement",
"Effect": "Allow",
"Action": "s3:ListAllMyBuckets",
"Resource": "*"
},
{
"Sid": "ThirdStatement",
"Effect": "Allow",
"Action": [
"s3:List*",
"s3:Get*"
],
"Resource": [
"arn:aws-cn:s3:::confidential-data",
"arn:aws-cn:s3:::confidential-data/*"
]
}
]
Managed Policies and Inline Policies
Using IAM, you apply permissions to IAM users, groups, and roles (which we refer to as principal entities)
by creating policies. You can create two types of IAM, oridentity-based policies:
• Managed policies – Standalone policies that you can attach to multiple users, groups, and roles in
your AWS account. Managed policies apply only to identities (users, groups, and roles) - not resources.
You can use two types of managed policies:
• AWS managed policies – Managed policies that are created and managed by AWS. If you are new to
using policies, we recommend that you start by using AWS managed policies.
• Customer managed policies – Managed policies that you create and manage in your AWS account.
Using customer managed policies, you have more precise control over your policies than when using
AWS managed policies.
• Inline policies – Policies that you create and manage, and that are embedded directly into a single
user, group, or role. Resource-based policies are another form of inline policy. Resource-based policies
are not discussed here. For more information about resource-based policies, see Identity-Based (IAM)
Permissions and Resource-Based Permissions (p. 223).
235
AWS Identity and Access Management User Guide
Managed Policies and Inline Policies
Identity-based (IAM) policies can be either inline or managed. Resource-based policies are attached to
the resources (inline) only and are not managed.
Generally speaking, the content of the policies is the same in all cases—each kind of policy defines a set
of permissions using a common structure and a common syntax.
Note
For AWS managed policies and customer managed policies, the policy's Version element must
be set to 2012-10-17. For inline policies, the policy's Version element can be set to 2012-10-17
or to 2008-10-17. We recommend that you set the Version element to 2012-10-17 for all
policies.
For more information about the Version element, see Version (p. 375) in this guide's Policy
Element Reference.
You can use the different types of policies together. You are not limited to using only one type.
The following sections provide more information about each of the types of policies and when to use
them.
Topics
• AWS Managed Policies (p. 236)
• Customer Managed Policies (p. 237)
• Inline Policies (p. 238)
• Choosing Between Managed Policies and Inline Policies (p. 239)
AWS Managed Policies
An AWS managed policy is a standalone policy that is created and administered by AWS. Standalone
policy means that the policy has its own Amazon Resource Name (ARN) that includes the policy name.
AWS managed policies are designed to provide permissions for many common use cases. For example,
there are AWS managed policies that define typical permissions for administrators (all access), for power
users (all access except IAM), and for other various levels of access to AWS services. AWS managed
policies make it easier for you to assign appropriate permissions to users, groups, and roles than if you
had to write the policies yourself.
One particularly useful category of AWS managed policies are those designed for job functions. These
policies align closely to commonly used job functions in the IT industry. The intent is to make granting
permissions for these common job functions easy. One key advantage of using job function policies is
that they are maintained and updated by AWS as new services and APIs are introduced. For a list and
descriptions of the job function policies, see AWS Managed Policies for Job Functions (p. 415).
You cannot change the permissions defined in AWS managed policies. AWS will occasionally update the
permissions defined in an AWS managed policy. When AWS does this, the update affects all principal
entities (users, groups, and roles) that the policy is attached to. AWS is most likely to update an AWS
managed policy when a new AWS service is launched or new APIs become available for existing services,
and the policy needs to include permissions for the new service(s) or APIs. For example, the AWS
managed policy called ReadOnlyAccess provides read-only access to all AWS services and resources.
When AWS launches a new service, AWS will update the ReadOnlyAccess policy to add read-only
permissions for the new service. The updated permissions are applied to all principal entities that the
policy is attached to.
The following diagram illustrates AWS managed policies. The diagram shows three AWS managed
policies: AdministratorAccess, PowerUserAccess, and AWSCloudTrailReadOnlyAccess. Notice that
a single AWS managed policy can be attached to principal entities in different AWS accounts, and to
different principal entities in a single AWS account.
236
AWS Identity and Access Management User Guide
Managed Policies and Inline Policies
Customer Managed Policies
You can create standalone policies that you administer in your own AWS account, which we refer to as
customer managed policies. You can then attach the policies to multiple principal entities in your AWS
account. When you attach a policy to a principal entity, you give the entity the permissions that are
defined in the policy.
A great way to create a customer managed policy is to start by copying an existing AWS managed policy.
That way you know that the policy is correct at the beginning and all you need to do is customize it to
your environment.
The following diagram illustrates customer managed policies. Each policy is an entity in IAM with its
own Amazon Resource Name (ARN) that includes the policy name. Notice that the same policy can be
attached to multiple principal entities—for example, the same DynamoDB-books-app policy is attached
to two different IAM roles.
237
AWS Identity and Access Management User Guide
Managed Policies and Inline Policies
Inline Policies
An inline policy is a policy that's embedded in a principal entity (a user, group, or role)—that is, the policy
is an inherent part of the principal entity. You can create a policy and embed it in a principal entity, either
when you create the principal entity or later.
The following diagram illustrates inline policies. Each policy is an inherent part of the user, group, or
role. Notice that two roles include the same policy (the DynamoDB-books-app policy), but they are not
sharing a single policy; each role has its own copy of the policy.
238
AWS Identity and Access Management User Guide
Managed Policies and Inline Policies
Choosing Between Managed Policies and Inline Policies
The different types of policies are for different use cases. In most cases, we recommend that you use
managed policies instead of inline policies.
Managed policies provide the following features:
Reusability
A single managed policy can be attached to multiple principal entities (users, groups, and roles).
In effect, you can create a library of policies that define permissions that are useful for your AWS
account, and then attach these policies to principal entities as needed.
239
AWS Identity and Access Management User Guide
Versioning for Managed Policies
Central change management
When you change a managed policy, the change is applied to all principal entities that the policy
is attached to. For example, if you want to add permission for a new AWS API, you can update the
managed policy to add the permission. (If you're using an AWS managed policy, AWS updates to the
policy.) When the policy is updated, the changes are applied to all principal entities that the policy
is attached to. In contrast, to change an inline policy you must individually edit each principal entity
that contains the policy. For example, if a group and a role both contain the same inline policy, you
must individually edit both principal entities in order to change that policy.
Versioning and rolling back
When you make changes to a customer managed policy, the changed policy doesn't overwrite the
existing policy. Instead, IAM creates a new version of the managed policy. IAM stores up to five
versions of your customer managed policies. You can use policy versions to revert a policy to an
earlier version if you need to.
A policy version is different from a Version policy element. The Version policy element is used
within a policy and defines the version of the policy language. To learn more about policy versions,
see the section called “Versioning for Managed Policies” (p. 240). To learn more about the Version
policy element see the section called “Version” (p. 375).
Delegating permissions management
You can allow users in your AWS account to attach and detach policies while maintaining control
over the permissions defined in those policies. In effect, you can designate some users as full admins
—that is, admins that can create, update, and delete policies. You can then designate other users
as limited admins. That is, admins that can attach policies to other principal entities, but only the
policies that you have allowed them to attach.
For more information about delegating permissions management, see Controlling Access to
Managed Policies (p. 243).
Automatic updates for AWS managed policies
AWS maintains AWS managed policies and updates them when necessary (for example, to
add permissions for new AWS services), without you having to make changes. The updates are
automatically applied to the principal entities that you have attached the AWS managed policy to.
Using Inline Policies
Inline policies are useful if you want to maintain a strict one-to-one relationship between a policy and
the principal entity that it's applied to. For example, you want to be sure that the permissions in a
policy are not inadvertently assigned to a principal entity other than the one they're intended for. When
you use an inline policy, the permissions in the policy cannot be inadvertently attached to the wrong
principal entity. In addition, when you use the AWS Management Console to delete that principal entity,
the policies embedded in the principal entity are deleted as well. That's because they are part of the
principal entity.
Versioning for Managed Policies
When you make changes to a customer managed policy, and when AWS makes changes to an AWS
managed policy, the changed policy doesn't overwrite the existing policy. Instead, IAM creates a new
version of the managed policy. IAM stores up to five versions of your customer managed policies. The
following diagram illustrates this.
240
AWS Identity and Access Management User Guide
Versioning for Managed Policies
A policy version is different from a Version policy element. The Version policy element is used within a
policy and defines the version of the policy language. To learn more about the Version policy element
see the section called “Version” (p. 375).
You can use versions to track changes to a managed policy. For example, you might make a change to a
managed policy and then discover that the change had unintended effects. In this case, you can roll back
to a previous version of the managed policy by setting the previous version as the default version.
The following sections explain how you can use versioning for managed policies.
Topics
• Setting the Default Version (p. 241)
• Using Versions to Roll Back Changes (p. 242)
• Version Limits (p. 242)
Setting the Default Version
One of the versions of a managed policy is set as the default version. The policy's default version is the
operative version—that is, it's the version that is in effect for all of the principal entities (users, groups,
and roles) that the managed policy is attached to.
When you create a customer managed policy, the policy begins with a single version identified as v1. For
managed policies with only a single version, that version is automatically set as the default. For customer
managed policies with more than one version, you choose which version to set as the default. For AWS
managed policies, the default version is set by AWS. The following diagrams illustrate this concept.
241
AWS Identity and Access Management User Guide
Versioning for Managed Policies
You can set the default version of your customer managed policies, but AWS sets the default version of
AWS managed policies. To learn how to set the default version of a customer managed policy using the
AWS Management Console, see Setting the Default Version of Customer Managed Policies (p. 253). For
the AWS Command Line Interface, or the IAM API, see Working with Managed Policies Using the AWS CLI
or the IAM API (p. 254).
Using Versions to Roll Back Changes
When you change a customer managed policy, your changes are stored as policy versions. In some cases,
you may want to roll back your changes. For example, consider the following scenario.
You create a customer managed policy that allows users to administer a particular Amazon S3 bucket
using the AWS Management Console. Upon creation, your customer managed policy has only one
version, identified as v1, so that version is automatically set as the default. The policy works as intended.
Later, you update the policy to add permission to administer a second Amazon S3 bucket. IAM creates a
new version of the policy, identified as v2, that contains your changes. You set version v2 as the default,
and a short time later your users report that they lack permission to use the Amazon S3 console. In this
case, you can roll back to version v1 of the policy, which you know works as intended. To do this, you set
version v1 as the default version. Your users are now able to use the Amazon S3 console to administer
the original bucket.
Later, after you determine the error in version v2 of the policy, you update the policy again to add
permission to administer the second Amazon S3 bucket. IAM creates another new version of the policy,
identified as v3. You set version v3 as the default, and this version works as intended. At this point, you
delete version v2 of the policy.
Version Limits
A managed policy can have up to five versions. If you need to make changes to a managed policy beyond
five versions from the AWS Command Line Interface, or the IAM API, you must first delete one or more
existing versions. If you use the AWS Management Console, you do not have to delete a version before
editing your policy. When you save a sixth version, a dialog box appears that prompts you to delete one
or more nondefault versions of your policy. You can view the JSON policy document for each version
to help you decide. For details about this dialog box, see the section called “Editing Customer Managed
Policies” (p. 252).
You can delete any version of the managed policy that you want, except for the default version. When
you delete a version, the version identifiers for the remaining versions do not change. As a result, version
242
AWS Identity and Access Management User Guide
Deprecated AWS Managed Policies
identifiers might not be sequential. For example, if you delete versions v2 and v4 of a managed policy
and add two new versions, the remaining version identifiers might be v1, v3, v5, v6, and v7.
Deprecated AWS Managed Policies
To simplify the assignment of permissions, AWS provides managed policies (p. 235)—predefined
policies that are ready to be attached to your IAM users, groups, and roles.
Sometimes AWS needs to add a new permission to an existing policy, such as when a new service is
introduced. Adding a new permission to an existing policy does not disrupt or remove any feature or
ability.
However, AWS might choose to create a new policy when the needed changes could impact customers if
they were applied to an existing policy. For example, removing permissions from an existing policy could
break the permissions of any IAM entity or application that depended upon it, potentially disrupting a
critical operation.
Therefore, when such a change is required, AWS creates a completely new policy with the required
changes and makes it available to customers. The old policy is then marked deprecated. A deprecated
managed policy appears with a warning icon next to it in the Policies list in the IAM console.
A deprecated policy has the following characteristics:
• It continues to work for all currently attached users, groups, and roles. Nothing breaks.
• It cannot be attached to any new users, groups, or roles. If you detach it from a current entity, you
cannot reattach it.
• After you detach it from all current entities, it is no longer visible and can no longer be used in any
way.
If any user, group, or role requires the policy, you must instead attach the new policy. When you receive
notice that a policy is deprecated, we recommend that you immediately plan to attach all users, groups,
and roles to the replacement policy and detach them from the deprecated policy. Continuing to use the
deprecated policy can carry risks that are mitigated only by switching to the replacement policy.
Controlling Access to Managed Policies
Managed policies give you precise control over how your users can manage policies and manage
permissions for others. You can separately control who can create, update, and delete policies, and who
can attach and detach policies to and from principal entities (users, groups, and roles). You can also
control which policies a user can attach or detach, and to and from which entities.
A typical scenario is that you give permissions to an account administrator to create, update, and delete
policies. Then, you give permissions to a team leader or other limited administrator to attach and detach
these policies to and from principal entities that the limited administrator manages.
Topics
• Controlling Permissions for Creating, Updating, and Deleting Customer Managed Policies (p. 244)
• Controlling Permissions for Attaching and Detaching Managed Policies (p. 245)
• Specifying the Amazon Resource Name (ARN) for Managed Policies (p. 246)
243
AWS Identity and Access Management User Guide
Controlling Access to Managed Policies
Controlling Permissions for Creating, Updating, and Deleting
Customer Managed Policies
You can use IAM policies (p. 232) to control who is allowed to create, update, and delete customer
managed policies in your AWS account. The following list contains APIs that pertain directly to creating,
updating, and deleting policies or policy versions:
• CreatePolicy
• CreatePolicyVersion
• DeletePolicy
• DeletePolicyVersion
• SetDefaultPolicyVersion
The APIs in the preceding list correspond to actions that you can allow or deny—that is, permissions that
you can grant—using an IAM policy.
The following example shows a policy that allows a user to create, update (that is, create a new policy
version), delete, and set a default version for all customer managed policies in the AWS account. The
example policy also allows the user to list policies and get policies.
Example policy that allows creating, updating, deleting, listing, getting, and setting the
default version for all policies
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"iam:CreatePolicy",
"iam:CreatePolicyVersion",
"iam:DeletePolicy",
"iam:DeletePolicyVersion",
"iam:GetPolicy",
"iam:GetPolicyVersion",
"iam:ListPolicies",
"iam:ListPolicyVersions",
"iam:SetDefaultPolicyVersion"
],
"Resource": "*"
}
You can create policies that limit the use of these APIs to affect only the managed policies that you
specify. For example, you might want to allow a user to set the default version and delete policy
versions, but only for specific customer managed policies. You do this by specifying the policy ARN in the
Resource element of the policy that grants these permissions.
The following example shows a policy that allows a user to delete policy versions and set the default
version, but only for the customer managed policies that include the path /TEAM-A/. The customer
managed policy ARN is specified in the Resource element of the policy (in this example the ARN includes
a path and a wildcard and thus matches all customer managed policies that include the path /TEAM-A/).
For more information about using paths in the names of customer managed policies, see Friendly Names
and Paths (p. 356).
244
AWS Identity and Access Management User Guide
Controlling Access to Managed Policies
Example policy that allows deleting policy versions and setting the default version for only
specific policies
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"iam:DeletePolicyVersion",
"iam:SetDefaultPolicyVersion"
],
"Resource": "arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:policy/TEAM-A/*"
}
Controlling Permissions for Attaching and Detaching Managed
Policies
You can also use IAM policies to allow users to work with only specific managed policies—in effect, you
can control which permissions a user is allowed to grant to other principal entities.
The following list shows APIs that pertain directly to attaching and detaching managed policies to and
from principal entities:
• AttachGroupPolicy
• AttachRolePolicy
• AttachUserPolicy
• DetachGroupPolicy
• DetachRolePolicy
• DetachUserPolicy
You can create policies that limit the use of these APIs to affect only the specific managed policies and/
or principal entities that you specify. For example, you might want to allow a user to attach managed
policies, but only the managed policies that you specify. Or, you might want to allow a user to attach
managed policies, but only to the principal entities that you specify.
The following example policy allows a user to attach managed policies to only the groups and roles that
include the path /TEAM-A/. The group and role ARNs are specified in the Resource element of the policy
(in this example the ARNs include a path and a wildcard and thus match all groups and roles that include
the path /TEAM-A/).
Example policy that allows attaching managed policies to only specific groups or roles
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"iam:AttachGroupPolicy",
"iam:AttachRolePolicy"
],
"Resource": [
"arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:group/TEAM-A/*",
"arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/TEAM-A/*"
]
}
245
AWS Identity and Access Management User Guide
Controlling Access to Managed Policies
You can further limit the actions in the preceding example to affect only specific policies—that is,
you can control which permissions a user is allowed to attach to other principal entities—by adding a
condition to the policy.
In the following example, the condition ensures that the AttachGroupPolicy and AttachRolePolicy
permissions are allowed only when the policy being attached matches one of the specified policies.
The condition uses the iam:PolicyArn condition key (p. 385) to determine which policy or policies are
allowed to be attached. The following example policy expands on the previous example by allowing a
user to attach only the managed policies that include the path /TEAM-A/ to only the groups and roles
that include the path /TEAM-A/.
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"iam:AttachGroupPolicy",
"iam:AttachRolePolicy"
],
"Resource": [
"arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:group/TEAM-A/*",
"arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/TEAM-A/*"
],
"Condition": {"ArnLike":
{"iam:PolicyArn": "arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:policy/TEAM-A/*"}
}
}
Specifying the Amazon Resource Name (ARN) for Managed
Policies
To control access to specific managed policies, you use the Amazon Resource Name (ARN) (p. 357) of
the managed policy. In some cases you use the ARN of the managed policy in the Resource element of a
policy, and in other cases you use the ARN of the managed policy in the Condition element of a policy.
The following sections explain when to use each.
Using the Resource Element to Control Access to Actions That Affect the Managed
Policy
To control access to specific managed policies for actions that affect the managed policy, you specify the
ARN of the managed policy in the Resource element of a policy.
The following list contains IAM actions (APIs) that affect a managed policy:
• CreatePolicy
• CreatePolicyVersion
• DeletePolicy
• DeletePolicyVersion
• GetPolicy
• GetPolicyVersion
• ListEntitiesForPolicy
• ListPolicyVersions
• SetDefaultPolicyVersion
246
AWS Identity and Access Management User Guide
Creating IAM Policies
You can limit the use of these actions to affect only the managed policies that you specify. You do this
by specifying the policy ARN in the Resource element of the policy that grants these permissions. For
example, to specify the ARN of a customer managed policy:
"Resource": "arn:aws-cn:iam::123456789012:policy/POLICY-NAME"
You can also specify the ARN of an AWS managed policy in a policy's Resource element. The ARN of
an AWS managed policy uses the special alias aws in the policy ARN instead of an account ID, as in this
example:
"Resource": "arn:aws-cn:iam::aws:policy/AmazonEC2FullAccess"
Using the Condition Element to Control Access to Actions That Affect the Principal
Entity (User, Group, or Role)
To control access to specific managed policies for actions that involve a managed policy but that affect
a principal entity (user, group, or role), you specify the ARN of the managed policy in the Condition
element of a policy. In this case, the Resource element of a policy is used to specify the ARN of the
principal entity that is affected.
The following list contains IAM actions (APIs) that involve a managed policy but that affect a principal
entity:
• AttachGroupPolicy
• AttachRolePolicy
• AttachUserPolicy
• DetachGroupPolicy
• DetachRolePolicy
• DetachUserPolicy
You can limit the use of these actions to involve only the managed policies that you specify. You do this
by specifying the policy ARN in the Condition element of the policy that grants these permissions. For
example, to specify the ARN of a customer managed policy:
"Condition": {"ArnEquals":
{"iam:PolicyArn": "arn:aws-cn:iam::123456789012:policy/POLICY-NAME"}
}
You can also specify the ARN of an AWS managed policy in a policy's Condition element. The ARN of
an AWS managed policy uses the special alias aws in the policy ARN instead of an account ID, as in this
example:
"Condition": {"ArnEquals":
{"iam:PolicyArn": "arn:aws-cn:iam::aws:policy/AmazonEC2FullAccess"}
}
You can use the ArnLike or ArnEquals condition types. For more information about ArnLike and
ArnEquals, see Amazon Resource Name (ARN) Condition Operators (p. 392) in the Condition Types
section of the Policy Element Reference.
Creating a New Policy
You have several ways to create a new IAM permission policy. You can copy a complete AWS managed
policy that already does some of what you're looking for and then customize it to your specific
247
AWS Identity and Access Management User Guide
Creating IAM Policies
requirements. Alternatively, you can construct the policy by selecting actions and conditions from lists in
the policy generator to build the statements into a policy for you. Or you can create a policy from scratch
by writing the JSON code.
A policy consists of one or more statements. Each statement generally contains all the actions that share
the same effect (Allow or Deny) and the same resources. If one action requires "*" for the resource, and
another action specifies the ARN of a specific resource, then they must be in two separate statements.
For general information about IAM policies, see Overview of IAM Policies (p. 232). For information
about the IAM policy language, see AWS IAM Policy Reference (p. 373).
Create a Policy
No matter which option you choose, they all start the same way:
To start creating a new policy
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation column on the left, choose Policies.
If this is your first time choosing Policies, the Welcome to Managed Policies page appears. Choose
Get Started.
3.
At the top of the page, choose Create Policy.
4.
On the Create Policy page choose Select for one of the following options. Then follow the steps in
the selected procedure:
• Copy an AWS Managed Policy (p. 248) — Copies an existing managed policy and enables you to
customize the copy for its new purpose.
• Policy Generator (p. 248) — Creates a policy by letting you select items from lists.
• Create Your Own Policy (p. 249) — Opens the policy editor with a blank policy that you can
type or copy and paste into.
Copy an Existing Managed Policy
An easy way to create a new policy is to start with a copy of a policy that has at least some of the needed
functionality already in it. You can then customize the policy to match it to your new requirements.
To create a copy of an existing policy
1.
Start the Create Policy wizard by following the steps in Create a Policy (p. 248). Then choose
Select for Copy an AWS Managed Policy.
2.
On the Copy an AWS Managed Policy page, choose Select for the managed policy that most closely
approximates the policy you want to create. Type in the search box at the top to limit the list to your
search terms.
3.
On the Review Policy page, edit the Policy Name, Description (optional), and the Policy Document
information so that they meet your new requirements. Choose Create Policy to save your work.
Construct a Policy with the Policy Generator
The policy generator can create a policy without you having to write JSON syntax.
248
AWS Identity and Access Management User Guide
Creating IAM Policies
To use the policy generator to create a policy
1.
Start the Create Policy wizard by following the steps in Create a Policy (p. 248). Then choose
Select for Policy Generator.
2.
On the Edit Permissions page, for Effect, choose Allow or Deny. Because we deny by default,
we recommend as a security best practice that you allow permissions to only those actions and
resources that a user needs access to. This is sometime called "whitelisting". You need to create a
statement with an explicit Deny ("blacklisting") only if you want to override a permission separately
allowed by another statement or policy. We recommend that you limit the number of explicit Deny
statements to a minimum because they can increase the difficulty of troubleshooting permissions.
3.
Select the AWS service whose actions you want to allow or deny from the list.
4.
Choose the actions that you want to allow or deny. The list shows actions for the service that you
selected in the step 2. You can specify All Actions or specify individual actions by selecting the box
next to each action name. When you are done selecting actions, click outside of the list to close it.
The list shows how many actions you selected.
5.
Type the resource you want to allow or deny access to. Some operations allow only "Resource":"*"
while others allow you to specify the Amazon Resource Name (ARN) of individual resources. You
can include an asterisk (*) as a wildcard in any field of the ARN (between each pair of colons). Or
simply specify an asterisk by itself to mean "any resource in the account." For example, arn:awscn:s3:::* represents all S3 buckets in the same account as the policy. For more information, see
Resource (p. 383).
6.
(Optional) You can add Condition elements to limit a statement's effect. For example, you can
specify that a user is allowed to perform the actions on the resources only when that user's request
happens within a certain time range, or is authenticated with a multi-factor authentication device,
or originates from within a certain range of IP addresses. For lists of all of the context keys you can
use in the Condition element, see AWS Service Actions and Condition Context Keys for Use in IAM
Policies (p. 430). To begin, click Add Conditions (optional).
a.
For Condition choose the type of comparison that you want to perform.
b.
For Key choose the context key whose value you want to evaluate when a user makes a request.
c.
For Value type the value that you want to compare to the specified key.
d.
Choose Add Condition to add this completed condition to the current statement. To add
another condition, modify the settings and choose Add Condition again. Repeat as needed.
Each condition applies only to this one statement. All the conditions must be true for the
permission statement to be considered a match. You can consider the conditions as being
connected by a logical "AND" element.
For more information about the Condition element, see Condition (p. 385) in the AWS IAM
Policy Reference (p. 373).
7.
When you have completed all of the fields needed for this statement, choose Add Statement. If you
need to add more statements to the policy, repeat the preceding steps. Any time you need to change
the effect or change the affected resources, you must create a new statement.
8.
After you have added all of the statements that you need, choose Next Step to see your statements
in the policy editor. If you want to make changes, you can manually edit the policy further. Edit and
save the policy using the steps shown in the following procedure.
Edit a Policy Using the Policy Editor
You can also use the policy editor to create a new policy.
To create a new policy in the policy editor
1.
Start the Create Policy wizard by following the steps in Create a Policy (p. 248). Then choose
Select for Create Your Own Policy.
249
AWS Identity and Access Management User Guide
Working with Policies
2.
For Policy Name, type a unique name that helps you to remember what your policy is intended to
do.
3.
(Optional) For Description, type an explanation for future reference.
4.
For Policy Document, add or edit policy statements. For details about the IAM policy language, see
AWS IAM Policy Reference (p. 373).
5.
You can choose Validate Policy any time during editing to ensure that the policy is syntactically
correct. You can save the policy only if the syntax is correct.
Note
The policy validator only checks the JSON policy syntax and grammar. It does not validate
that your ARNs, action names, or condition keys are correct.
6.
When you are done with the policy, choose Create Policy to save your completed policy.
7.
After you create a policy, you can apply it by attaching it to your users, groups, or roles. For more
information, see Attaching Managed Policies (p. 251)
Working with Policies
This section describes how to create and manage all types of IAM policies (managed policies and inline
policies).
For more information about the different types of IAM policies, see Managed Policies and Inline
Policies (p. 235).
For general information about IAM policies, see Overview of IAM Policies (p. 232).
To add permissions to an IAM principal entity—that is, an IAM user, group, or role—you create a policy
and then attach the policy to the principal entity. You can attach multiple policies to a principal entity,
and each policy can contain multiple permissions.
For information about how permissions are evaluated when multiple policies are in effect for a given IAM
principal entity, see IAM Policy Evaluation Logic (p. 405).
For information about policy size limitations and other quotas, see Limitations on IAM Entities and
Objects (p. 360).
Topics
• Working with Managed Policies (p. 250)
• Working with Inline Policies (p. 256)
Working with Managed Policies
This section describes how to work with AWS managed policies, and how to create and work with
customer managed policies, that is, managed policies that you create yourself. You can manage and
create managed policies using the AWS Management Console, the AWS Command Line Interface (AWS
CLI), or the IAM API.
For more information about the different types of IAM policies, see Managed Policies and Inline
Policies (p. 235).
For general information about IAM policies, see Overview of IAM Policies (p. 232).
For information about policy size limitations and other quotas, see Limitations on IAM Entities and
Objects (p. 360).
Topics
250
AWS Identity and Access Management User Guide
Working with Policies
• Working with Managed Policies Using the AWS Management Console (p. 251)
• Working with Managed Policies Using the AWS CLI or the IAM API (p. 254)
Working with Managed Policies Using the AWS Management Console
This section describes how to manage managed policies (p. 235) using the AWS Management Console.
For information about managing managed policies using the AWS Command Line Interface (AWS CLI) or
the IAM API, see Working with Managed Policies Using the AWS CLI or the IAM API (p. 254).
Topics
• Attaching Managed Policies (p. 251)
• Detaching Managed Policies (p. 251)
• Creating Customer Managed Policies (p. 252)
• Editing Customer Managed Policies (p. 252)
• Setting the Default Version of Customer Managed Policies (p. 253)
• Deleting Versions of Customer Managed Policies (p. 253)
• Deleting Customer Managed Policies (p. 254)
Attaching Managed Policies
You can attach a managed policy to a principal entity (a user, group, or role) to apply the permissions in
the policy to the principal entity. You can attach up to 10 managed policies to each principal entity.
To attach a managed policy using the AWS Management Console
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Policies.
3.
In the list of policies, select the check box next to the name of the policy to attach. You can use the
Filter menu and the search box to filter the list of policies.
4.
Choose Policy actions, and then choose Attach.
5.
Select the principal entities to attach the policy to. You can use the Filter menu and the search box
to filter the list of principal entities. After selecting the principal entities to attach the policy to,
choose Attach policy.
Detaching Managed Policies
You can detach a managed policy from a principal entity (a user, group, or role) to remove the
permissions in the policy from the principal entity.
To detach a managed policy using the AWS Management Console
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Policies.
3.
In the list of policies, select the check box next to the name of the policy to detach. You can use the
Filter menu and the search box to filter the list of policies.
4.
Choose Policy actions, and then choose Detach.
5.
Select the principal entities to detach the policy from. You can use the Filter menu and the search
box to filter the list of principal entities. After selecting the principal entities to detach the policy
from, choose Detach policy.
251
AWS Identity and Access Management User Guide
Working with Policies
Creating Customer Managed Policies
You can create customer managed policies to define sets of permissions to attach to principal entities
(users, groups, and roles) in your AWS account. For more information about customer managed policies,
see Managed Policies and Inline Policies (p. 235)
To create a managed policy using the AWS Management Console
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Policies, and then choose Create Policy.
3.
Choose the Select button that corresponds to the way that you want to create your policy.
• Copy an AWS Managed Policy. See a list of all existing policies and then choose Select next to the
one you want to copy.
• Policy Generator. Build a policy by selecting elements from lists of available options. Select the
appropriate Effect, AWS Service, and Actions options, enter the Amazon Resource Name ARN (if
applicable), and add any conditions you want to include. Then choose Add Statement. You can
add as many statements as you want to the policy. When you are finished adding statements,
choose Next Step.
• Create Your Own Policy. Type a Policy Name in the space provided. For Policy Document, type or
paste a policy document into the editor.
4.
In the editor, make any customizations that you need to tailor the policy to your environment.
5.
After you complete your changes, choose Validate Policy and ensure that no errors display in a red
box at the top of the screen. Correct any errors that are reported.
Note
If Use autoformatting for policy editing is selected, the policy is reformatted whenever
you open a policy or choose Validate Policy.
6.
Choose Create Policy to save your new policy.
Editing Customer Managed Policies
You edit customer managed policies to change the permissions that are defined in the policy. You cannot
edit AWS managed policies.
A managed policy can have up to five versions. If you need to make changes to a managed policy beyond
five versions, then the AWS Management Console prompts you to decide which version to delete.
To edit a customer managed policy using the AWS Management Console
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Policies.
3.
In the list of policies, choose the policy name of the policy to edit. You can use the Filter menu and
the search box to filter the list of policies.
4.
Choose the Permissions tab, choose Edit policy, and then edit the policy document.
5.
After you complete your changes, choose Validate policy and ensure that no errors appear in a red
box at the top of the screen. Correct any that are reported.
Note
If Use autoformatting for policy editing is selected, then the policy is reformatted
whenever you open a policy or choose Validate policy.
6.
When you are finished editing the policy, decide whether you want to immediately apply your
changes to all principal entities (users, groups, and roles) that this policy is attached to:
252
AWS Identity and Access Management User Guide
Working with Policies
• To immediately apply your changes to all attached entities, select Save as default version.
• To save your changes without affecting the currently attached entities, clear the check box for
Save as default version.
7.
Choose Save.
8.
If the managed policy already has the maximum of five versions, then choosing Save displays a
dialog box. To save your new version, you must remove at least one older version. You cannot delete
the default version. Choose from the following options:
• Remove oldest non-default policy version (version v# - created # days ago) - Use this option
to see which version will be deleted and when it was created. You can view the JSON policy
document for all nondefault versions by choosing the second option, Select versions to remove.
• Select versions to remove - Use this option to view the JSON policy document and choose one or
more versions to delete.
After choosing the versions to remove, choose Delete version and save to save your new policy
version.
Setting the Default Version of Customer Managed Policies
You can specify the default version of a customer managed policy to make that version the one that is in
effect for every principal entity (user, group, and role) that the policy is attached to. You cannot set the
default version for an AWS managed policy.
You can set the default version of a customer managed policy when you edit the policy. To set the
default version while editing the policy, see Editing Customer Managed Policies (p. 252). To set the
default version of a customer managed policy independently of editing the policy, see the following
procedure.
To set the default version of a customer managed policy using the AWS Management
Console
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Policies.
3.
In the list of policies, choose the policy name of the policy to set the default version of. You can use
the Filter menu and the search box to filter the list of policies.
4.
Choose the Policy versions tab. Select the check box next to the version that you want to set as the
default version, and then choose Set as default.
Deleting Versions of Customer Managed Policies
You can delete a version of a customer managed policy to ensure that version can never be set as the
default version of the policy. That is, to ensure that version can never be attached to any entities (users,
groups, and roles) in your AWS account. You cannot delete versions of AWS managed policies.
To delete a version of a customer managed policy using the AWS Management Console
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Policies.
3.
Choose the name of the customer managed policy that has a version you want to delete. You can
use the Filter menu and the search box to filter the list of policies.
253
AWS Identity and Access Management User Guide
Working with Policies
4.
Choose the Policy versions tab. Select the check box next to the version that you want to delete.
Then choose Delete.
5.
Confirm that you want to delete the version, and then choose Delete.
Deleting Customer Managed Policies
You can delete a customer managed policy to remove it from your AWS account. You cannot delete AWS
managed policies.
To delete a customer managed policy using the AWS Management Console
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Policies.
3.
Select the check box next to the customer managed policy to delete. You can use the Filter menu
and the search box to filter the list of policies.
4.
Choose Policy actions, and then choose Delete.
5.
Confirm that you want to delete the policy, and then choose Delete.
Working with Managed Policies Using the AWS CLI or the IAM API
This section describes how to manage managed policies (p. 235) using the AWS Command Line
Interface (AWS CLI) or the IAM API. Information in this section applies to both AWS managed policies and
customer managed policies, that is, managed policies that you create.
For information about managing managed policies using the AWS Management Console, see Working
with Managed Policies Using the AWS Management Console (p. 251).
To list managed policies
• AWS CLI: list-policies
• IAM API: ListPolicies
To retrieve detailed information about a managed policy
• AWS CLI: get-policy
• IAM API: GetPolicy
To list the versions of a managed policy
• AWS CLI: list-policy-versions
• IAM API: ListPolicyVersions
To retrieve detailed information about a version of a managed policy, including the policy document
• AWS CLI: get-policy-version
• IAM API: GetPolicyVersion
To list the principal entities (users, groups, and roles) attached to a managed policy
• AWS CLI: list-entities-for-policy
• IAM API: ListEntitiesForPolicy
254
AWS Identity and Access Management User Guide
Working with Policies
To list the managed policies attached to a principal entity (a user, group, or role)
• AWS CLI:
• list-attached-group-policies
• list-attached-role-policies
• list-attached-user-policies
• IAM API:
• ListAttachedGroupPolicies
• ListAttachedRolePolicies
• ListAttachedUserPolicies
To attach a managed policy to a group, role, or user
• AWS CLI:
• attach-group-policy
• attach-role-policy
• attach-user-policy
• IAM API:
• AttachGroupPolicy
• AttachRolePolicy
• AttachUserPolicy
To detach a managed policy from a group, role, or user
• AWS CLI:
• detach-group-policy
• detach-role-policy
• detach-user-policy
• IAM API:
• DetachGroupPolicy
• DetachRolePolicy
• DetachUserPolicy
To create a customer managed policy
• AWS CLI: create-policy
• IAM API: CreatePolicy
To edit a customer managed policy
A managed policy can have up to five versions. If you need to make changes to a managed policy beyond
five versions from the AWS Command Line Interface, or the IAM API, you must first delete one or more
existing versions.
• AWS CLI: create-policy-version
• IAM API: CreatePolicyVersion
To set the default version of a customer managed policy
255
AWS Identity and Access Management User Guide
Working with Policies
• AWS CLI: set-default-policy-version
• IAM API: SetDefaultPolicyVersion
To delete a version of a customer managed policy
• AWS CLI: delete-policy-version
• IAM API: DeletePolicyVersion
To delete a customer managed policy
• AWS CLI: delete-policy
• IAM API: DeletePolicy
Working with Inline Policies
This section describes how to create and manage inline policies (p. 235).
For information about managing managed policies, see Working with Managed Policies (p. 250).
Working with Inline Policies (Console)
You can use the AWS Management Console to create and embed inline policies.
To create an inline policy and embed it in a group, user, or role
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Groups, Users, or Roles.
3.
In the list, choose the name of the group, user, or role to embed a policy in.
4.
Choose the Permissions tab. If you chose Groups, expand the Inline Policies section if necessary.
5.
If in Groups, choose Create Group Policy. If in Users or Roles, scroll to the bottom of the page and
choose Add inline policy. If there are no existing policies in Groups, instead choose click here to
create your first inline policy.
Note
You cannot embed an inline policy in a service-linked role (p. 99) in IAM. Because the linked
service defines whether you can modify the permissions of the role, you might be able to
add additional policies from the service console, API, or CLI. To view the service-linked role
documentation for a service, see AWS Services That Work with IAM (p. 363) and choose
Yes in the Service-Linked Role column for your service.
6.
Choose Policy Generator or Custom Policy, and then choose Select.
7.
Do one of the following:
• If you chose Custom Policy, specify a name for the policy and create your policy document.
• If you are using the policy generator to create your policy, select the appropriate Effect, AWS
Service, and Actions options. Type the Amazon Resource Name ARN (if applicable), and add
any conditions that you want to include. Then choose Add Statement. You can add as many
statements as you want to the policy. When you are finished adding statements, choose Next
Step. For more information, see Construct a Policy with the Policy Generator (p. 248)
8.
Choose Validate Policy and ensure that no errors appear in a red box at the top of the screen.
Correct any that are reported.
256
AWS Identity and Access Management User Guide
Working with Policies
Note
If Use autoformatting for policy editing is selected, the policy is reformatted whenever
you open a policy or choose Validate Policy.
9.
When you are satisfied with the policy, choose Apply Policy.
To view a policy or a list of all policies associated with a user, group, or role
•
In the navigation pane, choose Users, Groups, or Roles. Choose the name of the entity to view, and
then choose the Permissions tab.
To edit or delete an inline policy for a group, user, or role
1.
In the navigation pane, choose Groups, Users, or Roles.
2.
Choose the name of the group, user, or role with the policy that you want to modify. Then choose
the Permissions tab. If you chose Users or Roles, expand the policy.
3.
To edit an inline policy, choose Edit Policy.
4.
To delete an inline policy in Groups, choose Remove Policy. To delete an inline policy in Users or
Roles, choose X.
Working with Inline Policies (AWS API, AWS CLI)
You can use the AWS CLI or IAM API to work with inline policies.
To list all inline policies that are embedded in a principal entity (user, group, or role)
• AWS CLI:
• list-group-policies
• list-role-policies
• list-user-policies
• IAM API:
• ListGroupPolicies
• ListRolePolicies
• ListUserPolicies
To retrieve an inline policy document that is embedded in a principal entity (user, group, or role)
• AWS CLI:
• get-group-policy
• get-role-policy
• get-user-policy
• IAM API:
• GetGroupPolicy
• GetRolePolicy
• GetUserPolicy
To embed an inline policy in a principal entity (user, group, or role)
Note
You can embed an inline policy for a service-linked role (p. 99) only in the service that depends
on the role. See the AWS documentation for your service to see whether it supports this feature.
257
AWS Identity and Access Management User Guide
Policy Summaries
• AWS CLI:
• put-group-policy
• put-role-policy
• put-user-policy
• IAM API:
• PutGroupPolicy
• PutRolePolicy
• PutUserPolicy
To delete an inline policy that is embedded in a principal entity (user, group, or role)
Note
You can delete an inline policy from a service-linked role (p. 99) only in the service that depends
on the role. See the AWS documentation for your service to see whether it supports this feature.
• AWS CLI:
• delete-group-policy
• delete-role-policy
• delete-user-policy
• IAM API:
• DeleteGroupPolicy
• DeleteRolePolicy
• DeleteUserPolicy
Understanding Policy Summaries in the AWS
Management Console
The IAM console includes policy summary tables that describe the access level, resources, and conditions
that are allowed or denied for each service in a policy. Policies are summarized in three tables: the
policy summary (p. 259), the service summary (p. 269), and the action summary (p. 273). The
policy summary table includes a list of services. Choose a service there to see the service summary. This
summary table includes a list of the actions and associated permissions for the chosen service. You can
choose an action from that table to view the action summary. This table includes a list of resources and
conditions for the chosen action.
258
AWS Identity and Access Management User Guide
Policy Summaries
You can view policy summaries on the Users page for all policies (managed and inline) that are attached
to that user. View summaries on the Policies page for all managed policies. Managed policies include
AWS managed policies, AWS managed job function policies, and customer managed policies. You can
view summaries for these policies on the Policies page regardless of whether they are attached to a user
or other IAM identity.
You can use the information in the policy summaries to understand the permissions that are allowed or
denied by your policy. Policy summaries can help you troubleshoot (p. 336) and fix policies that are not
providing the permissions that you expect.
Topics
• Policy Summary (List of Services) (p. 259)
• Service Summary (List of Actions) (p. 269)
• Action Summary (List of Resources) (p. 273)
• Examples of Policy Summaries (p. 275)
Policy Summary (List of Services)
Policies are summarized in three tables: the policy summary, the service summary (p. 269), and the
action summary (p. 273). The policy summary table includes a list of services and summaries of the
permissions that are defined by the chosen policy.
259
AWS Identity and Access Management User Guide
Policy Summaries
The policy summary table is grouped into one or more Uncategorized services, Explicit deny, and Allow
sections. If the policy includes a service that IAM does not recognize, then the service is included in the
Uncategorized services section of the table. If IAM recognizes the service, then it is included under the
Explicit deny or Allow sections of the table, depending on the effect of the policy (Deny or Allow).
Viewing Policy Summaries
You can view the summaries for any policies that are attached to a user on the Users page. You can view
the summaries for any policies that are attached to a role on the Roles page. You can view the policy
summary for managed policies on the Policies page. If your policy does not include a policy summary,
see Missing Policy Summary (p. 340) to learn why.
To view the policy summary from the Policies page
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Policies.
3.
In the list of policies, choose the name of the policy that you want to view.
4.
On the Summary page for the policy, view the Permissions tab to see the policy summary.
To view the summary for a policy attached to a user
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
Choose Users from the navigation pane.
3.
In the list of users, choose the name of the user whose policy you want to view.
4.
On the Summary page for the user, view the Permissions tab to see the list of policies that are
attached to the user directly or from a group.
5.
In the table of policies for the user, expand the row of the policy that you want to view.
260
AWS Identity and Access Management User Guide
Policy Summaries
To view the summary for a policy attached to a role
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Roles.
3.
In the list of roles, choose the name of the role whose policy you want to view.
4.
On the Summary page for the role, view the Permissions tab to see the list of policies that are
attached to the role.
5.
In the table of policies for the role, expand the row of the policy that you want to view.
Editing Policies to Change Policy Summaries
While viewing a policy summary, you might find a typo or notice that the policy does not provide the
permissions you expected. You cannot edit a policy summary directly. However, you can edit the policy
using the JSON policy editor and then view the changes in the policy summary. You cannot edit AWS
managed policies.
To edit a policy for your policy summary
1.
Open the policy summary as explained in the previous procedures.
2.
Choose { } JSON and Policy summary to compare the policy summary to the JSON policy
document. You can use this information to determine which lines in the policy document you want
to change.
3.
Choose Edit policy to edit the JSON policy document.
If you are on the Users page and choose to edit a customer managed policy that is attached to that
user, you are redirected to the Policies page. You can edit customer managed policies only on the
Policies page.
4.
Edit your policy and choose Save to save your changes.
5.
Choose Policy summary to see your changes reflected in the policy summary.
Understanding the Elements of a Policy Summary
In the following example of a user details page, the PolSumUser user has eight attached policies. The
SummaryAllElements policy is a managed policy (customer managed policy) that is attached directly to
the user. This policy is expanded to show the policy summary. To view the JSON policy document for this
policy, see the section called “SummaryAllElements JSON Policy Document” (p. 266).
261
AWS Identity and Access Management User Guide
Policy Summaries
In the preceding image, the policy summary is visible from within the user details page:
1. The Permissions tab for a user includes the policies that are attached to the PolSumUser user.
2. The SummaryAllElements policy is one of several policies that are attached to the user. The policy is
expanded in order to view the policy summary.
3. If the policy does not grant permissions to all the actions, resources, and conditions defined in the
policy, then a warning or error banner appears at the top of the page. The policy summary then
includes details about the problem. To learn how policy summaries help you to understand and
troubleshoot the permissions that your policy grants, see the section called “My Policy Does Not Grant
the Expected Permissions” (p. 342).
4. Use the Policy summary and { } JSON buttons to toggle between the policy summary and the JSON
policy document.
5. Simulate policy opens the policy simulator for testing the policy.
6. Use the search box to reduce the list of services and easily find a specific service.
7. The expanded view shows additional details of the SummaryAllElements policy.
262
AWS Identity and Access Management User Guide
Policy Summaries
The following policy summary table image shows the expanded SummaryAllElements policy on the
PolSumUser user details page.
In the preceding image, the policy summary is visible from within the user details page:
A. Service – This column lists the services that are defined within the policy and provides details for
each service. Each service name in the policy summary table is a link to the service summary table,
which is explained in Service Summary (List of Actions) (p. 269). In this example, permissions are
defined for the Amazon S3, Billing, and Amazon EC2 services. The policy also defines permissions for a
(misspelled) codedploy service, which IAM does not recognize.
B.
Unrecognized services – This policy includes an unrecognized service (in this case codedploy
).
You can use this warning to check whether a service name might include a typo. If the service name
is correct, then the service might not support policy summaries, might be in preview, or might be
a custom service. To request policy summary support for a generally available (GA) service, see
Service Does Not Support IAM Policy Summaries (p. 341). In this example, the policy includes an
unrecognized codedploy service that is missing an e. Because of this typo, the policy does not provide
the expected AWS CodeDeploy permissions. You can edit the policy (p. 261) to include the accurate
codedeploy service name; the service then appears in the policy summary.
C. For those services that IAM recognizes, it arranges services according to whether the policy allows or
explicitly denies the use of the service. In this example, the policy includes Allow and Deny statements
for the Amazon S3 service. Therefore the policy summary includes S3 within both the Explicit deny
and Allow sections.
D. Show remaining 100 – Choose this link to expand the table to include the services that are not
defined by the policy. These services are implicitly denied (or denied by default) within this policy.
However, a statement in another policy might still allow or explicitly deny using the service. The policy
summary summarizes the permissions of a single policy. To learn about how the AWS service decides
whether a given request should be allowed or denied, see IAM Policy Evaluation Logic (p. 405).
E.
EC2
– This service includes an unrecognized action. IAM recognizes service names, actions, and
resource types for services that support policy summaries. When a service is recognized but contains
an action that is not recognized, IAM includes a warning next to that service. In this example, IAM can't
recognize at least one Amazon EC2 action. To learn more about unrecognized actions and to view the
unrecognized action in an S3 service summary, see Service Summary (List of Actions) (p. 269).
Note
IAM reviews service names, actions, and resource types for services that support policy
summaries. However, your policy summary might include a resource value or condition that
does not exist. Always test your policies with the policy simulator (p. 283).
F.
S3
– This service includes an unrecognized resource. IAM recognizes service names, actions, and
resource types for services that support policy summaries. When a service is recognized but contains
263
AWS Identity and Access Management User Guide
Policy Summaries
aa resource type that is not recognized, IAM includes a warning next to that service. In this example,
IAM can't recognize at least one Amazon S3 action. To learn more about unrecognized resources
and to view the unrecognized resource type in an S3 service summary, see Service Summary (List of
Actions) (p. 269).
G. Access level – This column tells whether the actions in each access level (List, Read, Write, and
Permissions management) have Full or Limited permissions defined in the policy. For additional
details and examples of the access level summary, see Understanding Access Level Summaries Within
Policy Summaries (p. 267).
• Full access – This entry indicates that the service has access to all actions within all four of the
access levels available for the service. In this example, because this row is in the Explicit deny
section of the table, all Amazon S3 actions are denied for the resources included in the policy.
• If the entry does not include Full access, then the service has access to some but not all of the
actions for the service. The access is then defined by following descriptions for each of the four
access level classifications (List, Read, Write, and Permissions management):
Full: The policy provides access to all actions within each access level classification listed. In this
example, the policy provides access to all of the Billing Read actions.
Limited: The policy provides access to one or more but not all actions within each access level
classification listed. In this example, the policy provides access to some of the Billing Write actions.
H. Resource – This column shows the resources that the policy specifies for each service.
• Multiple – The policy includes more than one but not all of the resources within the service. In this
example, access is explicitly denied to more than one Amazon S3 resource.
• All resources –- The policy is defined for all resources within the service. In this example, the policy
allows the listed actions to be performed on all Billing resources.
• Resource text – The policy includes one resource within the service. In this example, the
listed actions are allowed on only the developer_bucket Amazon S3 bucket resource.
Depending on the information that the service provides to IAM, you might see an ARN such as
arn:aws:s3:::developer_bucket/*, or you might see the defined resource type, such as BucketName
= developer_bucket.
Note
This column can include a resource from a different service. If the policy statement that
includes the resource does not include both actions and resources from the same service,
then your policy includes mismatched resources. IAM does not warn you about mismatched
resources when you create a policy, or when you view a policy in the policy summary. If this
column includes a mismatched resource, then you should review your policy for errors. To
better understand your policies, always test them with the policy simulator (p. 283).
I. Request condition – This column indicates whether the services or actions associated with the
resource are subject to conditions.
• None – The policy includes no conditions for the service. In this example no conditions are applied
to the denied actions in the Amazon S3 service.
• Condition text – The policy includes one condition for the service. In this example, the listed Billing
actions are allowed only if the IP address of the source matches 203.0.113.0/24.
• Multiple – The policy includes more than one condition for the service. In this example, access to
the listed Amazon S3 actions is allowed based on more than one condition. To view each of the
multiple conditions for the policy, choose { } JSON to view the policy document.
When a policy or an element within the policy does not grant permissions, IAM provides additional
warnings and information in the policy summary. The following policy summary table shows the
expanded Show remaining 100 services on the PolSumUser user details page with the possible
warnings.
264
AWS Identity and Access Management User Guide
Policy Summaries
In the preceding image, you can see all services that include defined actions, resources, or conditions
with no permissions:
a. Resource warnings – For services that do not provide permissions for all of the included actions or
resources, you see one of the following warnings in the Resource column of the table:
•
•
•
No resources are defined. – This means that the service has defined actions but no supported
resources are included in the policy.
One or more actions do not have an applicable resource. – This means that the service has
defined actions, but that some of those actions don't have a supported resource.
One or more resources do not have an applicable action. – This means that the service has
defined resources, but that some of those resources don't have a supporting action.
If a service includes both actions that do not have an applicable resource and resources that do not
have an applicable resource, then only the One or more resources do not have an applicable action.
warning is shown. This is because when you view the service summary for the service, resources that
do not apply to any action are not shown. For the ListAllMyBuckets action, this policy includes the
last warning because the action does not support resource-level permissions, and does not support
the s3:x-amz-acl condition key. If you fix either the resource problem or the condition problem, the
remaining issue appears in a detailed warning.
b. Request condition warnings – For services that do not provide permissions for all of the included
conditions, you see one of the following warnings in the Request condition column of the table:
•
•
One or more actions do not have an applicable condition. – This means that the service has
defined actions, but that some of those actions don't have a supported condition.
One or more conditions do not have an applicable action. – This means that the service has
defined conditions, but that some of those condtions don't have a supporting action,
265
AWS Identity and Access Management User Guide
Policy Summaries
c.
Multiple |
One or more actions do not have an applicable resource. – The Deny statement
for Amazon S3 includes more than one resource. It also includes more than one action, and
some actions support the resources and some do not. To view this policy, see the section called
“SummaryAllElements JSON Policy Document” (p. 266). In this case, the policy includes all Amazon
S3 actions, and only the actions that can be performed on a bucket or bucket object are denied.
d. The ellipses (…) indicate that all the services are included in the page, but we are showing only the
rows with information relevant to this policy. When you view this page in the AWS Management
Console, you see all the AWS services.
e. The background color in the table rows indicates services that do not grant any permissions. You
cannot get any additional information about these services in the policy summary. For services in
white rows, you can choose the name of the service to view the service summary (list of actions) page.
There you can learn more about the permissions granted for that service.
f.
None - No actions are defined. – This means that the service is defined as a resource or condition,
but that no actions are included for the service, and therefore the service provides no permissions. In
this case, the policy includes a AWS CodeBuild resource but no AWS CodeBuild actions.
g.
h.
i.
No resources are defined – The service has defined actions, but no supported resources are
included in the policy, and therefore the service provides no permissions. In this case, the policy
includes AWS CodeCommit actions but no AWS CodeCommit resources.
BucketName = developer_bucket, ObjectPath = All |
One or more resources do not have an
applicable action. – The service has a defined bucket object resource, and at least one more resource
that does not have a supporting action.
s3:x-amz-acl = public-read |
One or more conditions do not have an applicable action. – The
service has a defined s3:x-amz-acl condition key, and at least one more condition key that does not
have a supporting action.
SummaryAllElements JSON Policy Document
The SummaryAllElements policy is not intended for you to use to define permissions in your account.
Rather, it is included to demonstrate the errors and warnings that you might encounter while viewing a
policy summary.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"aws-portal:ViewBilling",
"aws-portal:ViewPaymentMethods",
"aws-portal:ModifyPaymentMethods",
"aws-portal:ViewAccount",
"aws-portal:ModifyAccount",
"aws-portal:ViewUsage"
],
"Resource": [
"*"
],
"Condition": {
"IpAddress": {
"aws:SourceIp": "203.0.113.0/24"
}
}
},
{
266
AWS Identity and Access Management User Guide
Policy Summaries
},
{
},
{
},
{
}
]
}
"Effect": "Deny",
"Action": [
"s3:*"
],
"Resource": [
"arn:aws:s3:::customer",
"arn:aws:s3:::customer/*"
]
"Effect": "Allow",
"Action": [
"ec2:GetConsoleScreenshots"
],
"Resource": [
"*"
]
"Effect": "Allow",
"Action": [
"codedploy:*",
"codecommit:*"
],
"Resource": [
"arn:aws:codedeploy:us-west-2:123456789012:deploymentgroup:*",
"arn:aws:codebuild:us-east-1:123456789012:project/my-demo-project"
]
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets",
"s3:GetObject",
"s3:DeletObject",
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": [
"arn:aws:s3:::developer_bucket",
"arn:aws:s3:::developer_bucket/*",
"arn:aws:autoscling:us-east-2:123456789012:autoscalgrp"
],
"Condition": {
"StringEquals": {
"s3:x-amz-acl": [
"public-read"
],
"s3:prefix": [
"custom",
"other"
]
}
}
Understanding Access Level Summaries Within Policy Summaries
Policy summaries include an access level summary that describes the action permissions defined for
each service that is mentioned in the policy. To learn about policy summaries, see Understanding Policy
Summaries in the AWS Management Console (p. 258). Access level summaries indicate whether the
actions in each access level (List, Read, Write, and Permissions management) have Full or Limited
267
AWS Identity and Access Management User Guide
Policy Summaries
permissions defined in the policy. To view a list of actions that belong to each of the action levels for
a specific service, see AWS IAM Policy Actions Grouped by Access Level (p. 529). To see a complete
list of actions for a specific service, see AWS Service Actions and Condition Context Keys for Use in IAM
Policies (p. 430).
The following example describes the access provided by a policy for the given services. For examples of
full JSON policy documents and their related summaries, see Examples of Policy Summaries (p. 275).
Service
Access level
This policy provides:
IAM
Full access
Access to all actions within the IAM service
CloudWatch
Full: List
Access to all CloudWatch actions in the List
access level, but no access to actions with the
Read, Write, or Permissions management access
level classification
Data
Pipeline
Limited: List, Read
Access to at least one but not all AWS Data
Pipeline actions in the List and Read access level,
but not the Write or Permissions management
actions
EC2
Full: List, Read Limited: Write
Access to all Amazon EC2 List and Read actions
and access to at least one but not all Amazon
EC2 Write actions, but no access to actions
with the Permissions management access level
classification
S3
Limited: Read, Write, Permissions
management
Access to at least one but not all Amazon S3 Read,
Write and Permissions management actions
codedploy
(empty)
Unknown access, because IAM does not recognize
this service
API
Gateway
None
No access is defined in the policy
CodeBuild
No access because no actions are defined
for the service. To learn how to understand
and troubleshoot this issue, see the section
called “My Policy Does Not Grant the Expected
Permissions” (p. 342)
No actions are defined.
As previously mentioned (p. 264), Full access indicates that the policy provides access to all the actions
within the service. Policies that provide access to some but not all actions within a service are further
grouped according to the access level classification. This is indicated by one of the following access-level
groupings:
• Full: The policy provides access to all actions within the specified access level classification.
• Limited: The policy provides access to one or more but not all actions within the specified access level
classification.
• None: The policy provides no access.
• (empty): IAM does not recognize this service. If the service name includes a typo, then the policy
provides no access to the service. If the service name is correct, then the service might not support
policy summaries or might be in preview. In this case, the policy might provide access, but that access
cannot be shown in the policy summary. To request policy summary support for a generally available
(GA) service, see Service Does Not Support IAM Policy Summaries (p. 341).
268
AWS Identity and Access Management User Guide
Policy Summaries
Access level summaries that include partial access to actions are grouped using the following access level
classifications:
• List (p. 530): Permission to list resources within the service to determine whether an object exists.
Actions with this level of access can list objects but cannot see the contents of a resource. For example,
the Amazon S3 action ListBucket has the List access level.
• Read (p. 551): Permission to read but not edit the contents and attributes of resources in the service.
For example, the Amazon S3 actions GetObject and GetBucketLocation have the Read access level.
• Write (p. 577): Permission to create, delete, or modify resources in the service. For example, the
Amazon S3 actions CreateBucket, DeleteBucket and PutObject have the Write access level.
• Permissions management (p. 624): Permission to grant or modify resource permissions in the
service. For example, most IAM and AWS Organizations actions, as well as actions like the Amazon S3
actions PutBucketPolicy and DeleteBucketPolicy have the Permissions management access level.
Tip
To improve the security of your AWS account, restrict or regularly monitor policies that
include the Permissions management access level classification.
Service Summary (List of Actions)
Policies are summarized in three tables: the policy summary (p. 259), the service summary, and the
action summary (p. 273). The service summary table includes a list of the actions and summaries of the
permissions that are defined by the policy for the chosen service.
You can view a service summary for each service listed in the policy summary that grants permissions.
The table is grouped into Uncategorized actions, Uncategorized resource types, and access level
sections. If the policy includes an action that IAM does not recognize, then the action is included in the
Uncategorized actions section of the table. If IAM recognizes the action, then it is included under one
of the access level (List, Read, Write and Permissions management) sections of the table. To view a
list of actions that belong to each of the action levels for a specific service, see AWS IAM Policy Actions
Grouped by Access Level (p. 529). To see a complete list of actions for a specific service, see AWS
Service Actions and Condition Context Keys for Use in IAM Policies (p. 430).
269
AWS Identity and Access Management User Guide
Policy Summaries
Viewing Service Summaries
You can view the service summary for managed policies on the Policies page, or view service summaries
for inline and managed policies attached to a user or role through the Users page and Roles page.
However, if you choose a service name on the Users page or Roles page from a managed policy, you are
redirected to the Policies page. Service summaries for managed policies must be viewed on the Policies
page.
To view the service summary for a managed policy
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Policies.
3.
In the list of policies, choose the name of the policy that you want to view.
4.
On the Summary page for the policy, view the Permissions tab to see the policy summary.
5.
In the policy summary list of services, choose the name of the service that you want to view.
To view the service summary for a policy attached to a user
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Users.
3.
In the list of users, choose the name of the user whose policy you want to view.
4.
On the Summary page for the user, view the Permissions tab to see the list of policies that are
attached to the user directly or from a group.
5.
In the table of policies for the user, expand the row of the policy that you want to view.
6.
In the policy summary list of services, choose the name of the service that you want to view.
Note
If the policy that you select is an inline policy that is attached directly to the user, then the
service summary table appears. If the policy is an inline policy attached from a group, then
you are taken to the JSON policy document for that group. If the policy is a managed policy,
then you are taken to the service summary for that policy on the Policies page.
To view the service summary for a policy attached to a role
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
Choose Roles from the navigation pane.
3.
In the list of roles, choose the name of the role whose policy you want to view.
4.
On the Summary page for the role, view the Permissions tab to see the list of policies that are
attached to the role.
5.
In the table of policies for the role, expand the row of the policy that you want to view.
6.
In the policy summary list of services, choose the name of the service that you want to view.
Understanding the Elements of a Service Summary
The example below is the service summary for Amazon S3 actions that are allowed from the
SummaryAllElements policy summary (see the section called “SummaryAllElements JSON
Policy Document” (p. 266)). The actions for this service are grouped by Uncategorized actions,
Uncategorized resource types, and access level. For example, two Write actions are defined out of the
total 29 Write actions available for the service.
270
AWS Identity and Access Management User Guide
Policy Summaries
The service summary page for a managed policy includes the following information:
1. If the policy does not grant permissions to all the actions, resources, and conditions defined for the
service in the policy, then a warning banner appears at the top of the page. The service summary
then includes details about the problem. To learn how policy summaries help you to understand and
troubleshoot the permissions that your policy grants, see the section called “My Policy Does Not Grant
the Expected Permissions” (p. 342).
2. Next to the Back link appears the name of the service (in this case S3). The service summary for this
service includes the list of allowed actions that are defined in the policy. If instead, the text (Explicitly
denied) appears next to the name of a service, then the actions listed in the service summary table are
explicitly denied.
3. Choose { } JSON to see additional details about the policy. You can do this to view all conditions that
are applied to the actions. (If you are viewing the service summary for an inline policy that is attached
directly to a user, you must close the service summary dialog box and return to the policy summary to
access the JSON policy document.)
4. To view the summary for a specific action, type keywords into the search box to reduce the list of
available actions.
5. Action (2 of 69 actions) – This column lists the actions that are defined within the policy and provides
the resources and conditions for each action. If the policy grants permissions to the action, then
the action name links to the action summary (p. 273) table. The count indicates the number of
recognized actions that provide permissions. The total is the number of known actions for the service.
In this example, 2 actions provide permissions out of 69 total known S3 actions.
6. Show/Hide remaining 67 – Choose this link to expand or hide the table to include actions that are
known but do not provide permissions for this service. Expanding the link also displays warnings for
any elements that do not provide permissions.
271
AWS Identity and Access Management User Guide
Policy Summaries
7. Unrecognized resource types – This policy includes at least one unrecognized resource type within
the policy for this service. You can use this warning to check whether a resource type might include
a typo. If the resource type is correct, then the service might not fully support policy summaries,
might be in preview, or might be a custom service. To request policy summary support for a
specific resource type in a generally available (GA) service, see Service Does Not Support IAM Policy
Summaries (p. 341). In this example, the autoscling service name is missing an a.
8. Unrecognized actions – This policy includes at least one unrecognized action within the policy for
this service. You can use this warning to check whether an action might include a typo. If the action
name is correct, then the service might not fully support policy summaries, might be in preview, or
might be a custom service. To request policy summary support for a specific action in a generally
available (GA) service, see Service Does Not Support IAM Policy Summaries (p. 341). In this example,
the DeletObject
action is missing an e.
Note
IAM reviews service names, actions, and resource types for services that support policy
summaries. However, your policy summary might include a resource value or condition that
does not exist. Always test your policies with the policy simulator (p. 283).
9. For those actions that IAM recognizes, the table groups these actions into at least one or up to four
sections, depending on the level of access that the policy allows or denies. The sections are List, Read,
Write, and Permissions management. You can also see the number of actions that are defined out
of the total number of actions available within each access level. For information about which actions
belong to each of the action levels for AWS services, see AWS IAM Policy Actions Grouped by Access
Level (p. 529). To see a complete list of actions for a specific service, see AWS Service Actions and
Condition Context Keys for Use in IAM Policies (p. 430).
10.The ellipses (…) indicate that all the actions are included in the page, but we are showing only the
rows with information relevant to this policy. When you view this page in the AWS Management
Console, you see all the actions for your service.
11.(No access) – This policy includes an action that does not provide permissions.
12.Actions that provide permissions include a link to the action summary.
13.Resource – This column shows the resources that the policy defines for the service. IAM does not
check whether the resource applies to each action. In this example, actions in the S3 service are
allowed on only the developer_bucket Amazon S3 bucket resource. Depending on the information
that the service provides to IAM, you might see an ARN such as arn:aws:s3:::developer_bucket/*, or
you might see the defined resource type, such as BucketName = developer_bucket.
Note
This column can include a resource from a different service. If the policy statement that
includes the resource does not include both actions and resources from the same service,
then your policy includes mismatched resources. IAM does not warn you about mismatched
resources when you create a policy, or when you view a policy in the service summary.
IAM also does not indicate whether the action applies to the resources, only whether the
service matches. If this column includes a mismatched resource, then you should review
your policy for errors. To better understand your policies, always test them with the policy
simulator (p. 283).
14.Resource warning – For actions with resources that do not provide full permissions, you see one of the
following warnings:
• This action does not support resource-level permissions. This requires a wildcard (*) for the
resource. – This means that the policy includes resource-level permissions but must include
"Resource": ["*"] to provide permissions for this action.
• This action does not have an applicable resource. – This means that the action is included in the
policy without a supported resource.
• This action does not have an applicable resource and condition. – This means that the action is
included in the policy without a supported resource and without a supported condition. In this case,
there is also condition included in the policy for this service, but there are no conditions that apply
to this action.
272
AWS Identity and Access Management User Guide
Policy Summaries
For the ListAllMyBuckets action, this policy includes the last warning because the action does not
support resource-level permissions and does not support the s3:x-amz-acl condition key. If you
fix either the resource problem or the condition problem, the remaining issue appears in a detailed
warning.
15.Request condition – This column tells whether the actions associated with the resource are subject
to conditions. To learn more about those conditions, choose { } JSON to review the JSON policy
document.
16.Condition warning – For actions with conditions that do not provide full permissions, you see one of
the following warnings:
• <CONDITION_KEY> is not a supported condition key for this action. – This means that the policy
includes a condition key for the service that is not supported for this action.
• Multiple condition keys are not supported for this action. – This means that the policy includes
more than one condition keys for the service that are not supported for this action.
For GetObject, this policy includes the s3:x-amz-acl condition key, which will not work with this
action. Although the action supports the resource, the policy does not grant any permissions for this
action because the condition will never be true for this action.
Action Summary (List of Resources)
Policies are summarized in three tables: the policy summary (p. 259), the service summary (p. 269),
and the action summary. The action summary table includes a list of resources and the associated
conditions that apply to the chosen action.
To view an action summary for each action that grants permissions, choose the link in the service
summary. The action summary table includes details about the resource, including its Region and
Account. You can also view the conditions that apply to each resource. This shows you conditions that
apply to some resources but not others.
Viewing Action Summaries
You can view the action summary for any policy that is attached to a user on the Users page. You can
view the action summary for any policy that is attached to a role on the Roles page. You can view
the action summary for managed policies on the Policies page. However, if you try to view the action
273
AWS Identity and Access Management User Guide
Policy Summaries
summary for a managed policy from the Users page or the Roles page, you are redirected to the Policies
page.
To view the action summary for a managed policy
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Policies.
3.
In the list of policies, choose the name of the policy that you want to view.
4.
On the Summary page for the policy, view the Permissions tab to see the policy summary.
5.
In the policy summary list of services, choose the name of the service that you want to view.
6.
In the service summary list of actions, choose the name of the action that you want to view.
To view the action summary for a policy attached to a user
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
Choose Users from the navigation pane.
3.
In the list of users, choose the name of the user whose policy you want to view.
4.
On the Summary page for the user, view the Permissions tab to see the list of policies that are
attached to the user directly or from a group.
5.
In the table of policies for the user, expand the row of the policy that you want to view.
6.
In the policy summary list of services, choose the name of the service that you want to view.
Note
If the policy that you select is an inline policy that is attached directly to the user, then the
service summary table appears. If the policy is an inline policy attached from a group, then
you are taken to the JSON policy document for that group. If the policy is a managed policy,
then you are taken to the service summary for that policy on the Policies page.
7.
In the service summary list of actions, choose the name of the action that you want to view.
To view the action summary for a policy attached to a role
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
In the navigation pane, choose Roles.
3.
In the list of roles, choose the name of the role whose policy you want to view.
4.
On the Summary page for the role, view the Permissions tab to see the list of policies that are
attached to the role.
5.
In the table of policies for the role, expand the row of the policy that you want to view.
6.
In the policy summary list of services, choose the name of the service that you want to view.
7.
In the service summary list of actions, choose the name of the action that you want to view.
Understanding the Elements of an Action Summary
The example below is the action summary for the PutObject (Write) action from the Amazon S3 service
summary (see Service Summary (List of Actions) (p. 269)). For this action, the policy defines multiple
conditions on a single resource.
274
AWS Identity and Access Management User Guide
Policy Summaries
The action summary page includes the following information:
1. Next to the Back link appears the name of the service and action in the format service: action (in
this case S3: PutObject). The action summary for this service includes the list of resources that are
defined in the policy.
2. Choose { } JSON to see additional details about the policy, such as viewing the multiple conditions
that are applied to the actions. (If you are viewing the action summary for an inline policy that is
attached directly to a user, the steps differ. To access the JSON policy document in that case, you must
close the action summary dialog box and return to the policy summary.)
3. To view the summary for a specific resource, type keywords into the search box to reduce the list of
available resources.
4. Resource – This column lists the resources that the policy defines for the chosen service. In this
example, the PutObject action is allowed on all object paths, but on only the developer_bucket
Amazon S3 bucket resource. Depending on the information that the service provides to IAM, you
might see an ARN such as arn:aws:s3:::developer_bucket/*, or you might see the defined resource
type, such as BucketName = developer_bucket, ObjectPath = All.
5. Region – This column shows the region in which the resource is defined. Resources can be defined for
all regions, or a single region. They cannot exist in more than one specific region.
• All regions – The actions that are associated with the resource apply to all regions. In this example,
the action belongs to a global service, Amazon S3. Actions that belong to global services apply to
all regions.
• Region text – The actions associated with the resource apply to one region. For example, a policy
can specify the us-west-2 region for a resource.
6. Account – This column indicates whether the services or actions associated with the resource apply to
a specific account. Resources can exist in all accounts or a single account. They cannot exist in more
than one specific account.
• All accounts – The actions that are associated with the resource apply to all accounts. In this
example, the action belongs to a global service, Amazon S3. Actions that belong to global services
apply to all accounts.
• This account – The actions that are associated with the resource apply only to the account that you
are currently logged in to.
• Account number – The actions that are associated with the resource apply to one account (one that
you are not currently logged in to). For example, if a policy specifies the 123456789012 account for a
resource, then the account number appears in the policy summary.
7. Request condition – This column shows whether the actions that are associated with the resource
are subject to conditions. This example includes the s3:x-amz-acl = public-read condition. To learn
more about those conditions, choose { } JSON to review the JSON policy document.
Examples of Policy Summaries
The following examples include JSON policies with their associated policy summaries (p. 259),
the service summaries (p. 269), and the action summaries (p. 273) to help you understand the
permissions given through a policy.
275
AWS Identity and Access Management User Guide
Policy Summaries
Policy 1: DenyCustomerBucket
This policy demonstrates an allow and a deny for the same service.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Sid": "FullAccess",
"Effect": "Allow",
"Action": ["s3:*"],
"Resource": ["*"]
},
{
"Sid": "DenyCustomerBucket",
"Action": ["s3:*"],
"Effect": "Deny",
"Resource": ["arn:aws:s3:::customer", "arn:aws:s3:::customer/*" ]
}
]
DenyCustomerBucket Policy Summary:
DenyCustomerBucket S3 (Explicit deny) Service Summary:
276
AWS Identity and Access Management User Guide
Policy Summaries
GetObject (Read) Action Summary:
Policy 2: DynamoDbRowCognitoID
This policy provides row-level access to Amazon DynamoDB based on the user's Amazon Cognito ID.
277
AWS Identity and Access Management User Guide
Policy Summaries
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem"
],
"Resource": [
"arn:aws:dynamodb:us-west-1:123456789012:table/myDynamoTable"
],
"Condition": {
"ForAllValues:StringEquals": {
"dynamodb:LeadingKeys": [
"${cognito-identity.amazonaws.com:sub}"
]
}
}
}
]
DynamoDbRowCognitoID Policy Summary:
DynamoDbRowCognitoID DynamoDB (Allow) Service Summary:
GetItem (List) Action Summary:
278
AWS Identity and Access Management User Guide
Policy Summaries
Policy 3: MultipleResourceCondition
This policy includes multiple resources and conditions.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": ["arn:aws:s3:::Apple_bucket/*"],
"Condition": {"StringEquals": {"s3:x-amz-acl": ["public-read"]}}
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": ["arn:aws:s3:::Orange_bucket/*"],
"Condition": {"StringEquals": {
"s3:x-amz-acl": ["custom"],
"s3:x-amz-grant-full-control": ["1234"]
}}
}
]
MultipleResourceCondition Policy Summary:
MultipleResourceCondition S3 (Allow) Service Summary:
PutObject (Write) Action Summary:
279
AWS Identity and Access Management User Guide
Policy Summaries
Policy 4: EC2_Troubleshoot
The following policy allows users to get a screenshot of a running Amazon EC2 instance, which can help
with EC2 troubleshooting. This policy also permits viewing information about the items in the Amazon
S3 developer bucket.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:GetConsoleScreenshot"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::developer"
]
}
]
EC2_Troubleshoot Policy Summary:
EC2_Troubleshoot S3 (Allow) Service Summary:
ListBucket (List) Action Summary:
Policy 5: Unrecognized_Service_Action
The following policy was intended to provide full access to DynamoDB, but that access fails because
dynamodb is misspelled as dynamobd. This policy was intended to allow access to some Amazon EC2
actions in the us-west-2 region, but deny that access to the ap-northeast-2 region. However, access to
280
AWS Identity and Access Management User Guide
Policy Summaries
reboot instances in the ap-northeast-2 region is not explicitly denied because of the unrecognized o in
the middle of the RebootInstances action. This example shows how you can use policy summaries to
locateerrors in your policies. To learn how to edit policies based on information in a policy summary, see
Editing Policies to Change Policy Summaries (p. 261).
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamobd:*"
],
"Resource": [
"*"
]
},
{
"Action": [
"ec2:RunInstances",
"ec2:StartInstances",
"ec2:StopInstances",
"ec2:ReboootInstances"
],
"Resource": "*",
"Effect": "Deny",
"Condition": {
"StringEquals": {
"ec2:Region": "ap-northeast-2"
}
}
},
{
"Action": [
"ec2:RunInstances",
"ec2:StartInstances",
"ec2:StopInstances",
"ec2:RebootInstances"
],
"Resource": "*",
"Effect": "Allow",
"Condition": {
"StringEquals": {
"ec2:Region": "us-east-2"
}
}
}
]
Unrecognized_Service_Action Policy Summary:
281
AWS Identity and Access Management User Guide
Policy Summaries
Unrecognized_Service_Action EC2 (Explicit deny) Service Summary:
Unrecognized_Service_Action StartInstances (Write) Action Summary:
Policy 6: CodeBuild_CodeCommit_CodeDeploy
This policy provides access to specific CodeBuild, CodeCommit, and CodeDeploy resources. Because
these resources are specific to each service, they appear only with the matching service. If you include a
resource that does not match any services in the Action element, then the resource appears in all action
summaries.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1487980617000",
"Effect": "Allow",
"Action": [
"codebuild:*",
"codecommit:*",
"codedeploy:*"
],
"Resource": [
"arn:aws:codebuild:us-west-2:123456789012:project/my-demo-project",
"arn:aws:codecommit:us-west-2:123456789012:MyDemoRepo",
"arn:aws:codedeploy:us-west-2:123456789012:application:WordPress_App",
"arn:aws:codedeploy:us-west-2:123456789012:instance/AssetTag*"
]
}
]
CodeBuild_CodeCommit_CodeDeploy Policy Summary:
282
AWS Identity and Access Management User Guide
Testing IAM Policies
CodeBuild_CodeCommit_CodeDeploy CodeBuild (Allow) Service Summary:
CodeBuild_CodeCommit_CodeDeploy StartBuild (Write) Action Summary:
Testing IAM Policies with the IAM Policy Simulator
For more information about how and why to use IAM policies, see Overview of IAM Policies (p. 232).
You can access the IAM Policy Simulator Console at: https://policysim.www.amazonaws.cn/
Getting Started with the IAM Policy Simulator
With the IAM policy simulator, you can test and troubleshoot IAM and resource-based policies in the
following ways:
• Test policies that are attached to IAM users, groups, or roles in your AWS account. If more than one
policy is attached to the user, group, or role, you can test all the policies, or select individual policies to
test. You can test which actions are allowed or denied by the selected policies for specific resources.
• Test policies that are attached to AWS resources, such as Amazon S3 buckets, Amazon SQS queues,
Amazon SNS topics, or Amazon Glacier vaults.
• If your AWS account is a member of an AWS Organization, then you can test the impact of
organization control policies on your IAM policies and resource policies.
283
AWS Identity and Access Management User Guide
Testing IAM Policies
• Test new policies that are not yet attached to a user, group, or role by typing or copying them into the
simulator. These are used only in the simulation and are not saved. Note: you cannot type or copy a
resource-based policy into the simulator. To use a resource-based policy in the simulator, you must
include the resource in the simulation and select the check box to include that resource's policy in the
simulation.
• Test the policies with selected services, actions, and resources. For example, you can test to ensure
that your policy allows an entity to perform the ListAllMyBuckets, CreateBucket, and DeleteBucket
actions in the Amazon S3 service on a specific bucket.
• Simulate real-world scenarios by providing context keys, such as an IP address or date, that are
included in Condition elements in the policies being tested.
• Identify which specific statement in a policy results in allowing or denying access to a particular
resource or action.
Topics
• How the IAM Policy Simulator Works (p. 284)
• Permissions Required for Using the IAM Policy Simulator (p. 284)
• Using the IAM Policy Simulator (AWS Management Console) (p. 287)
How the IAM Policy Simulator Works
The simulator evaluates the policies that you choose and determines the effective permissions for each
of the actions that you specify. The simulator uses the same policy evaluation engine that is used during
real requests to AWS services. But the simulator differs from the live AWS environment in the following
ways:
• The simulator does not make an actual AWS service request, so you can safely test requests that might
make unwanted changes to your live AWS environment.
• Because the simulator does not simulate running the selected actions it cannot report any response to
the simulated request. The only result returned is whether the requested action would be allowed or
denied.
• If you edit a policy inside the simulator, these changes affect only the simulator. The corresponding
policy in your AWS account remains unchanged.
Permissions Required for Using the IAM Policy Simulator
You can use the policy simulator console or the policy simulator API to test policies. By default, console
users can test policies that are not yet attached to a user, group, or role by typing or copying those
policies into the simulator. These policies are used only in the simulation and do not disclose sensitive
information. API users must have permissions to test unattached policies. To allow console or API users
to test policies that are attached to IAM users, groups, or roles in your AWS account, you must provide
users with permissions to retrieve those policies. In order to test resource-based policies, users must have
permission to retrieve the resource's policy.
For examples of console and API policies that allow a user to simulate policies, see the section called
“Example Policies: AWS Identity and Access Management (IAM)” (p. 299).
Permissions Required for Using the Policy Simulator Console
To allow users to test policies that are attached to IAM users, groups, or roles in your AWS account,
you must provide your users with permissions to retrieve those policies. In order to test resource-based
policies, users must have permission to retrieve the resource's policy.
284
AWS Identity and Access Management User Guide
Testing IAM Policies
To view an example policy that allows using the policy simulator console for policies that are attached to
a user, group, or role, see IAM: Access the Policy Simulator Console (p. 312).
To view an example policy that allows using the policy simulator console only for those users with a
specific path, see IAM: Access the Policy Simulator Console Based on User Path (p. 313).
To create a policy to allow using the policy simulator console for only one type of entity, use the
following procedures.
To allow console users to simulate policies for users
Include the following actions in your policy:
• iam:GetGroupPolicy
• iam:GetPolicy
• iam:GetPolicyVersion
• iam:GetUser
• iam:GetUserPolicy
• iam:ListAttachedUserPolicies
• iam:ListGroupsForUser
• iam:ListGroupPolicies
• iam:ListUserPolicies
• iam:ListUsers
To allow console users to simulate policies for groups
Include the following actions in your policy:
• iam:GetGroup
• iam:GetGroupPolicy
• iam:GetPolicy
• iam:GetPolicyVersion
• iam:ListAttachedGroupPolicies
• iam:ListGroupPolicies
• iam:ListGroups
To allow console users to simulate policies for roles
Include the following actions in your policy:
• iam:GetPolicy
• iam:GetPolicyVersion
• iam:GetRole
•
•
•
•
iam:GetRolePolicy
iam:ListAttachedRolePolicies
iam:ListRolePolicies
iam:ListRoles
To test resource-based policies, users must have permission to retrieve the resource's policy.
To allow console users to test resource-based policies in an Amazon S3 bucket
Include the following actions in your policy:
285
AWS Identity and Access Management User Guide
Testing IAM Policies
• s3:GetBucketPolicy
• s3:GetObjects
For example, the following policy uses these actions to allow console users to simulate a resource-based
policy in a specific Amazon S3 bucket.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:GetBucketPolicy",
"s3:GetObjects"
],
"Effect": "Allow",
"Resource":"arn:aws:s3:::<BUCKET-NAME>/*"
}
]
To allow console users to test policies for AWS Organizations
Include the following actions in your policy:
• organizations:DescribePolicy
• organizations:ListPolicies
• organizations:ListPoliciesForTarget
• organizations:ListTargetsForPolicy
Permissions Required for Using the Policy Simulator API
The policy simulator API actions GetContextKeyForCustomPolicy and SimulateCustomPolicy allow users
to test policies that are not yet attached to a user, group, or role by passing the policies as strings to the
API. These policies are used only in the simulation and do not disclose sensitive information. To allow
API users to test policies that are attached to IAM users, groups, or roles in your AWS account, you must
provide users with permissions to call GetContextKeyForPrincipalPolicy and SimulatePrincipalPolicy.
To view an example policy that allows using the policy simulator API for unattached policies and policies
attached to a user, group, or role in the current AWS account, see IAM: Access the Policy Simulator
API (p. 312).
To create a policy to allow using the policy simulator API for only one type of policy, use the following
procedures.
To allow API users to simulate policies passed directly to the API as strings
Include the following actions in your policy:
• iam:GetContextKeysForCustomPolicy
• iam:SimulateCustomPolicy
To allow API users to simulate policies attached to IAM users, groups, roles, or resources
Include the following actions in your policy:
• iam:GetContextKeysForPrincipalPolicy
286
AWS Identity and Access Management User Guide
Testing IAM Policies
• iam:SimulatePrincipalPolicy
For example, to give a user named Bob permission to simulate a policy that is assigned to a user named
Alice, give Bob access to the following resource: arn:aws:iam::777788889999:user/alice.
To view an example policy that allows using the policy simulator API only for those users with a specific
path, see IAM: Access the Policy Simulator API Based on User Path (p. 313).
Using the IAM Policy Simulator (AWS Management Console)
By default, users can test policies that are not yet attached to a user, group, or role by typing or copying
those policies into the policy simulator console. These policies are used only in the simulation and do not
disclose sensitive information.
To test a policy that is not attached to a user, group, or role using the policy simulator
console:
1.
Open the IAM policy simulator console at: https://policysim.www.amazonaws.cn/.
2.
In the Mode: menu at the top of the page, choose New Policy.
3.
4.
In the Policy Sandbox, choose Create New Policy.
Type or copy a policy into the simulator, and use the simulator as described in the following steps.
After you have been given the required permissions for using the IAM Policy Simulator Console, you can
use the simulator to test an IAM user, group, role, or resource policy.
To use the policy simulator console:
1.
Open the IAM policy simulator console at https://policysim.www.amazonaws.cn/.
Note
To sign in to the policy simulator as an IAM user, use your unique sign-in URL to sign in
to the AWS Management Console. Then go to https://policysim.www.amazonaws.cn/.
For more information about signing in as an IAM user, see How IAM Users Sign In to
AWS (p. 57).
The simulator opens in Existing Policies mode and lists the IAM users in your account under Users,
Groups, and Roles.
2.
Choose the option that is appropriate to your task:
To test this:
Do this:
A policy attached to a
user
Choose Users in the Users, Groups, and Roles list. Then choose the user.
A policy attached to a
group
Choose Groups in the Users, Groups, and Roles list. Then choose the
group.
A policy attached to a
role
Choose Roles in the Users, Groups, and Roles list. Then choose the role.
A policy attached to a
resource
See Step 8.
A custom policy
Choose New Policy from the mode list at the top. Then, in the Policy
Sandbox pane on the left, choose Create New Policy, type or paste a
policy, then choose Apply.
287
AWS Identity and Access Management User Guide
Testing IAM Policies
Tip
To test a policy that is attached to group, you can launch the IAM policy simulator directly
from the IAM console: In the navigation pane, choose Groups. Choose the name of the
group that you want to test a policy on, and then choose the Permissions tab. In the Inline
Policies or Managed Policies section, locate the policy that you want to test. In the Actions
column for that policy, choose Simulate Policy.
To test a customer managed policy that is attached to a user: In the navigation pane,
choose Users. Choose the name of the user that you want to test a policy on. Then choose
the Permissions tab and expand the policy that you want to test. On the far right, choose
Simulate policy. The IAM Policy Simulator opens in a new window and displays the
selected policy in the Policies pane.
3.
(Optional) If your account is a member of an AWS Organization, then any organization control
policies (OCPs) that affect the simulated user's account appear in the Policies pane along with IAM
policies and Resource policies. These policies are essentially filters that restrict what permissions
can be used by users, groups, or roles in an affected account. If an OCP blocks a service or action,
then no entity in that account can access that service nor perform that action. This is true even if
an administrator explicitly grants permissions to that service or action through an IAM or resource
policy. To remove an OCP from the simulation, clear the check box next to the OCP name. To view
the OCP contents, choose the name of the OCP.
If your account is not a member of an organization, then there are no OCPs to simulate.
4.
(Optional) To test only a subset of policies attached to a user, group, or role, in the Policies pane
clear the check box next to each policy that you want to exclude.
5.
Under Policy Simulator, choose Select service and then choose the service to test. Then choose
Select actions and select one or more actions to test. Although the menus show the available
selections for only one service at a time, all the services and actions that you have selected appear in
Action Settings and Results.
6.
(Optional) If any of the policies that you choose in Step 2 and Step 4 include conditions with AWS
global condition keys (p. 422), then supply values for those keys. You can do this by by expanding
the Global Settings section and typing values for the key names displayed there.
Warning
If you leave the value for a condition key empty, then that key is ignored during the
simulation. In some cases, this results in an error and the simulation fails to run. In other
cases the simulation runs, but the results might not be reliable because the simulation does
not match the real-world conditions that include a value for the condition key or variable.
7.
(Optional) Each selected action appears in the Action Settings and Results list with Not simulated
shown in the Permission column until you actually run the simulation. Before you run the
simulation, you can configure each action with a resource. To configure individual actions for a
specific scenario, choose the arrow to expand the action's row. If the action supports resource-level
permissions, you can type the Amazon Resource Name (ARN) of the specific resource whose access
you want to test. By default, each resource is set to a wildcard (*). You can also specify a value for
any condition context keys (p. 430). As noted previously, keys with empty values are ignored, which
can cause simulation failures or unreliable results.
a.
Choose the arrow next to the action name to expand each row and configure any additional
information required to accurately simulate the action in your scenario. If the action requires
any resource-level permissions, you can type the Amazon Resource Name (ARN) of the specific
resource that you want to simulate access to. By default, each resource is set to a wildcard (*).
b.
If the action supports resource-level permissions but does not require them, then you can
choose Add Resource to select the resource type that you want to add to the simulation.
c.
If any of the selected policies include a Condition element that references a context key for this
action's service, then that key name is displayed under the action. You can specify the value to
be used during the simulation of that action for the specified resource.
288
AWS Identity and Access Management User Guide
Testing IAM Policies
Actions that require different groups of resource types
Some actions require different resource types under different circumstances. Each group of resource
types is associated with a scenario. If one of these applies to your simulation, select it and the
simulator requires the resource types appropriate for that scenario. The following list shows each of
the supported scenario options and the resources that you must define to run the simulation.
Each of the following Amazon EC2 scenarios requires that you specify instance, image, and
security-group resources. If your scenario includes an EBS volume, then you must specify that
volume as a resource. If the Amazon EC2 scenario includes a virtual private cloud (VPC), then you
must supply the network-interface resource. If it includes an IP subnet, then you must specify
the subnet resource. For more information on the Amazon EC2 scenario options, see Supported
Platforms in the AWS EC2 User Guide.
• EC2-Classic-InstanceStore
instance, image, security-group
• EC2-Classic-EBS
instance, image, security-group, volume
• EC2-VPC-InstanceStore
instance, image, security-group, network-interface
• EC2-VPC-InstanceStore-Subnet
instance, image, security-group, network-interface, subnet
• EC2-VPC-EBS
instance, image, security-group, network-interface, volume
• EC2-VPC-EBS-Subnet
instance, image, security-group, network-interface, subnet, volume
8.
(Optional) If you want to include a resource-based policy in your simulation, then you must first
select the actions that you want to simulate on that resource in Step 5. Expand the rows for the
selected actions, and type the ARN of the resource with a policy that you want to simulate. Then
select Include Resource Policy next to the ARN text box. The IAM policy simulator currently
supports resource-based policies from only the following services: Amazon S3 (resource-based
policies only; ACLs are not currently supported), Amazon SQS, Amazon SNS, and unlocked Amazon
Glacier vaults (locked vaults are not currently supported).
9.
Choose Run Simulation in the upper-right corner.
The Permission column in each row of Action Settings and Results displays the result of the
simulation of that action on the specified resource.
10. To see which statement in a policy explicitly allowed or denied an action, choose the N matching
statement(s) link in the Permissions column to expand the row. Then choose the Show statement
link. The Policies pane shows the relevant policy with the statement that affected the simulation
result highlighted.
Note
If an action is implicitly denied—that is, if the action is denied only because it is not
explicitly allowed—the List and Show statement options are not displayed.
289
AWS Identity and Access Management User Guide
Testing IAM Policies
Troubleshooting IAM Policy Simulator Console Messages
The following table lists the informational and warning messages you might encounter when using the
IAM policy simulator. The table also provides steps you can take to resolve them.
Message
Steps to resolve
This policy has been edited. Changes will not be
saved to your account.
No action required.
Cannot get the resource policy. Reason: detailed
The simulator is not able to access a requested
resource-based policy. Ensure that the specified
resource ARN is correct and that the user running
the simulation has permission to read the
resource's policy.
error message
One or more policies require values in the
simulation settings. The simulation might fail
without these values.
This message is informational. If you edit an
existing policy in the IAM policy simulator, your
change does not affect your AWS account. The
simulator allows you to make changes to policies
for testing purposes only.
This message appears if the policy you are testing
contains condition keys or variables but you have
not entered any values for these keys or variables
in Simulation Settings.
To dismiss this message, choose Simulation
Settings, Then type a value for each condition key
or variable.
You have changed policies. These results are no
longer valid.
This message appears if you have changed the
selected policy while results are displayed in the
Results pane. Results shown in the Results pane
are not updated dynamically.
To dismiss this message, choose Run Simulation
again to display new simulation results based on
the changes made in the Policies pane.
The resource you entered for this simulation does
not match this service.
This message appears if you have entered an
Amazon Resource Name (ARN) in the Simulation
Settings pane that does not match the service
that you chose for the current simulation. For
example, this message appears if you specify an
ARN for an Amazon DynamoDB resource but you
chose Amazon Redshift as the service to simulate.
To dismiss this message, do one of the following:
• Remove the ARN from the box in the
Simulation Settings pane.
• Choose the service that matches the ARN that
you specified in Simulation Settings.
This action belongs to a service that supports
special access control mechanisms in addition to
resource-based policies, such as S3 ACLs or Glacier
vault lock policies. The policy simulator does not
290
No action required.
This message is informational. In the current
version, the simulator evaluates policies attached
to users and groups, and can evaluate resource-
AWS Identity and Access Management User Guide
Testing IAM Policies
Message
Steps to resolve
support these mechanisms, so the results can
differ from your production environment.
based policies for Amazon S3, Amazon SQS,
Amazon SNS, and Amazon Glacier. The policy
simulator does not support all access control
mechanisms supported by other AWS services.
DynamoDB FGAC is currently not supported.
No action required.
This informationl message refers to fine-grained
access control. This is the ability to use IAM policy
conditions to determine who can access individual
data items and attributes in DynamoDB tables
and indexes as well as the actions that can be
performed on them. The current version of the
IAM policy simulator does not support this type
of policy condition. For more information on
DynamoDB fine-grained access control, see FineGrained Access Control for DynamoDB.
You have policies that do not comply with the
policy syntax. You can use the Policy Validator to
review and accept the recommended updates to
your policies.
This message appears at the top of the policy
list if you have policies that do not comply with
the IAM policy grammar. In order to simulate
these policies, follow the instructions at Using
Policy Validator (p. 292) to identify and fix these
policies.
This policy must be updated to comply with the
latest policy syntax rules.
This message is displayed if you have policies
that do not comply with the IAM policy grammar.
In order to simulate these policies, follow the
instructions at Using Policy Validator (p. 292) to
identify and fix these policies.
Using the IAM Policy Simulator (AWS CLI, Tools for Windows PowerShell, and
AWS API)
Policy simulator commands typically require calling APIs to do two things:
1. Evaluate the policies and return the list of context keys that they reference. You need to know what
context keys are referenced so that you can supply values for them in the next step.
2. Simulate the policies, providing a list of actions, resources, and context keys that are used during the
simulation.
For security reasons, the APIs have been broken into two groups:
• API actions that simulate only policies that are passed directly to the API as strings. This set includes
GetContextKeysForCustomPolicy and SimulateCustomPolicy.
• API actions that simulate the policies that are attached to a specified IAM user, group, role, or resource.
Because these APIs can reveal details of permissions assigned to other IAM entities, you should
consider restricting access to these API actions. This set includes GetContextKeysForPrincipalPolicy
and SimulatePrincipalPolicy. For more information about restricting access to API actions, see Example
Policies: AWS Identity and Access Management (IAM) (p. 299).
In both cases, the API actions simulate the effect of one or more policies on a list of actions and
resources. Each action is paired with each resource and the simulation determines whether the policies
291
AWS Identity and Access Management User Guide
Using Policy Validator
allow or deny that action for that resource. You can also provide values for any context keys that
your policies reference. You can get the list of context keys that the policies reference by first calling
GetContextKeysForCustomPolicy or GetContextKeysForPrincipalPolicy. If you don't provide a value
for a context key, the simulation still runs. But the results might not be reliable because the simulator
cannot include that context key in the evaluation.
To get the list of context keys
Use these commands to evaluate a list of policies and return a list of context keys that are used in the
policies.
• AWS CLI: aws iam get-context-keys-for-custom-policy and aws iam get-context-keys-forprincipal-policy
• Tools for Windows PowerShell: Get-IAMContextKeysForCustomPolicy and GetIAMContextKeysForPrincipalPolicy
• AWS API: GetContextKeysForCustomPolicy and GetContextKeysForPrincipalPolicy
To simulate IAM policies
Use these commands to simulate IAM policies to determine a user's effective permissions.
• AWS CLI: aws iam simulate-custom-policy and aws iam simulate-principal-policy
• Tools for Windows PowerShell: Test-IAMCustomPolicy and Test-IAMPrincipalPolicy
• AWS API: SimulateCustomPolicy and SimulatePrincipalPolicy
Using Policy Validator
Policy Validator automatically examines your new and existing IAM access control policies to ensure that
they comply with the IAM policy grammar. A policy is a JSON document written using the IAM policy
grammar. It defines access permissions for the AWS user, group, or role you attach the policy to. If the
Policy Validator determines that a policy is not in compliance with the grammar, it prompts you to fix the
policy. Policy Validator is only available if you have non-compliant policies.
You can access the policy simulator three ways:
1. Creating policies - When you create a new policy, you can choose Validate Policy to check your policy,
or the policy validator runs automatically when you choose Create Policy. If the policy is not valid, you
receive a notification and must fix the problem before you can continue.
2. Editing policies - When you edit an existing policy, you can choose Validate policy to check your
policy, or the policy validator runs automatically when you choose Save. If the policy is not valid, you
receive a notification and must fix the problem before you can continue.
3. Viewing policies - If you have a policy that was created before the policy validator was released, that
policy could include errors. When you view a policy, the policy validator runs in the background. If the
policy is not valid, you receive a notification about the problem.
Important
You cannot save any new or updated policies that do not comply with the policy syntax. If a
policy fails validation, it cannot be saved until the error is corrected. Existing policies with errors
that were set up prior to the introduction of the Policy Validator will continue to function,
however you cannot edit and save them without fixing the policy syntax errors.
Note
The policy validator only checks JSON policy syntax and grammar. It does not validate that your
ARNs, action names, or condition keys are correct.
292
AWS Identity and Access Management User Guide
Service Last Accessed Data
Identifying and fixing non-compliant access control policies to comply with the policy
grammar
1.
Sign in to the IAM console. If you have any non-compliant policies, a yellow banner titled Fix policy
syntax appears at the top of the console screen. If this banner does not appear, then all of your
policies are in good shape and you can stop right now.
2.
3.
Click the Fix Now link.
A list of the non-compliant policies appears. Select the policy that you want to correct by clicking
the policy name.
4.
A screen similar to the following appears, showing the recommended changes to your policy at
the top of the page in an editing window and the original version at the bottom. In the following
example, the policy engine recommends changing two separate Resource elements (not valid) into
a single Resource array element with two items in it (valid). For more information about the policy
rules, see the AWS IAM Policy Reference.
Do one of the following:
5.
6.
• If you want to accept the recommended changes, click Apply Changes.
• If you want to alter the policy further, you can edit directly in the top edit box. If you make any
changes, the Validate button is enabled. When you are done, check the syntax against the rules by
clicking Validate. If Policy Validator confirms that your edited policy is OK, click Apply Changes.
If errors are reported, continue to edit the policy until it passes validation and then click Apply
Changes.
You are returned to the list of non-compliant policies, if any. Repeat the procedure for each until you
have fixed all of your policies.
You can edit any of your policies on your own at any time, without using the Policy Validator. If you fix
any compliance issues then they are automatically removed from the list of non-compliant policies.
Service Last Accessed Data
The IAM console provides information about when IAM users and roles last attempted to access AWS
services. This information is called service last accessed data. This data can help you identify unnecessary
permissions so that you can refine your IAM policies to better adhere to the principle of "least privilege."
That means granting the minimum permissions required to perform a specific task.
You can get the date and hour when an IAM entity (user, group, or role) last accessed an AWS service
through IAM policy permissions. You can use this information to identify unused and not recently used
permissions in your IAM policies. You can then choose to remove permissions for unused services or
reorganize users with similar usage patterns into a group to help improve account security. Knowing if
and when an IAM entity last exercised a permission can help you remove unnecessary permissions and
tighten your IAM policies with less effort.
293
AWS Identity and Access Management User Guide
Service Last Accessed Data
Important
The service last accessed data includes all attempts to access an AWS API, not just the successful
ones. This includes all access attempts made using the AWS Management Console, the AWS
API through any of the SDKs, or any of the command line tools. An unexpected entry in the
service last accessed data does not mean that your account has been compromised, because
the request might have been denied. Refer to your CloudTrail logs as the authoritative source
for information about all API calls and whether they were successful or denied access. For more
information, see Logging IAM Events with AWS CloudTrail (p. 323).
This topic describes the functionality of the IAM service last accessed data and how you can use it with
the IAM console. It also describes two practical scenarios of using the service last accessed data to
remove unnecessary permissions from an IAM policy.
Topics
• Viewing Access Advisor Information (p. 294)
• Notes (p. 295)
• Troubleshooting Tips (p. 296)
• Sample Usage Scenarios (p. 296)
• Tracking Period Regional Differences (p. 298)
Viewing Access Advisor Information
You can find the data on the Access Advisor tab in the IAM console by examining the detail view for any
IAM user, group, role, or managed policy.
Minimum permissions to see access advisor information
Users must have permission to see user, group, role, and policy details in order to view those
entities in the IAM console. However, in order to view the service last accessed data, you must
also have permission to use the following actions:
• iam:GenerateServiceLastAccessedDetails
• iam:GetServiceLastAccessedDetails
• iam:GetServiceLastAccessedDetailsWithEntities
• iam:ListPoliciesGrantingServiceAccess
Because these actions are not specific to a single resource, administrators should provide access
to use these actions on all resources ("Resource": "*").
Be aware that granting these permissions enables the user to see which users, groups, or roles
are attached to a managed policy, which services a user or role has access to, and which services
have been accessed, by whom, and when. This is similar to the iam:ListEntitiesForPolicy and
iam:ListAttached[User/Group/Role]Policies permissions.
To view access advisor information
1.
2.
3.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
In the navigation pane, choose either Groups, or Users, or Roles, or Policies.
Choose any user, group, role, or policy name to open its detailed view and choose the Access
Advisor tab. The tab displays a table with the following columns:
Service Name
A list of services with permissions granted by an IAM policy (if you are examining a policy), or
the list of services with permissions granted to the IAM entity by all IAM policies (if you are
examining a user, group, or role).
294
AWS Identity and Access Management User Guide
Service Last Accessed Data
A row for a service appears if the entity is granted any permission to that service by an IAM
policy, whether that permission is for only one action in the service or all of them.
Policies Granting Permissions
The name of one policy and a count of other polices that grant this entity permission to access
the specified service. Choose the link with the policy name and count to see a list of all of
the IAM policies that grant this entity permission to access the specified service. The list also
includes the name, the type of policy (AWS managed, customer managed, or inline), and the
group (if applicable) through which a user gets the policy.
If you choose the name of a managed policy in the Policies Granting Permissions dialog box,
IAM opens a new browser tab that shows the policy text. If you click a group name in the dialog
box, IAM opens a new browser tab that displays the details for the group.
Last Accessed
The length of time since this user, role, or a member of a group last accessed the specified
service.
The service last accessed data goes back to the tracking start date for your region (p.
).
That date through the present is called the tracking period. If the service has never been
accessed, or has not been accessed any time during the tracking period, then the message Not
accessed in the tracking period appears in place of a time stamp. Activity that occurred before
the tracking period is not available.
Access by Members
(Group only) The name of one user and a count of other users who are members of the group
and that have accessed this service. Choose the link to see a list of all of the IAM users who are
members of the group and when each member last accessed the specified service.
If you choose the name of a user in the dialog box, IAM opens a new browser tab that displays
the details for the user.
Access by Entities
(Policy only) The name of one user or role and a count of other users and roles who have used
this policy to access the specified service. Choose the link to see a list of all of the users and
roles to which this policy is attached and when each last accessed the specified service.
Additional options
• Use the Filter menu on the Access Advisor tab to limit the list to Services accessed and Services
not accessed. For example, you might select Services not accessed for a policy to discover which
services listed in that policy are never used. In that case, you might want to remove those services
from the policy. You can also type a name (or part of a name) in the search box to restrict the list
to only those entities whose name matches what you type.
• Choose one of the column heads to sort the information according to that column's information.
Choose the header a second time to sort in the opposite order.
Notes
• The list of services in the table reflects the current state of your IAM policies, not any historical state.
For example, if the current version of your policy allows only Amazon S3 access and it previously
allowed access to other AWS services, the service last accessed data shows only a table entry for
Amazon S3. If you are trying to determine the history of access control changes in your account, or
want to audit historical access, we recommend that you use AWS CloudTrail.
295
AWS Identity and Access Management User Guide
Service Last Accessed Data
• It usually takes less than 4 hours for recent Last Accessed activity to appear in the table. However,
under some circumstances it can take up to 12 hours. If the service is running unusually slow, a
notification appears in the IAM console.
Troubleshooting Tips
If the service last accessed table is empty, it might be caused by one of the following:
• You selected a user that has no attached policies, either directly or through group memberships.
• You selected a managed policy attached to a group that has no members.
• You selected a user, group, or role that has neither inline nor managed policies attached.
• You selected a user that has permissions granted only by a resource-based policy.
Sample Usage Scenarios
Some examples that show the value of using the IAM access advisor for both policies (the first example)
and principals (the second).
Scoping Down Permissions for an IAM Policy
Imagine an administrator who is responsible for managing a team’s AWS infrastructure. The team has
created an application that runs on Amazon EC2 and calls other AWS services. This means that the
administrator needs to provision an EC2 instance for this application and manage its configuration. One
part of this is to attach an IAM role to this EC2 instance.
Note
You can attach IAM roles to EC2 instances to enable applications that run on those instances
to make API requests. That way you don't need to manually manage the security credentials
that the applications use. Instead of creating and distributing your AWS credentials, you can
delegate permission to make API requests to an IAM role that is assigned to the instance. For
more information, see IAM Roles for Amazon EC2.
However, the administrator is new to IAM and when attaching the IAM role to the EC2 instance, the
administrator is not sure what to put in the role’s permission policy. The administrator wants to
implement a thorough access control mechanism, but the immediate priority is to make sure that the
application works. To do that the administrator simply copies the PowerUserAccess AWS managed policy
shown below with the intention of modifying it as it becomes clear over time what permissions are really
needed. This policy grants full read-write permissions to all AWS services and resources in the account
except for IAM (and is definitely not recommended as a long-term solution).
{
}
"Statement": [
{
"Effect": "Allow",
"NotAction": "iam:*",
"Resource": "*"
}
]
After the application runs for a while, the administrator can use the service last accessed data to
view which permissions are actually used. The administrator can then reduce the permissions for the
application. The administrator signs in to the IAM console and chooses Policies, finds the policy attached
to the IAM role associated with the EC2 instance where the application is running. The administrator then
chooses the policy name to view its details and chooses the Access Advisor tab.
296
AWS Identity and Access Management User Guide
Service Last Accessed Data
The administrator reviews the time stamps listed in the Last Accessed column and notices that the
team's application is using only Amazon DynamoDB, Amazon S3, Amazon CloudWatch, Amazon Simple
Notification Service (Amazon SNS), and Amazon Simple Queue Service (Amazon SQS). The administrator
can then choose the Permissions tab and expand the row for a policy whose permissions need to be
restricted. The administrator chooses Edit policy for inline policies that are attached directly to the
user. To edit a managed policy, the administrator chooses the name of the policy to go to the Policies
page. From there, administrators can revise the policy's access to include only those permissions that are
required for the application to successfully run.
Scoping Down Permissions for an IAM User
Imagine an IT administrator who is responsible for ensuring that people in the organization do not have
excess AWS permissions. As part of a periodic security check, the administrator reviews the permissions
of all IAM users. One of these users is an application developer, who previously filled the role of a
security engineer. Because of the change in job requirements, the developer is a member of both the
“app-dev” group for the new job (which grants permissions to multiple services including Amazon EC2,
Amazon EBS, Auto Scaling, etc.) and the “security-team” group for the old job (which grants permissions
to IAM and CloudTrail).
The administrator signs into the IAM console and chooses Users, then chooses the name of the IAM user
of the developer and then chooses the Access Advisor tab.
The administrator reviews the time stamps in the Last Accessed column and notices that the developer
has not recently accessed IAM, CloudTrail, Amazon Route 53, Amazon Elastic Transcoder, and a number
of other AWS services. The administrator is now ready to act on the service last accessed information.
However, unlike the previous example, the next steps for a principal like the developer's IAM user (who
may be subject to multiple policies and a member of multiple IAM groups) requires the administrator
to proceed with caution to avoid inadvertently disrupting other users’ access. So his first step is to
determine how the developer is receiving these permissions.
The administrator confirms that the developer has no business need for access to IAM and CloudTrail
anymore because the developer is no longer a member of the internal security team. For these
permissions, after analyzing the group memberships and policies, the administrator realizes that the
simplest solution is to remove the developer’s membership in the security-team IAM group, rather than
make any policy changes.
The administrator might also infer that the developer’s access to Amazon Route 53, Elastic Transcoder,
etc. from the app-dev group should also be revoked due to lack of use. However, before cutting these
permissions out of the app-dev policy (which may adversely affect other members of the group), the
administrator should consult the service last accessed data for the app-dev group policies. That data can
reveal whether these permissions are universally unused by all app-dev group members or simply unused
by this particular developer. If they are truly unused by all group members, then the administrator can
probably safely remove those permissions from the app-dev group's policy. If it is only this one developer
that is not using the permissions, then the administrator may want to craft a different set of permissions
for the developer. Another option is for the administrator to do nothing, accepting that not all users
exercise all the permissions granted to them.
As this example shows, you might use the service last accessed data for principals as a starting point for
a number of possible next steps, including the following suggestions. However, it’s up to you as an IAM
administrator to choose the steps that strike the right balance of accessibility and least-privilege that’s
appropriate to your organization.
•
•
•
•
•
Removing membership in a group (p. 95)
Detaching a managed policy (p. 251)
Deleting a managed policy (p. 254)
Deleting an inline policy and converting to a managed policy (p. 256)
Editing an existing policy to remove permissions (p. 252)
• Adding an explicit deny to an existing policy (p. 409)
297
AWS Identity and Access Management User Guide
Example Policies
Tracking Period Regional Differences
AWS began collecting service last accessed data in most regions on October 1, 2015. As AWS adds
support for service last accessed to additional regions, those regions have different dates for when
tracking in those regions begins. Here is a list of the regions that have later tracking period start dates:
Region
Tracking period start date
Initially supported regions:
October 1, 2015
•
•
•
•
(us-west-2)
US East (N. Virginia) (us-east-1)
US West (N. California) (us-west-1)
US West (Oregon) (us-west-2)
• Asia Pacific (Tokyo) (ap-northeast-1)
• Asia Pacific (Singapore) (ap-southeast-1)
• Asia Pacific (Sydney) (ap-southeast-2)
• EU (Frankfurt) (eu-central-1)
• EU (Ireland) (eu-west-1)
South America (São Paulo) (sa-east-1)
December 11, 2015
Asia Pacific (Seoul) (ap-northeast-2)
January 6, 2016
Asia Pacific (Mumbai) (ap-south-1)
June 27, 2016
If a region is not listed in the previous table, then that region does not yet provide service last accessed
data.
Example Policies
An IAM policy is a JSON document that formally states one or more permissions that you can apply to
identities in IAM. By default all requests are denied, so you must provide access to the services, actions,
and resources that you intend for the identity to access. If you also want to allow access to complete the
specified actions in the IAM console, you need to provide additional permissions.
The following library of policies can help you define permissions for your IAM identities. After you find
the policy that you need, choose View this policy to view the JSON for the policy. You can use the JSON
policy document as a template for your own policies.
Note
If you would like to submit a policy to be included in this reference guide, use the Feedback
button at the bottom of this page.
Example Policies: AWS
• Allows access during a specific range of dates (View this policy (p. 300))
• Denies access to AWS based on the source IP address (View this policy (p. 300))
Example Policies: AWS CodeCommit
• Allows Read access to an AWS CodeCommit repository, programmatically and in the console (View this
policy (p. 301))
298
AWS Identity and Access Management User Guide
Example Policies
Example Policies: AWS Data Pipeline
• Denies access to pipelines that a user did not create (View this policy (p. 301))
Example Policies: Amazon DynamoDB
• Allows access to a specific Amazon DynamoDB table (View this policy (p. 302))
• Allows access to specific Amazon DynamoDB columns (View this policy (p. 303))
• Allows row-level access to Amazon DynamoDB based on an Amazon Cognito ID (View this
policy (p. 303))
Example Policies: Amazon EC2
• Allows an Amazon EC2 instance to attach or detach volumes (View this policy (p. 304))
• Allows attaching or detaching Amazon EBS volumes to Amazon EC2 instances based on tags (View this
policy (p. 305))
• Allows launching Amazon EC2 instances in a specific subnet, programmatically and in the console
(View this policy (p. 305))
• Allows managing Amazon EC2 security groups associated with a specific VPC, programmatically and in
the console (View this policy (p. 306))
• Allows starting or stopping Amazon EC2 instances a user has tagged, programmatically and in the
console (View this policy (p. 306))
• Allows full Amazon EC2 access within a specific region, programmatically and in the console (View this
policy (p. 307))
• Allows starting or stopping a specific Amazon EC2 instance and modifying a specific security group,
programmatically and in the console (View this policy (p. 307))
• Limits terminating Amazon EC2 instances to a specific IP address range (View this policy (p. 308))
Example Policies: AWS Elastic Beanstalk
• Allows access to a specific AWS Elastic Beanstalk application, environment, and version (View this
policy (p. 309))
• Allows full access to a specific AWS Elastic Beanstalk environment or application (View this
policy (p. 310))
Example Policies: AWS Identity and Access Management (IAM)
• Allows access to the policy simulator API (View this policy (p. 312))
• Allows access to the policy simulator console (View this policy (p. 312))
• Allows using the policy simulator API for users with a specific path (View this policy (p. 313))
• Allows using the policy simulator console for users with a specific path (View this policy (p. 313))
• Allows IAM users to rotate their own credentials, programmatically and in the console (View this
policy (p. 314))
• Limits managed policies that can be applied to a new IAM user, group, or role (View this
policy (p. 314))
299
AWS Identity and Access Management User Guide
Example Policies
Example Policies: Amazon RDS
• Allows full Amazon RDS database access within a specific region (View this policy (p. 315))
• Allows restoring Amazon RDS databases, programmatically and in the console (View this
policy (p. 316))
• Allows tag owners full access to Amazon RDS resources that they have tagged (View this
policy (p. 316))
Example Policies: Amazon S3
• Allows an Amazon Cognito user to access objects in their own Amazon S3 bucket (View this
policy (p. 318))
• Allows IAM users to access their own home directory in Amazon S3, programmatically and in the
console (View this policy (p. 319))
• Allows a user to manage a single Amazon S3 bucket and denies every other AWS action and resource
(View this policy (p. 319))
• Allows Read and Write access to a specific Amazon S3 bucket (View this policy (p. 320))
• Allows Read and Write access to a specific Amazon S3 bucket, programmatically and in the console
(View this policy (p. 321))
AWS: Allows Access Within Specific Dates
This example shows how you might create a policy that allows access to the ACTION-NAME action in
the service named SERVICE-NAME. Access is restricted to actions that occur between July 1, 2017 and
December 31, 2017 (UTC), inclusive. To use this policy, replace the red text in the example policy with
your own information.
To learn about using multiple conditions within the Condition block of an IAM policy, see Multiple Values
in a Condition (p. 386).
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "<SERVICE-NAME>:<ACTION-NAME>",
"Resource": "*",
"Condition": {
"DateGreaterThan": {"aws:CurrentTime": "2017-07-01T00:00:00Z"},
"DateLessThan": {"aws:CurrentTime": "2017-12-31T23:59:59Z"}
}
}
AWS: Denies Access to AWS Based on the Source IP
This example shows how you might create a policy that denies access to all AWS actions in the account
when the request comes from outside the specified IP range. The policy is useful when the IP addresses
for your company are within the specified ranges. This policy also provides the permissions necessary to
complete this action on the console. To use this policy, replace the red text in the example policy with
your own information.
The aws:SourceIp condition key denies access to an AWS service, such as AWS CloudFormation, that
makes calls on your behalf. For more information about using the aws:SourceIp condition key, see
Available Global Condition Keys (p. 423).
300
AWS Identity and Access Management User Guide
Example Policies
Important
This policy does not allow any actions. Use this policy in combination with other policies that
allow specific actions.
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Deny",
"Action": "*",
"Resource": "*",
"Condition": {"NotIpAddress": {"aws:SourceIp": [
"192.0.2.0/24",
"203.0.113.0/24"
]}}
}
}
AWS CodeCommit: Allows Read Access to an AWS CodeCommit
Repository, Programmatically and in the Console
This example shows how you might create a policy that allows Read access to a specific CodeCommit
repository. This policy also provides the permissions necessary to complete this action on the console. To
use this policy, replace the red text in the example policy with your own information.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"codecommit:GitPull"
],
"Resource": "arn:aws:codecommit:<REGION>:<ACCOUNTNUMBER>:<REPO-NAME>"
},
{
"Effect": "Allow",
"Action": [
"codecommit:Get*",
"codecommit:BatchGetRepositories",
"codecommit:List*"
],
"Resource": "*"
}
]
AWS Data Pipeline: Denies Access to DataPipeline Pipelines That
a User Did Not Create
This example shows how you might create a policy that denies access to pipelines that a user did not
create. If the value of the PipelineCreator field matches the IAM user name, then the specified actions
are not denied.
Important
This policy does not allow any actions. Use this policy in combination with other policies that
allow specific actions.
{
301
AWS Identity and Access Management User Guide
Example Policies
}
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ExplicitDenyIfNotTheOwner",
"Effect": "Deny",
"Action": [
"datapipeline:ActivatePipeline",
"datapipeline:AddTags",
"datapipeline:DeactivatePipeline",
"datapipeline:DeletePipeline",
"datapipeline:DescribeObjects",
"datapipeline:EvaluateExpression",
"datapipeline:GetPipelineDefinition",
"datapipeline:PollForTask",
"datapipeline:PutPipelineDefinition",
"datapipeline:QueryObjects",
"datapipeline:RemoveTags",
"datapipeline:ReportTaskProgress",
"datapipeline:ReportTaskRunnerHeartbeat",
"datapipeline:SetStatus",
"datapipeline:SetTaskStatus",
"datapipeline:ValidatePipelineDefinition"
],
"Resource": [
"*"
],
"Condition": {
"StringNotEquals": {
"datapipeline:PipelineCreator": "${aws:userid}"
}
}
}
]
Amazon DynamoDB: Allows Access to a Specific Table
This example shows how you might create a policy that allows full access to a DynamoDB table with the
specified name. To use this policy, replace the red text in the example policy with your own information.
Important
This policy allows all actions that can be performed on a DynamoDB table. To review these
actions, see DynamoDB API Permissions: Actions, Resources, and Conditions Reference in the
Amazon DynamoDB Developer Guide. You could provide the same permissions by listing each
individual action. However, if you use the "Action":"dynamodb:*" element, then you will not
need to update your policy if DynamoDB adds a new action for DynamoDB tables.
This policy allows actions only on DynamoDB tables that exist with the specified name.
To allow your users Read access to everything in DynamoDB, you can also attach the
AmazonDynamoDBReadOnlyAccess AWS managed policy.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "arn:aws:dynamodb:<REGION>:<ACCOUNTNUMBER>:table/<TABLE-NAME>"
}
]
302
AWS Identity and Access Management User Guide
Example Policies
Amazon DynamoDB: Allows Access to Specific Columns
This example shows how you might create a policy that allows access to the specific DynamoDB columns.
To use this policy, replace the red text in the example policy with your own information.
The dynamodb:Select requirement prevents the API action from returning any attributes that aren't
allowed, such as from an index projection. To learn more about DynamoDB condition keys, see Specifying
Conditions: Using Condition Keys in the Amazon DynamoDB Developer Guide. To learn about using
multiple conditions or multiple condition keys within the Condition block of an IAM policy, see Multiple
Values in a Condition (p. 386).
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:GetItem",
"dynamodb:BatchGetItem",
"dynamodb:Query",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:BatchWriteItem"
],
"Resource": [
"arn:aws:dynamodb:<REGION>:<ACCOUNTNUMBER>:table/<TABLE-NAME>"
],
"
"Condition": {
"ForAllValues:StringEquals": {
"dynamodb:Attributes": [
"<COLUMN-NAME-1>",
"<COLUMN-NAME-2>",
"<COLUMN-NAME-3>"
]
},
"StringEqualsIfExists": {
"dynamodb:Select": "SPECIFIC_ATTRIBUTES"
}
}
}
]
Amazon DynamoDB: Allows Row-Level Access to DynamoDB
Based on an Amazon Cognito ID
This example shows how you might create a policy that allows row-level access to a specific DynamoDB
table based on an Amazon Cognito ID. To use this policy, replace the red text in the example policy with
your own information.
To use this policy, you must structure your DynamoDB table so the Cognito user ID is the partition key.
For more information, see Creating a Table in the Amazon DynamoDB Developer Guide.
To learn more about DynamoDB condition keys, see Specifying Conditions: Using Condition Keys in the
Amazon DynamoDB Developer Guide.
{
303
AWS Identity and Access Management User Guide
Example Policies
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:PutItem",
"dynamodb:Query",
"dynamodb:UpdateItem"
],
"Resource": [
"arn:aws:dynamodb:<REGION>:<ACCOUNTNUMBER>:table/<TABLE-NAME>"
],
"Condition": {
"ForAllValues:StringEquals": {
"dynamodb:LeadingKeys": [
"${cognito-identity.amazonaws.com:sub}"
]
}
}
}
]
Amazon EC2: Allows an EC2 Instance to Attach or Detach
Volumes
This example shows how you might create a policy that can be attached to a service role. The policy
allows the specified EC2 instance to attach or detach volumes. The instance is specified with an ARN
in the Condition element. To use this policy, replace the red text in the example policy with your own
information.
Amazon EC2 instances can run AWS commands with permissions granted by an AWS service role for an
EC2 instance (p. 98) that is attached to the instance profile. You can attach this policy to the role, or add
this statement to an existing policy. Only the instance identified by INSTANCE-ID can attach or detach
volumes to instances in the account, including its own. Other statement elements that might exist in
a larger policy are not impacted by the restriction of this one statement. For more information about
creating IAM policies to control access to Amazon EC2 resources, see Controlling Access to Amazon EC2
Resources in the Amazon EC2 User Guide for Linux Instances.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:AttachVolume",
"ec2:DetachVolume"
],
"Resource": [
"arn:aws-cn:ec2:<REGION>:<ACCOUNTNUMBER>:volume/*",
"arn:aws-cn:ec2:<REGION>:<ACCOUNTNUMBER>:instance/*"
],
"Condition": {
"ArnEquals": {
"ec2:SourceInstanceARN": "arn:awscn:ec2:<REGION>:<ACCOUNTNUMBER>:instance/<INSTANCE-ID>"
}
}
}
]
304
AWS Identity and Access Management User Guide
Example Policies
}
Amazon EC2: Attach or Detach Amazon EBS Volumes to EC2
Instances Based on Tags
This example shows how you might create a policy that allows EBS volume owners to attach or detach
their EBS volumes defined using the tag volume_user to EC2 instances that are tagged as development
instances (department=dev). To use this policy, replace the red text in the example policy with your own
information.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:AttachVolume",
"ec2:DetachVolume"
],
"Resource": "arn:aws-cn:ec2:<REGION>:<ACCOUNTNUMBER>:instance/*",
"Condition": {"StringEquals": {"ec2:ResourceTag/department": "dev"}}
},
{
"Effect": "Allow",
"Action": [
"ec2:AttachVolume",
"ec2:DetachVolume"
],
"Resource": "arn:aws-cn:ec2:<REGION>:<ACCOUNTNUMBER>:volume/*",
"Condition": {"StringEquals": {"ec2:ResourceTag/volume_user": "${aws:username}"}}
}
]
Amazon EC2: Allows Launching EC2 Instances in a Specific
Subnet, Programmatically and in the Console
This example shows how you might create a policy that allows listing information for all EC2 objects
and launching EC2 instances in a specific subnet. This policy also provides the permissions necessary to
complete this action on the console. To use this policy, replace the red text in the example policy with
your own information.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:Describe*",
"ec2:GetConsole*"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ec2:RunInstances",
"Resource": [
"arn:aws:ec2:<REGION>:<ACCOUNTNUMBER>:subnet/subnet-<SUBNET-ID>",
"arn:aws:ec2:<REGION>:<ACCOUNTNUMBER>:network-interface/*",
305
AWS Identity and Access Management User Guide
Example Policies
}
]
}
]
"arn:aws:ec2:<REGION>:<ACCOUNTNUMBER>:instance/*",
"arn:aws:ec2:<REGION>:<ACCOUNTNUMBER>:volume/*",
"arn:aws:ec2:<REGION>::image/ami-*",
"arn:aws:ec2:<REGION>:<ACCOUNTNUMBER>:key-pair/*",
"arn:aws:ec2:<REGION>:<ACCOUNTNUMBER>:security-group/*"
Amazon EC2: Allows Managing EC2 Security Groups Associated
With a Specific VPC, Programmatically and in the Console
This example shows how you might create a policy that allows managing Amazon EC2 security groups
associated with a specific virtual private cloud (VPC). This policy also provides the permissions necessary
to complete this action on the console. To use this policy, replace the red text in the example policy with
your own information.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:AuthorizeSecurityGroupEgress",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:DeleteSecurityGroup",
"ec2:RevokeSecurityGroupEgress",
"ec2:RevokeSecurityGroupIngress"
],
"Resource": "arn:aws:ec2:<REGION>:<ACCOUNTNUMBER>:security-group/*",
"Condition": {
"StringEquals": {
"ec2:Vpc": "arn:aws:ec2:<REGION>:<ACCOUNTNUMBER>:vpc/vpc-<VPC-ID>"
}
}
},
{
"Action": [
"ec2:DescribeSecurityGroups",
"ec2:DescribeSecurityGroupReferences",
"ec2:DescribeStaleSecurityGroups",
"ec2:DescribeVpcs"
],
"Effect": "Allow",
"Resource": "*"
}
]
Amazon EC2: Allows Starting or Stopping EC2 Instances a User
Has Tagged, Programmatically and in the Console
This example shows how you might create a policy that allows an IAM user to start or stop EC2 instances,
but only if the instance tag Owner has the value of that user's user name. This policy also provides the
permissions necessary to complete this action on the console. To use this policy, replace the red text in
the example policy with your own information.
{
306
AWS Identity and Access Management User Guide
Example Policies
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:StartInstances",
"ec2:StopInstances"
],
"Resource": "arn:aws:ec2:<REGION>:<ACCOUNTNUMBER>:instance/*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/Owner": "${aws:username}"
}
}
},
{
"Effect": "Allow",
"Action": "ec2:DescribeInstances",
"Resource": "*"
}
]
Amazon EC2: Allows Full EC2 Access Within a Specific Region,
Programmatically and in the Console
This example shows how you might create a policy that allows full EC2 access within a specific region.
This policy also provides the permissions necessary to complete this action on the console. To use this
policy, replace the red text in the example policy with your own information.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Action": "ec2:*",
"Resource": "*",
"Effect": "Allow",
"Condition": {
"StringEquals": {
"ec2:Region": "<REGION>"
}
}
}
]
Amazon EC2: Allows Starting or Stopping an EC2 Instance
and Modifying a Security Group, Programmatically and in the
Console
This example shows how you might create a policy that allows starting or stopping a specific EC2
instance and modifying a specific security group. This policy also provides the permissions necessary to
complete this action on the console. To use this policy, replace the red text in the example policy with
your own information.
{
"Version": "2012-10-17",
"Statement": [
{
307
AWS Identity and Access Management User Guide
Example Policies
},
{
ID>"
}
]
}
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSecurityGroupReferences",
"ec2:DescribeStaleSecurityGroups"
],
"Resource": "*",
"Effect": "Allow"
"Action": [
"ec2:AuthorizeSecurityGroupEgress",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:RevokeSecurityGroupEgress",
"ec2:RevokeSecurityGroupIngress",
"ec2:StartInstances",
"ec2:StopInstances"
],
"Resource": [
"arn:aws:ec2:<REGION>:<ACCOUNTNUMBER>:instance/i-<INSTANCE-ID>",
"arn:aws:ec2:<REGION>:<ACCOUNTNUMBER>:security-group/sg-<SECURITY-GROUP],
"Effect": "Allow"
Amazon EC2: Limits Terminating EC2 Instances to an IP Address
Range
This example shows how you might create a policy that limits EC2 instances by allowing the action, but
explicitly denying access when the request comes from outside the specified IP range. The policy is useful
when the IP addresses for your company are within the specified ranges. To use this policy, replace the
red text in the example policy with your own information.
If this policy is used in combination with other policies that allow the ec2:TerminateInstances action
(such as the AmazonEC2FullAccess AWS managed policy), then access is denied. This is because an
explicit deny statement takes precedence over allow statements. For more information, see the section
called “Determining Whether a Request is Allowed or Denied” (p. 406).
Important
The aws:SourceIp condition key denies access to an AWS service, such as AWS CloudFormation,
that makes calls on your behalf. For more information about using the aws:SourceIp condition
key, see Available Global Condition Keys (p. 423).
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:TerminateInstances"
],
"Resource": [
"*"
]
},
{
"Effect": "Deny",
"Action": [
"ec2:TerminateInstances"
308
AWS Identity and Access Management User Guide
Example Policies
}
]
}
],
"Condition": {"NotIpAddress": {"aws:SourceIp": [
"192.0.2.0/24",
"203.0.113.0/24"
]}},
"Resource": [
"*"
]
AWS Elastic Beanstalk: Allows Access to a Specific Application,
Environment, and Version
This example shows how you might create a policy that allows access to a specific Elastic Beanstalk
application, environment, and version. To use this policy, replace the red text in the example policy with
your own information.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"autoscaling:Describe*",
"ec2:Describe*",
"s3:GetObject",
"iam:ListInstanceProfiles",
"cloudformation:GetTemplate"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"elasticbeanstalk:CheckDNSAvailability",
"elasticbeanstalk:CreateStorageLocation",
"elasticbeanstalk:RequestEnvironmentInfo",
"elasticbeanstalk:RetrieveEnvironmentInfo",
"elasticbeanstalk:Describe*",
"elasticbeanstalk:ValidateConfigurationSettings"
],
"Resource": [
"*"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication": [
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:application/<APPLICATION-ID>"
]
}
}
},
{
"Action": [
"elasticbeanstalk:ListAvailableSolutionStacks",
"elasticbeanstalk:CreateApplicationVersion",
"elasticbeanstalk:DeleteApplicationVersion",
"elasticbeanstalk:UpdateApplicationVersion",
309
AWS Identity and Access Management User Guide
Example Policies
"elasticbeanstalk:UpdateApplication",
"elasticbeanstalk:DescribeApplications",
"elasticbeanstalk:RestartAppServer",
"elasticbeanstalk:SwapEnvironmentCNAMEs",
"elasticbeanstalk:UpdateEnvironment",
"elasticbeanstalk:UpdateApplicationVersion"
ID>",
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:<REGION>::solutionstack/*",
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:application/<APPLICATION-
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:environment/<APPLICATIONID>/<ENVIRONMENT-ID>",
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:applicationversion/<APPLICATIONID>/<APPLICATION-VERSION>"
]
}
]
}
AWS Elastic Beanstalk: Allows Full Access to a Specific
Environment or Application
This example shows how you might create a policy that allows full access to a specific Elastic Beanstalk
environment or application. To use this policy, replace the red text in the example policy with your own
information.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"elasticbeanstalk:CheckDNSAvailability",
"elasticbeanstalk:CreateStorageLocation",
"elasticbeanstalk:Describe*",
"elasticbeanstalk:ApplyEnvironmentManagedAction",
"ec2:Describe*",
"autoscaling:Describe*",
"elasticloadbalancing:Describe*",
"cloudwatch:Describe*",
"cloudwatch:Get*",
"cloudwatch:List*",
"rds:Describe*"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"elasticbeanstalk:AbortEnvironmentUpdate",
"elasticbeanstalk:ComposeEnvironments",
"elasticbeanstalk:CreateApplication",
"elasticbeanstalk:DeleteApplication",
"elasticbeanstalk:UpdateApplication"
],
"Resource": [
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:application/<APPLICATION-ID>"
]
},
310
AWS Identity and Access Management User Guide
Example Policies
{
"Effect": "Allow",
"Action": [
"elasticbeanstalk:CreateApplicationVersion",
"elasticbeanstalk:DeleteApplicationVersion",
"elasticbeanstalk:UpdateApplicationVersion"
],
"Resource": [
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:applicationversion/*"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication": [
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:application/<APPLICATION-ID>"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"elasticbeanstalk:CreateConfigurationTemplate",
"elasticbeanstalk:DeleteConfigurationTemplate",
"elasticbeanstalk:UpdateConfigurationTemplate"
],
"Resource": [
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:configurationtemplate/*"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication": [
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:application/<APPLICATION-ID>"
],
"elasticbeanstalk:FromSolutionStack": [
"arn:aws:elasticbeanstalk:<REGION>::solutionstack/<STACK-ID>"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"elasticbeanstalk:ListAvailableSolutionStacks"
],
"Resource": [
"arn:aws:elasticbeanstalk:<REGION>::solutionstack/<STACK-ID>"
]
},
{
"Effect": "Allow",
"Action": [
"elasticbeanstalk:AbortEnvironmentUpdate",
"elasticbeanstalk:CreateEnvironment",
"elasticbeanstalk:DeleteEnvironmentConfiguration",
"elasticbeanstalk:RebuildEnvironment",
"elasticbeanstalk:RequestEnvironmentInfo",
"elasticbeanstalk:RestartAppServer",
"elasticbeanstalk:RetrieveEnvironmentInfo",
"elasticbeanstalk:SwapEnvironmentCNAMEs",
"elasticbeanstalk:TerminateEnvironment",
"elasticbeanstalk:UpdateEnvironment",
"elasticbeanstalk:ValidateConfigurationSettings"
],
"Resource": [
311
AWS Identity and Access Management User Guide
Example Policies
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:environment/<ENVIRONMENT-ID>"
],
"Condition": {
"StringEqualsIfExists": {
"elasticbeanstalk:InApplication": [
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:application/<APPLICATION-ID>"
],
"elasticbeanstalk:FromApplicationVersion": [
"arn:aws:elasticbeanstalk:<REGION>:<ACCOUNTNUMBER>:applicationversion/*"
]
}
}
}
]
}
IAM: Access the Policy Simulator API
This example shows how you might create a policy that allows using the policy simulator API for policies
attached to a user, group, or role in the current AWS account. This policy also allows access to simulate
less sensitive policies passed to the API as strings.
{
}
"Version" : "2012-10-17",
"Statement" : [
{
"Action" : [
"iam:GetContextKeysForCustomPolicy",
"iam:GetContextKeysForPrincipalPolicy",
"iam:SimulateCustomPolicy",
"iam:SimulatePrincipalPolicy"
],
"Effect" : "Allow",
"Resource" : "*"
}
]
Note
To allow a user to access the policy simulator console to simulate policies attached to
a user, group, or role in the current AWS account, see IAM: Access the Policy Simulator
Console (p. 312).
IAM: Access the Policy Simulator Console
This example shows how you might create a policy that allows using the policy simulator console for
policies attached to a user, group, or role in the current AWS account.
You can access the IAM Policy Simulator console at: https://policysim.www.amazonaws.cn/
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"iam:GetGroup",
"iam:GetGroupPolicy",
"iam:GetPolicy",
312
AWS Identity and Access Management User Guide
Example Policies
"iam:GetPolicyVersion",
"iam:GetRole",
"iam:GetRolePolicy",
"iam:GetUser",
"iam:GetUserPolicy",
"iam:ListAttachedGroupPolicies",
"iam:ListAttachedRolePolicies",
"iam:ListAttachedUserPolicies",
"iam:ListGroups",
"iam:ListGroupPolicies",
"iam:ListGroupsForUser",
"iam:ListRolePolicies",
"iam:ListRoles",
"iam:ListUserPolicies",
"iam:ListUsers"
}
]
}
],
"Effect": "Allow",
"Resource":"*"
IAM: Access the Policy Simulator API Based on User Path
This example shows how you might create a policy that allows using the policy simulator API only for
those users that have the path USER-PATH-NAME. To use this policy, replace the red text in the example
policy with your own information.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"iam:GetContextKeysForPrincipalPolicy",
"iam:SimulatePrincipalPolicy"
],
"Effect": "Allow",
"Resource":"arn:aws-cn:iam::<ACCOUNTNUMBER>:user/<USER-PATH-NAME>/*"
}
]
Note
To create a policy that allows using the policy simulator console for those users that have
the path USER-PATH-NAME, see IAM: Access the Policy Simulator Console Based on User
Path (p. 313).
IAM: Access the Policy Simulator Console Based on User Path
This example shows how you might create a policy that allows using the policy simulator console only
for those users that have the path USER-PATH-NAME. To use this policy, replace the red text in the example
policy with your own information.
You can access the IAM Policy Simulator at: https://policysim.www.amazonaws.cn/
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"iam:GetPolicy",
313
AWS Identity and Access Management User Guide
Example Policies
"iam:GetUserPolicy"
],
"Effect": "Allow",
"Resource": "*"
},
{
}
]
}
"Action": [
"iam:GetUser",
"iam:ListAttachedUserPolicies",
"iam:ListGroupsForUser",
"iam:ListUserPolicies",
"iam:ListUsers"
],
"Effect": "Allow",
"Resource": "arn:aws-cn:iam::<ACCOUNTNUMBER>:user/<USER-PATH-NAME>/*"
IAM: Allows IAM Users to Rotate Their Own Credentials
Programmatically and in the Console
This example shows how you might create a policy that allows IAM users to rotate their own access keys,
signing certificates, service specific credentials, and passwords. This policy also provides the permissions
necessary to complete this action on the console.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:ListUsers",
"iam:GetAccountPasswordPolicy"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iam:*AccessKey*",
"iam:ChangePassword",
"iam:GetUser",
"iam:*ServiceSpecificCredential*",
"iam:*SigningCertificate*"
],
"Resource": ["arn:aws:iam::*:user/${aws:username}"]
}
]
To learn how a user can change their own password in the console, see the section called “How IAM Users
Change Their Own Password” (p. 73).
IAM: Limits Managed Policies That Can Be Applied to a New IAM
User, Group, or Role
This example shows how you might create a policy that limits customer managed and AWS managed
policies that can be applied to a new IAM user, group, or role. To use this policy, replace the red text in
the example policy with your own information.
314
AWS Identity and Access Management User Guide
Example Policies
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:ChangePasword",
"iam:CreateAccessKey",
"iam:CreateLoginProfile",
"iam:CreateUser",
"iam:DeleteAccessKey",
"iam:DeleteLoginProfile",
"iam:DeleteUser",
"iam:UpdateAccessKey",
"iam:ListAttachedUserPolicies",
"iam:ListPolicies",
"iam:ListUserPolicies",
"iam:ListGroups",
"iam:ListGroupsForUser",
"iam:GetPolicy",
"iam:GetAccountSummary"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iam:AttachUserPolicy",
"iam:DetachUserPolicy"
],
"Resource": "*",
"Condition": {
"ArnEquals": {
"iam:PolicyArn": [
"arn:aws:iam::<ACCOUNTNUMBER>:policy/<MANAGED-POLICY-NAME>",
"arn:aws:iam::aws:policy/<AWS-MANAGED-POLICY-NAME>"
]
}
}
}
]
Amazon RDS: Allows Full RDS Database Access Within a Specific
Region
This example shows how you might create a policy that allows full RDS database access within a specific
region. To use this policy, replace the red text in the example policy with your own information.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "rds:*",
"Resource": [
"arn:aws:rds:<REGION>:<ACCOUNTNUMBER>:*"
]
},
{
"Effect": "Allow",
"Action": [
315
AWS Identity and Access Management User Guide
Example Policies
}
]
}
"rds:Describe*"
],
"Resource": [
"*"
]
Amazon RDS: Allows Restoring RDS Databases,
Programmatically and In the Console
This example shows how you might create a policy that allows restoring RDS databases. This policy also
provides the permissions necessary to complete this action on the console.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:Describe*",
"rds:CreateDBParameterGroup",
"rds:CreateDBSnapshot",
"rds:DeleteDBSnapshot",
"rds:Describe*",
"rds:DownloadDBLogFilePortion",
"rds:List*",
"rds:ModifyDBInstance",
"rds:ModifyDBParameterGroup",
"rds:ModifyOptionGroup",
"rds:RebootDBInstance",
"rds:RestoreDBInstanceFromDBSnapshot",
"rds:RestoreDBInstanceToPointInTime"
],
"Resource": "*"
}
]
Amazon RDS: Allows Tag Owners Full Access to RDS Resources
That They Have Tagged
This example shows how you might create a policy that allows tag owners full access to RDS resources
that they have tagged.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"rds:Describe*",
"rds:List*"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Action": [
"rds:DeleteDBInstance",
316
AWS Identity and Access Management User Guide
Example Policies
"rds:RebootDBInstance",
"rds:ModifyDBInstance"
},
{
},
{
},
{
},
{
},
{
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEqualsIgnoreCase": {
"rds:db-tag/Owner": "${aws:username}"
}
}
"Action": [
"rds:ModifyOptionGroup",
"rds:DeleteOptionGroup"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEqualsIgnoreCase": {
"rds:og-tag/Owner": "${aws:username}"
}
}
"Action": [
"rds:ModifyDBParameterGroup",
"rds:ResetDBParameterGroup"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEqualsIgnoreCase": {
"rds:pg-tag/Owner": "${aws:username}"
}
}
"Action": [
"rds:AuthorizeDBSecurityGroupIngress",
"rds:RevokeDBSecurityGroupIngress",
"rds:DeleteDBSecurityGroup"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEqualsIgnoreCase": {
"rds:secgrp-tag/Owner": "${aws:username}"
}
}
"Action": [
"rds:DeleteDBSnapshot",
"rds:RestoreDBInstanceFromDBSnapshot"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEqualsIgnoreCase": {
"rds:snapshot-tag/Owner": "${aws:username}"
}
}
"Action": [
317
AWS Identity and Access Management User Guide
Example Policies
"rds:ModifyDBSubnetGroup",
"rds:DeleteDBSubnetGroup"
},
{
}
]
}
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEqualsIgnoreCase": {
"rds:subgrp-tag/Owner": "${aws:username}"
}
}
"Action": [
"rds:ModifyEventSubscription",
"rds:AddSourceIdentifierToSubscription",
"rds:RemoveSourceIdentifierFromSubscription",
"rds:DeleteEventSubscription"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEqualsIgnoreCase": {
"rds:es-tag/Owner": "${aws:username}"
}
}
Amazon S3: Allows Amazon Cognito Users to Access Objects in
Their Bucket
This example shows how you might create a policy that allows Amazon Cognito users to access objects
in a specific S3 bucket. This policy allows access only to objects with a name that includes cognito,
the name of the application, and the federated user's ID. To use this policy, replace the red text in the
example policy with your own information.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": ["arn:aws-cn:s3:::<BUCKET-NAME>"],
"Condition": {"StringLike": {"s3:prefix": ["cognito/<APPLICATION-NAME>/"]}}
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": [
"arn:aws-cn:s3:::<BUCKET-NAME>/cognito/<APPLICATION-NAME>/${cognitoidentity.amazonaws.com:sub}",
"arn:aws-cn:s3:::<BUCKET-NAME>/cognito/<APPLICATION-NAME>/${cognitoidentity.amazonaws.com:sub}/*"
]
}
]
}
318
AWS Identity and Access Management User Guide
Example Policies
Amazon Cognito is an easy way to use web identity federation in your mobile app. Using Amazon
Cognito, you can provide access to AWS resources for users who have signed in to your app using a
third-party identity provider like Login with Amazon, Facebook, Google, or any Open-ID Connect (OIDC)
compatible identity provider instead of using an IAM user. To use Amazon Cognito for web identity
federation, you create a role that determines what permissions the federated user will have. You can
create one role for authenticated users. If your app allows unauthenticated (guest) users, you can create
a second role that defines the permissions for those users.
For more information about Amazon Cognito, see the following:
• Amazon Cognito Identity in the AWS Mobile SDK for Android Developer Guide
• Amazon Cognito Identity in the AWS Mobile SDK for iOS Developer Guide
Amazon S3: Allows IAM Users Access to Their S3 Home
Directory, Programmatically and In the Console
This example shows how you might create a policy that allows IAM users to access their own home
directory in S3. The home directory is a bucket that includes a home folder and folders for individual
users. This policy also provides the permissions necessary to complete this action on the console. To use
this policy, replace the red text in the example policy with your own information.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets",
"s3:GetBucketLocation"
],
"Resource": "arn:aws:s3:::*"
},
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::<BUCKET-NAME>",
"Condition": {"StringLike": {"s3:prefix": [
"",
"home/",
"home/${aws:username}/*"
]}}
},
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": [
"arn:aws:s3:::<BUCKET-NAME>/home/${aws:username}",
"arn:aws:s3:::<BUCKET-NAME>/home/${aws:username}/*"
]
}
]
Amazon S3: Limits Managing to a Specific S3 Bucket
This example shows how you might create a policy that limits managing an S3 bucket by allowing
all S3 actions on the specific bucket, but explicitly denying access to every AWS service except
Amazon S3. This policy also denies access to actions that can't be performed on an S3 bucket, such as
319
AWS Identity and Access Management User Guide
Example Policies
s3:ListAllMyBuckets or s3:GetObject. To use this policy, replace the red text in the example policy with
your own information.
If this policy is used in combination with other policies (such as the AmazonS3FullAccess or
AmazonEC2FullAccess AWS managed policies) that allow actions denied by this policy, then access is
denied. This is because an explicit deny statement takes precedence over allow statements. For more
information, see the section called “Determining Whether a Request is Allowed or Denied” (p. 406).
Warning
NotAction (p. 382) and NotResource (p. 384) are advanced policy elements that must be
used with care. This policy denies access to every AWS service except Amazon S3. If you attach
this policy to a user, any other policies that grant permissions to other services are ignored and
access is denied.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": [
"arn:aws-cn:s3:::<BUCKET-NAME>",
"arn:aws-cn:s3:::<BUCKET-NAME>/*"
]
},
{
"Effect": "Deny",
"NotAction": "s3:*",
"NotResource": [
"arn:aws-cn:s3:::<BUCKET-NAME>",
"arn:aws-cn:s3:::<BUCKET-NAME>/*"
]
}
]
}
Amazon S3: Allows Read and Write Access to a Specific S3
Bucket
This example shows how you might create a policy that allows Read and Write access to a specific S3
bucket. To use this policy, replace the red text in the example policy with your own information.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": ["arn:aws:s3:::<BUCKET-NAME>"]
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject"
],
"Resource": ["arn:aws:s3:::<BUCKET-NAME>/*"]
}
]
320
AWS Identity and Access Management User Guide
Additional Resources
Note
To allow Read and Write access to a specific Amazon S3 bucket and also include additional
permissions for console access, see Amazon S3: Allows Read and Write Access to a Specific S3
Bucket, Programmatically and in the Console (p. 321).
Amazon S3: Allows Read and Write Access to a Specific S3
Bucket, Programmatically and in the Console
This example shows how you might create a policy that allows Read and Write access to a specific S3
bucket. This policy also provides the permissions necessary to complete this action on the console. To use
this policy, replace the red text in the example policy with your own information.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetBucketLocation",
"s3:ListAllMyBuckets"
],
"Resource": "arn:aws:s3:::*"
},
{
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": ["arn:aws:s3:::<BUCKET-NAME>"]
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject"
],
"Resource": ["arn:aws:s3:::<BUCKET-NAME>/*"]
}
]
Resources for Learning About Permissions and
Policies
For more information about permissions and about creating policies, see the following resources:
• Overview of IAM Policies (p. 232) – This section discusses types of permissions, how to grant them,
and how to manage permissions.
• Working with Policies (p. 250) – This section discusses how to specify what actions are allowed, which
resources to allow the actions on, and what the effect will be when the user requests access to the
resources.
• The following entries in the AWS Security Blog cover common ways to write policies for access to
Amazon S3 buckets and objects.
• Writing IAM Policies: How to Grant Access to an Amazon S3 Bucket
• Writing IAM policies: Grant Access to User-Specific Folders in an Amazon S3 Bucket
• IAM Policies and Bucket Policies and ACLs! Oh My! (Controlling Access to S3 Resources)
321
AWS Identity and Access Management User Guide
Additional Resources
• A Primer on RDS Resource-Level Permissions
• Demystifying EC2 Resource-Level Permissions
• Testing IAM Policies with the IAM Policy Simulator (p. 283) – This tool lets you test the effects of IAM
policies to determine whether they will allow or deny access to actions in AWS services.
• Example Policies for Administering IAM Resources (p. 227) – This section contains example policies
that show how to perform tasks specific to IAM, like administer users, groups, and credentials.
322
AWS Identity and Access Management User Guide
Types of IAM Information Logged in CloudTrail
Logging IAM Events with AWS
CloudTrail
AWS Identity and Access Management (IAM) is integrated with AWS CloudTrail, a service that logs AWS
events made by or on behalf of your AWS account. CloudTrail logs authenticated AWS API calls and also
AWS sign-in events, and collects this event information in files that are delivered to Amazon S3 buckets.
Using information collected by CloudTrail, you can determine what requests were successfully made to
AWS services, who made the request, when it was made, and so on.
To learn more about CloudTrail, including how to configure and enable it, see the AWS CloudTrail User
Guide.
Topics
• Types of IAM Information Logged in CloudTrail (p. 323)
• Examples of Logged Events in CloudTrail Files (p. 326)
• Preventing Duplicate Log Entries in CloudTrail (p. 332)
Types of IAM Information Logged in CloudTrail
IAM information is available to CloudTrail in these ways:
• API requests to IAM and AWS Security Token Service (AWS STS) – CloudTrail logs all
authenticated API requests (made with credentials) to IAM and AWS STS APIs, with the exception of
DecodeAuthorizationMessage. CloudTrail also logs nonauthenticated requests to the AWS STS actions,
AssumeRoleWithSAML and AssumeRoleWithWebIdentity and logs information provided by the identity
provider. You can use this information to map calls made by a federated user with an assumed role
back to the originating external federated caller. In the case of AssumeRole, you can map calls back to
the originating AWS service or to the account of the originating user. The userIdentity section of the
JSON data in the CloudTrail log entry contains the information that you need to map the AssumeRole*
request with a specific federated user. For more information, see CloudTrail userIdentity Element in the
AWS CloudTrail User Guide.
For example, calls to the IAM CreateUser, DeleteRole, ListGroups, and other API operations are all
logged by CloudTrail.
Examples for this type of log entry are presented later in this topic.
323
AWS Identity and Access Management User Guide
Types of IAM Information Logged in CloudTrail
Important
If you activate AWS STS endpoints in regions other than the default global endpoint, then you
must also turn on CloudTrail logging in those regions to record any AWS STS API calls made
in those regions. For more information, see Turning On CloudTrail in Additional Regions in the
AWS CloudTrail User Guide.
• API requests to other AWS services – Authenticated requests to other AWS service APIs are logged by
CloudTrail, and these log entries contain information about who generated the request.
For example, if a request is made to list Amazon EC2 instances or create an AWS CodeDeploy
deployment group, the user identity of the person or service that made the request is contained in the
log entry for that request. The user identity information helps you determine whether the request was
made with IAM user credentials, with temporary security credentials for a role or federated user, or by
another AWS service.
For more details about the user identity information in CloudTrail log entries, see userIdentity Element
in the AWS CloudTrail User Guide.
• AWS sign-in events – Sign-in events to the AWS Management Console, the AWS Discussion Forums,
and the AWS Marketplace are logged by CloudTrail.
For example, IAM and federated user sign-in events—successful sign-ins and failed sign-in attempts—
are logged by CloudTrail.
If you enable CloudTrail to log sign-in events to your logs, you need to be aware of how CloudTrail
chooses where to log the events.
• If your users sign in directly to a console, they are redirected to either a global or a regional sign-in
endpoint, based on whether the selected service console supports regions. For example, the main
console home page supports regions, so if you sign in to the following URL:
https://alias.signin.aws.amazon.com/console
you are redirected to a regional sign-in endpoint such as https://uswest-2.signin.aws.amazon.com, resulting in a regional CloudTrail log entry in the user's region's log:
On the other hand, the Amazon S3 console does not support regions, so if you sign in to the
following URL
https://alias.signin.aws.amazon.com/console/s3
AWS redirects you to the global sign-in endpoint at https://signin.aws.amazon.com, resulting in a
global CloudTrail log entry.
• You can manually request a certain regional sign-in endpoint by signing in to the region-enabled
main console home page using a URL syntax like the following:
https://alias.signin.aws.amazon.com/console?region=ap-southeast-1
AWS redirects you to the ap-southeast-1 regional sign-in endpoint and results in a regional
CloudTrail log event.
Important
As a security best practice, AWS does not log the entered user name text when the signin failure is caused by an incorrect user name. The user name text is masked by the value
HIDDEN_DUE_TO_SECURITY_REASONS. For an example of this, see Sign-in Failure Event Caused
by Incorrect User Name (p. 331), later in this topic. The reason the user name is obscured is
because such failures might be caused by user errors like the following, which, if logged, could
expose potentially sensitive information:
324
AWS Identity and Access Management User Guide
Types of IAM Information Logged in CloudTrail
• You accidentally type your password in the user name field.
• You click the link for one AWS account's sign-in page, but then type the account number for
a different one.
• You forget which account you are signing in to and accidentally type the account name of
your personal email account, your bank sign-in identifier, or some other private ID.
Whether the sign-in event is considered to a regional event or a global one depends on the console the
user is signing into, and how the user constructs the sign-in URL.
• Is the service console regionalized? If so, then the sign-in request is automatically redirected to a
regional sign-in endpoint and the event is logged in that region's CloudTrail log. For example, if
you sign in to https://alias.signin.aws.amazon.com/console the console home page which is
regionalized, you are automatically redirected you to a sign-in endpoint in your region (for example,
https://us-west-2.signin.aws.amazon.com), and the event is logged in that region's log.
However, some services are not regionalized yet. For example, the Amazon S3 service is not currently
regionalized, so if you sign in to https://alias.signin.aws.amazon.com/console/s3, you are
redirected to the global sign-in endpoint at https://signin.aws.amazon.com, resulting in an event
in your global log.
• You can also manually request a certain regional sign-in endpoint by using a URL syntax like
https://alias.signin.aws.amazon.com/console?region=ap-southeast-1, which redirects to the
ap-southeast-1 regional sign-in endpoint and results in an event in the regional log.
• How temporary credential requests are logged – When a principal requests temporary credentials,
the principal type determines how CloudTrail logs the event. The following table shows how CloudTrail
logs different information for each of the API calls that generate temporary credentials.
Principal Type
IAM/STS API
User Identity
in CloudTrail
Log for Calling
Account
User Identity in
CloudTrail Log
for Role Owning
Account
IAM user
GetSessionToken
IAM user identity
Role owner
IAM user identity
account is same as
calling account
IAM user
GetFederationToken IAM user identity
Role owner
IAM user identity
account is same as
calling account
IAM user
AssumeRole
Account number
and Principal ID
(if a user), or AWS
service principal
Role identity only
(no user)
Externally
authenticated
user
AssumeRoleWithSAML
n/a
SAML user
identity
Role identity only
(no user)
Externally
authenticated
user
AssumeRoleWithWebIdentity
n/a
OIDC/Web user
identity
Role identity only
(no user)
IAM user identity
325
User Identity in
CloudTrail Log
for Role Owner
for Subsequent
API calls
AWS Identity and Access Management User Guide
Examples of Logged Events in CloudTrail Files
Examples of Logged Events in CloudTrail Files
CloudTrail log files contain events that are formatted using JSON. An event represents a single API
request or sign-in event and includes information about the requested action, any parameters, and the
date and time of the action.
IAM API Event in CloudTrail Log File
The following example shows a CloudTrail log entry for a request made for the IAM GetUserPolicy
action.
{
}
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws-cn:iam::444455556666:user/Alice",
"accountId": "444455556666",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "Alice",
"sessionContext": {
"attributes": {
"creationDate": "2014-07-15T21:39:40Z"
}
},
"invokedBy": "signin.amazonaws.com"
},
"eventTime": "2014-07-15T21:40:14Z",
"eventSource": "iam.amazonaws.com",
"eventName": "GetUserPolicy",
"awsRegion": "us-west-2",
"sourceIPAddress": "signin.amazonaws.com",
"userAgent": "signin.amazonaws.com",
"requestParameters": {
"userName": "Alice",
"policyName": "ReadOnlyAccess-Alice-201407151307"
},
"responseElements": null,
"requestID": "9EXAMPLE-0c68-11e4-a24e-d5e16EXAMPLE",
"eventID": "cEXAMPLE-127e-4632-980d-505a4EXAMPLE"
From this event information, you can determine that the request was made to get a user policy named
ReadOnlyAccess-Alice-201407151307 for user Alice, as specified in the requestParameters element.
You can also see that the request was made by an IAM user named Alice on July 15, 2014 at 9:40 PM
(UTC). In this case, the request originated in the AWS Management Console, as you can tell from the
userAgent element.
AWS STS API Event in CloudTrail Log File
The IAM user named "Bob" in account 777788889999 calls the AWS STS AssumeRole action to assume
the role EC2-dev in account 111122223333. The next two examples show the CloudTrail log entries for
the two affected accounts. The first example shows the CloudTrail log entry for the request made in
account 777788889999, the account that owns the user who calls AssumeRole.
{
"eventVersion": "1.05",
"userIdentity": {
326
AWS Identity and Access Management User Guide
AWS STS API Event in CloudTrail Log File
"type": "IAMUser",
"principalId": "AIDAQRSTUVWXYZEXAMPLE",
"arn": "arn:aws-cn:iam::777788889999:user/Bob",
"accountId": "777788889999",
"accessKeyId": "AKIAQRSTUVWXYZEXAMPLE",
"userName": "Bob"
},
"eventTime": "2014-07-18T15:07:39Z",
"eventSource": "sts.amazonaws.com",
"eventName": "AssumeRole",
"awsRegion": "us-west-2",
"sourceIPAddress": "192.0.2.101",
"userAgent": "aws-cli/1.11.10 Python/2.7.8 Linux/3.2.45-0.6.wd.865.49.315.metal1.x86_64
botocore/1.4.67",
"requestParameters": {
"roleArn": "arn:aws-cn:iam::777788889999:role/EC2-dev",
"roleSessionName": "Bob-EC2-dev"
},
"responseElements": {
"credentials": {
"sessionToken": "<encoded session token blob>",
"accessKeyId": "AKIAQRSTUVWXYZEXAMPLE",
"expiration": "Jul 18, 2014 4:07:39 PM"
},
"assumedRoleUser": {
"assumedRoleId": "AIDAQRSTUVWXYZEXAMPLE:Bob-EC2-dev",
"arn": "arn:aws-cn:sts::777788889999:assumed-role/EC2-dev/Bob-EC2-dev"
}
},
"resources": [
{
"ARN": "arn:aws:iam::111122223333:role/EC2-dev",
"accountId": "111122223333",
"type": "AWS::IAM::Role"
}
],
"requestID": "4EXAMPLE-0e8d-11e4-96e4-e55c0EXAMPLE",
"sharedEventID": "bEXAMPLE-efea-4a70-b951-19a88EXAMPLE",
"eventID": "dEXAMPLE-ac7f-466c-a608-4ac8dEXAMPLE"
"eventType": "AwsApiCall",
"recipientAccountId": "111122223333"
}
The second example shows the role owning account's (111122223333) CloudTrail log entry for the same
request.
{
"eventVersion": "1.05",
"userIdentity": {
"type": "AWSAccount",
"principalId": "AIDAQRSTUVWXYZEXAMPLE",
"accountId": "777788889999"
},
"eventTime": "2014-07-18T15:07:39Z",
"eventSource": "sts.amazonaws.com",
"eventName": "AssumeRole",
"awsRegion": "us-west-2",
"sourceIPAddress": "192.0.2.101",
"userAgent": "aws-cli/1.11.10 Python/2.7.8 Linux/3.2.45-0.6.wd.865.49.315.metal1.x86_64
botocore/1.4.67",
"requestParameters": {
"roleArn": "arn:aws:iam:: 111122223333:role/EC2-dev",
"roleSessionName": "Bob-EC2-dev",
},
327
AWS Identity and Access Management User Guide
AWS STS API Event in CloudTrail Log File
}
"responseElements": {
"credentials": {
"sessionToken": "<encoded session token blob>",
"accessKeyId": "AKIAQRSTUVWXYZEXAMPLE",
"expiration": "Jul 18, 2014 4:07:39 PM"
},
"assumedRoleUser": {
"assumedRoleId": "AIDAQRSTUVWXYZEXAMPLE:Bob-EC2-dev",
"arn": "arn:aws:sts::777788889999:assumed-role/EC2-dev/Bob-EC2-dev"
}
},
"requestID": "4EXAMPLE-0e8d-11e4-96e4-e55c0EXAMPLE",
"sharedEventID": "bEXAMPLE-efea-4a70-b951-19a88EXAMPLE",
"eventID": "dEXAMPLE-ac7f-466c-a608-4ac8dEXAMPLE"
The following example shows a CloudTrail log entry for a request made by an AWS service calling an API
using permissions from an IAM role.
{
"eventVersion": "1.04",
"userIdentity": {
"type": "AssumedRole",
"principalId": "AIDAQRSTUVWXYZEXAMPLE:devdsk",
"arn": "arn:aws:sts::777788889999:assumed-role/AssumeNothing/devdsk",
"accountId": "777788889999",
"accessKeyId": "AKIAQRSTUVWXYZEXAMPLE",
"sessionContext": {
"attributes": {
"creationDate": "2016-11-14T17:25:26Z"
},
"sessionIssuer": {
"type": "Role",
"principalId": "AIDAQRSTUVWXYZEXAMPLE",
"arn": "arn:aws:iam::777788889999:role/AssumeNothing",
"accountId": "777788889999",
"userName": "AssumeNothing"
}
}
},
"eventTime": "2016-11-14T17:25:45Z",
"eventSource": "s3.amazonaws.com",
"eventName": "DeleteBucket",
"awsRegion": "us-west-2",
"sourceIPAddress": "192.0.2.1",
"userAgent": "[aws-cli/1.11.10 Python/2.7.8 Linux/3.2.45-0.6.wd.865.49.315.metal1.x86_64
botocore/1.4.67]",
"requestParameters": {
"bucketName": "my-test-bucket-cross-account"
},
"responseElements": null,
"requestID": "EXAMPLE463D56D4C",
"eventID": "dEXAMPLE-265a-41e0-9352-4401bEXAMPLE",
"eventType": "AwsApiCall",
"recipientAccountId": "777788889999"
}
The following example shows a CloudTrail log entry for a request made for the AWS STS
AssumeRoleWithSAML action.
{
"eventVersion": "1.05",
"userIdentity": {
328
AWS Identity and Access Management User Guide
AWS STS API Event in CloudTrail Log File
"type": "SAMLUser",
"principalId": "<id of identity provider>:<canonical id of user>",
"userName": "<canonical id of user>",
"identityProvider": "<id of identity provider>"
},
"eventTime": "2016-03-23T01:39:57Z",
"eventSource": "sts.amazonaws.com",
"eventName": "AssumeRoleWithSAML",
"awsRegion": "us-west-2",
"sourceIPAddress": "192.0.2.101",
"userAgent": "aws-cli/1.3.23 Python/2.7.6 Linux/2.6.18-164.el5",
"requestParameters": {
"sAMLAssertionID": "_c0046cEXAMPLEb9d4b8eEXAMPLE2619aEXAMPLE",
"roleSessionName": "MyAssignedRoleSessionName",
"durationSeconds": 3600,
"roleArn": "arn:aws-cn:iam::444455556666:role/SAMLTestRoleShibboleth",
"principalArn": "arn:aws-cn:iam::444455556666:saml-provider/Shibboleth"
},
"responseElements": {
"subjectType": "transient",
"issuer": "https://server.example.com/idp/shibboleth",
"credentials": {
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"expiration": "Mar 23, 2016 2:39:57 AM",
"sessionToken": "<encoded session token blob>"
},
"nameQualifier": "<id of identity provider>",
"assumedRoleUser": {
"assumedRoleId": "AROAD35QRSTUVWEXAMPLE:MyAssignedRoleSessionName",
"arn": "arn:aws-cn:sts::444455556666:assumed-role/SAMLTestRoleShibboleth/
MyAssignedRoleSessionName"
},
"subject": "<canonical id of user>",
"audience": "https://signin.aws.amazon.com/saml"
},
"resources": [
{
"ARN": "arn:aws:iam::444455556666:role/SAMLTestRoleShibboleth",
"accountId": "444455556666",
"type": "AWS::IAM::Role"
},
{
"ARN": "arn:aws:iam::444455556666:saml-provider/test-saml-provider",
"accountId": "444455556666",
"type": "AWS::IAM::SAMLProvider"
}
],
"requestID": "6EXAMPLE-e595-11e5-b2c7-c974fEXAMPLE",
"eventID": "dEXAMPLE-265a-41e0-9352-4401bEXAMPLE",
"eventType": "AwsApiCall",
"recipientAccountId": "444455556666"
}
The following example shows a CloudTrail log entry for a request made for the AWS STS
AssumeRoleWithWebIdentity action.
{
"eventVersion": "1.05",
"userIdentity": {
"type": "WebIdentityUser",
"principalId": "accounts.google.com:<id-of-application>.apps.googleusercontent.com:<idof-user>",
"userName": "<id of user>",
"identityProvider": "accounts.google.com"
329
AWS Identity and Access Management User Guide
Sign-in Failure Event in CloudTrail Log File
},
"eventTime": "2016-03-23T01:39:51Z",
"eventSource": "sts.amazonaws.com",
"eventName": "AssumeRoleWithWebIdentity",
"awsRegion": "us-west-2",
"sourceIPAddress": "192.0.2.101",
"userAgent": "aws-cli/1.3.23 Python/2.7.6 Linux/2.6.18-164.el5",
"requestParameters": {
"durationSeconds": 3600,
"roleArn": "arn:aws-cn:iam::444455556666:role/FederatedWebIdentityRole",
"roleSessionName": "MyAssignedRoleSessionName"
},
"responseElements": {
"provider": "accounts.google.com",
"subjectFromWebIdentityToken": "<id of user>",
"audience": "<id of application>.apps.googleusercontent.com",
"credentials": {
"accessKeyId": "ASIACQRSTUVWRAOEXAMPLE",
"expiration": "Mar 23, 2016 2:39:51 AM",
"sessionToken": "<encoded session token blob>"
},
"assumedRoleUser": {
"assumedRoleId": "AROACQRSTUVWRAOEXAMPLE:MyAssignedRoleSessionName",
"arn": "arn:aws-cn:sts::444455556666:assumed-role/FederatedWebIdentityRole/
MyAssignedRoleSessionName"
}
},
"resources": [
{
"ARN": "arn:aws:iam::444455556666:role/FederatedWebIdentityRole",
"accountId": "444455556666",
"type": "AWS::IAM::Role"
}
],
"requestID": "6EXAMPLE-e595-11e5-b2c7-c974fEXAMPLE",
"eventID": "bEXAMPLE-0b30-4246-b28c-e3da3EXAMPLE",
"eventType": "AwsApiCall",
"recipientAccountId": "444455556666"
}
Sign-in Failure Event in CloudTrail Log File
The following example shows a CloudTrail log entry for a failed sign-in event.
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn":"arn:aws-cn:iam::111122223333:user/Alice",
"accountId": "111122223333",
"userName": "Alice"
},
"eventTime": "2014-07-08T17:35:27Z",
"eventSource": "signin.amazonaws.com",
"eventName": "ConsoleLogin",
"awsRegion": "us-west-2",
"sourceIPAddress": "192.0.2.100",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:24.0) Gecko/20100101 Firefox/24.0",
"errorMessage": "Failed authentication",
"requestParameters": null,
"responseElements": {
"ConsoleLogin": "Failure"
330
AWS Identity and Access Management User Guide
Sign-in Failure Event Caused by Incorrect User Name
}
},
"additionalEventData": {
"MobileVersion": "No",
"LoginTo": "https://console.aws.amazon.com/sns"
},
"eventID": "11ea990b-4678-4bcd-8fbe-62509088b7cf"
From this information, you can determine that the sign-in attempt was made by an IAM user named
Alice, as shown in the userIdentity element. You can also see that the sign-in attempt failed, as shown
in the responseElements element. You can see that Alice tried to sign in to the Amazon SNS console at
5:35 PM (UTC) on July 8th, 2014.
Sign-in Failure Event Caused by Incorrect User Name
The following example shows a CloudTrail log entry for an unsuccessful sign-in event caused by the user
entering an incorrect user name. AWS masks the userName text with HIDDEN_DUE_TO_SECURITY_REASONS
to help prevent exposing potentially sensitive information.
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"accountId": "123456789012",
"accessKeyId": "",
"userName": "HIDDEN_DUE_TO_SECURITY_REASONS"
},
"eventTime": "2015-03-31T22:20:42Z",
"eventSource": "signin.amazonaws.com",
"eventName": "ConsoleLogin",
"awsRegion": "us-west-2",
"sourceIPAddress": "192.0.2.101",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:24.0) Gecko/20100101 Firefox/24.0",
"errorMessage": "No username found in supplied account",
"requestParameters": null,
"responseElements": {
"ConsoleLogin": "Failure"
},
"additionalEventData": {
"LoginTo": "https://console.aws.amazon.com/console/home?state=hashArgs
%23&isauthcode=true",
"MobileVersion": "No"
},
"eventID": "a7654656-0417-45c6-9386-ea8231385051",
"eventType": "AwsConsoleSignin",
"recipientAccountId": "123456789012"
}
Sign-in Success Event in CloudTrail Log File
The following example shows a CloudTrail log entry for a successful sign-in event.
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIDACKCEVSQ6C2EXAMPLE",
"arn":"arn:aws-cn:iam::111122223333:user/Bob",
"accountId": "111122223333",
"userName": "Bob"
331
AWS Identity and Access Management User Guide
Preventing Duplicate Log Entries in CloudTrail
}
},
"eventTime": "2014-07-16T15:49:27Z",
"eventSource": "signin.amazonaws.com",
"eventName": "ConsoleLogin",
"awsRegion": "us-west-2",
"sourceIPAddress": "192.0.2.110",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:24.0) Gecko/20100101 Firefox/24.0",
"requestParameters": null,
"responseElements": {
"ConsoleLogin": "Success"
},
"additionalEventData": {
"MobileVersion": "No",
"LoginTo": "https://console.aws.amazon.com/s3"
},
"eventID": "3fcfb182-98f8-4744-bd45-10a395ab61cb"
For more details about the information contained in CloudTrail log files, see CloudTrail Event Reference
in the AWS CloudTrail User Guide.
Preventing Duplicate Log Entries in CloudTrail
CloudTrail creates trails in each region separately. These trails include information for events that occur
in those regions, plus global (that is, non-region-specific) events such as IAM API calls, non-region
specific AWS STS calls (calls to sts.amazonaws.com), and AWS sign-in events. For example, by default, if
you have two trails, each in a different region, and you then create a new IAM user, the CreateUser event
is added to the log files in both regions, creating a duplicate log entry.
Note
By default, AWS Security Token Service (STS) is a global service with a single endpoint at
https://sts.amazonaws.com. Calls to this endpoint are logged as calls to a global service.
However, because this endpoint is physically located in the US East (N. Virginia) region, your logs
list "us-east-1" as the event region. CloudTrail does not write these logs to the region unless
you choose to include global service logs in that region. CloudTrail writes calls to all regional
endpoints to their respective regions. For example, calls to sts.us-west-2.amazonaws.com are
published to the region, calls to sts.eu-central-1.amazonaws.com are published to the EU
(Frankfurt) region, etc.
For more information about multiple regions and AWS STS see Activating and Deactivating AWS
STS in an AWS Region (p. 218).
The following table lists the regions and how CloudTrail logs AWS STS requests in each region. The
"Location" column indicates which logs CloudTrail writes to. "Global" means the event is logged in any
region for which you choose to include global service logs in that region. "Region" means that the event
is logged only in the region where the endpoint is located. The last column indicates how the request's
region is identified in the log entry.
Region name
Region
identity in
CloudTrail log
Endpoint
Location of
CloudTrail logs
n/a - global
us-east-1
sts.amazonaws.com
global
us-west-2
sts.us-east-2.amazonaws.com
region
US East (N. Virginia)
us-east-1
sts.us-east-1.amazonaws.com
region
US West (N. California)
us-west-1
sts.us-west-1.amazonaws.com
region
332
AWS Identity and Access Management User Guide
Preventing Duplicate Log Entries in CloudTrail
Region name
Region
identity in
CloudTrail log
Endpoint
Location of
CloudTrail logs
US West (Oregon)
us-west-2
sts.us-west-2.amazonaws.com
region
Canada (Central)
ca-central-1
sts.ca-central-1.amazonaws.com
region
EU (Frankfurt)
eu-central-1
sts.eu-central-1.amazonaws.com
region
EU (Ireland)
eu-west-1
sts.eu-west-1.amazonaws.com
region
EU (London)
eu-west-2
sts.eu-west-2.amazonaws.com
region
Asia Pacific (Tokyo)
ap-northeast-1
sts.apnortheast-1.amazonaws.com
region
Asia Pacific (Seoul)
ap-northeast-2
sts.apnortheast-2.amazonaws.com
region
ap-south-1
sts.ap-south-1.amazonaws.com
region
Asia Pacific (Singapore)
ap-southeast-1
sts.apsoutheast-1.amazonaws.com
region
Asia Pacific (Sydney)
ap-southeast-2
sts.apsoutheast-2.amazonaws.com
region
South America (São
Paulo)
sa-east-1
sts.sa-east-1.amazonaws.com
region
Asia Pacific (Mumbai)
When you configure CloudTrail to aggregate trail information from multiple regions in your account
into a single Amazon S3 bucket, IAM events are duplicated in the logs—the trail for each region writes
the same IAM event to the aggregated log. To prevent this duplication, you can include global events
selectively. A typical approach is to enable global events in one trail and to disable global events in all
other trails that write to the same Amazon S3 bucket. That way only one set of global events is written.
For more information, see Aggregating Logs in the AWS CloudTrail User Guide.
333
AWS Identity and Access Management User Guide
Troubleshooting General Issues
Troubleshooting IAM
If you encounter access-denied issues or similar difficulties when working with AWS Identity and Access
Management (IAM), consult the topics in this section.
Topics
• Troubleshooting General Issues (p. 334)
• Troubleshoot IAM Policies (p. 336)
• Troubleshooting IAM Roles (p. 346)
• Troubleshooting Amazon EC2 and IAM (p. 348)
• Troubleshooting Amazon S3 and IAM (p. 351)
• Troubleshooting SAML 2.0 Federation with AWS (p. 351)
Troubleshooting General Issues
Use the information here to help you diagnose and fix access-denied or other common issues that you
might encounter when working with AWS Identity and Access Management (IAM).
Topics
• I lost my access keys. (p. 334)
• I get "access denied" when I make a request to an AWS service. (p. 335)
• I get "access denied" when I make a request with temporary security credentials. (p. 335)
• Policy variables aren't working. (p. 335)
• Changes that I make are not always immediately visible (p. 336)
I lost my access keys.
Access keys consist of two parts:
• The access key identifier. This is not a secret, and can be seen in the IAM console wherever access keys
are listed, such as on the user summary page.
• The secret access key. This is provided when you initially create the access key pair. Just like a
password, it cannot be retrieved later. If you cannot find your secret access key then you must delete
the access key pair and recreate it.
For more information, see Retrieving Your Lost or Forgotten Passwords or Access Keys (p. 79).
334
AWS Identity and Access Management User Guide
I get "access denied" when I make
a request to an AWS service.
I get "access denied" when I make a request to an
AWS service.
Verify that you have permission to call the action and resource that you have requested. If any conditions
are set, you must also meet those conditions when you send the request. For information about viewing
or modifying policies for an IAM user, group, or role, see Working with Policies (p. 250).
If you're trying to access a service that has resource-based (or access control) policies, such as Amazon
S3, Amazon SNS, or Amazon SQS, verify that the resource policy specifies you as a principal and grants
you access. For more information about resource-based policies, see the documentation for that service.
If you are signing requests manually (without using the AWS SDKs), verify that you have correctly signed
the request.
I get "access denied" when I make a request with
temporary security credentials.
• Verify that the service accepts temporary security credentials, see Using Temporary Security
Credentials to Access AWS.
• Verify that your requests are being signed correctly and that the request is well-formed. For details,
see your toolkit documentation or Using Temporary Security Credentials to Authenticate an AWS
Request.
• Verify that your temporary security credentials haven't expired. For more information, see Using
Temporary Security Credentials.
• Verify that the IAM user or role has the correct permissions. Permissions for temporary security
credentials are derived from an IAM user or role, so the permissions are limited to those granted to the
IAM user or role. For more information about how permissions for temporary security credentials are
determined, see Controlling Permissions for Temporary Security Credentials (p. 207).
• If you are accessing a resource that has a resource-based policy by using a role, verify that the
policy grants permissions to the role. For example, the following policy allows MyRole from account
111122223333 to access MyBucket.
{
}
"Version": "2012-10-17",
"Statement": [{
"Sid": "S3BucketPolicy",
"Effect": "Allow",
"Principal": {"AWS": ["arn:aws-cn:iam::111122223333:role/MyRole"]},
"Action": ["s3:PutObject"],
"Resource": ["arn:aws-cn:s3:::MyBucket/*"]
}]
Policy variables aren't working.
• Verify that all policies that include variables include the following version number in the policy:
"Version": "2012-10-17"Without the correct version number, the variables are not replaced during
evaluation. Instead, the variables are evaluated literally. Any policies that don't include variables will
still work if you include the latest version number.
A Version policy element is different from a policy version. The Version policy element is used within
a policy and defines the version of the policy language. A policy version, on the other hand, is created
335
AWS Identity and Access Management User Guide
Changes that I make are not always immediately visible
when you make changes to a customer managed policy in IAM. The changed policy doesn't overwrite
the existing policy. Instead, IAM creates a new version of the managed policy. To learn more about the
Version policy element see the section called “Version” (p. 375). To learn more about policy versions,
see the section called “Versioning for Managed Policies” (p. 240).
• Verify that your policy variables are in the right case. For details, see IAM Policy Variables
Overview (p. 395).
Changes that I make are not always immediately
visible
As a service that is accessed through computers in data centers around the world, IAM uses a distributed
computing model called eventual consistency. Any change that you make in IAM (or other AWS services)
takes time to become visible from all possible endpoints. Some of the delay results from the time it takes
to send the data from server to server, from replication zone to replication zone, and from region to
region around the world. IAM also uses caching to improve performance, but in some cases this can add
time; the change might not be visible until the previously cached data times out.
You must design your global applications to account for these potential delays and ensure that they
work as expected, even when a change made in one location is not instantly visible at another. Such
changes include creating or updating users, groups, roles, or policies. We recommend that you do not
include such IAM changes in the critical, high-availability code paths of your application. Instead, make
IAM changes in a separate initialization or setup routine that you run less frequently. Also, be sure to
verify that the changes have been propagated before production workflows depend on them.
For more information about how some other AWS services are affected by this, consult the following
resources:
• Amazon DynamoDB: What is the consistency model of Amazon DynamoDB? in the DynamoDB FAQ,
and Read Consistency in the Amazon DynamoDB Developer Guide.
• Amazon EC2: EC2 Eventual Consistency in the Amazon EC2 API Reference.
• Amazon EMR: Ensuring Consistency When Using Amazon S3 and Amazon Elastic MapReduce for ETL
Workflows in the AWS Big Data Blog
• Amazon Redshift: Managing Data Consistency in the Amazon Redshift Database Developer Guide
• Amazon S3: Amazon S3 Data Consistency Model in the Amazon Simple Storage Service Developer Guide
Troubleshoot IAM Policies
Use the information here to help you diagnose and fix common errors, such as syntax errors, found in
IAM policies.
IAM policies use syntax that begins with the rules of JavaScript Object Notation (JSON). JSON describes
an 'object' and the name and value pairs that make up an object. The IAM policy grammar builds on that
by defining what names and values have meaning for, and are understood by, the AWS services that use
policies to grant permissions.
Common policy errors
• More Than One Policy Object (p. 337)
• More Than One Statement Element (p. 337)
• More Than One Effect, Action, or Resource Element in a Statement Element (p. 338)
• Missing Policy Summary (p. 340)
336
AWS Identity and Access Management User Guide
More Than One Policy Object
• Policy Summary Includes Unrecognized Services, Actions, or Resource Types (p. 340)
• Service Does Not Support IAM Policy Summaries (p. 341)
• My Policy Does Not Grant the Expected Permissions (p. 342)
• Missing Version Element (p. 346)
• I Can't Attach or Detach a Policy in My IAM Account (p. 346)
More Than One Policy Object
An IAM policy must consist of one and only one JSON object. You denote an object by placing { } braces
around it. Although you can nest other objects within a JSON object by embedding additional { } braces
within the outer pair, a policy can contain only one outermost pair of { } braces. The following example is
incorrect because it contains two objects at the top level (called out in red):
{
}
{
}
"Version": "2012-10-17",
"Statement":
{
"Effect":"Allow",
"Action":"ec2:Describe*",
"Resource":"*"
}
"Statement": {
"Effect": "Allow",
"Action": "s3:*",
"Resource": "arn:aws-cn:s3:::my-bucket/*"
}
You can, however, meet the intention of the previous example with the use of correct policy grammar.
Instead of including two complete policy objects each with its own Statement element, you can combine
the two blocks into a single Statement element. The Statement element has an array of two objects as its
value, as shown in the following example (called out in bold):
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:Describe*",
"Resource":" *"
},
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "arn:aws-cn:s3:::my-bucket/*"
}
]
More Than One Statement Element
This error might at first appear to be a variation on the previous section. However, syntactically it is a
different type of error. The following example has only one policy object as denoted by a single pair of { }
braces at the top level. However, that object contains two Statement elements within it.
337
AWS Identity and Access Management User Guide
More Than One Effect, Action, or
Resource Element in a Statement Element
An IAM policy must contain only one Statement element, consisting of the name (Statement) appearing
to the left of a colon, followed by its value on the right. The value of a Statement element must be an
object, denoted by { } braces, containing one Effect element, one Action element, and one Resource
element. The following example is incorrect because it contains two Statement elements in the policy
object (called out in red):
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "ec2:Describe*",
"Resource": "*"
},
"Statement": {
"Effect": "Allow",
"Action": "s3:*",
"Resource": "arn:aws-cn:s3:::my-bucket/*"
}
A value object can be an array of multiple value objects. To solve this problem, combine the two
Statement elements into one element with an object array, as shown in the following example (called out
in bold):
{
]
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:Describe*",
"Resource":"*"
},
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "arn:aws-cn:s3:::my-bucket/*"
}
The value of the Statement element is an object array. The array in this example consists of two objects,
each of which is by itself is a correct value for a Statement element. Each object in the array is separated
by commas.
More Than One Effect, Action, or Resource Element in
a Statement Element
On the value side of the Statement name/value pair, the object must consist of only one Effect element,
one Action element, and one Resource element. The following policy is incorrect because it has two
Effect elements in the value object of the Statement:
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Deny",
"Effect": "Allow",
"Action": "ec2:* ",
"Resource": "*"
}
338
AWS Identity and Access Management User Guide
More Than One Effect, Action, or
Resource Element in a Statement Element
}
Note
The policy engine does not allow such errors in new or edited policies. However, the policy
engine continues to permit policies that were saved before the engine was updated. The
behavior of existing policies with the error is as follows:
• Multiple Effect elements: only the last Effect element is observed. The others are ignored.
• Multiple Action elements: all Action elements are combined internally and treated as if they
were a single list.
• Multiple Resource elements: all Resource elements are combined internally and treated as if
they were a single list.
The policy engine does not allow you to save any policy with syntax errors. You must correct the
errors in the policy before you can save it. The Policy Validator (p. 292) tool can help you to find
all older policies with errors and can recommend corrections for them.
In each case, the solution is to remove the incorrect extra element. For Effect elements, this is
straightforward: if you want the previous example to deny permissions to Amazon EC2 instances, then
you must remove the line "Effect": "Allow", from the policy, as follows:
{
}
"Version": "2012-10-17",
"Statement": {
"Efect": "Deny",
"Action": "ec2:* ",
"Resource": "*"
}
However, if the duplicate element is Action or Resource, then the resolution can be more complicated.
You might have multiple actions that you want to allow (or deny) permission to, or you might want
to control access to multiple resources. For example, the following example is incorrect because it has
multiple Resource elements (called out in red):
{
}
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "s3:*",
"Resource": "arn:aws-cn:s3:::my-bucket",
"Resource": "arn:aws-cn:s3:::my-bucket/*"
}
Each of the required elements in a Statement element's value object can be present only once. The
solution is to place each value in an array. The following example illustrates this by making the two
separate resource elements into one Resource element with an array as the value object (called out in
bold):
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "s3:*",
"Resource": [
"arn:aws-cn:s3:::my-bucket",
339
AWS Identity and Access Management User Guide
Missing Policy Summary
}
}
]
"arn:aws-cn:s3:::my-bucket/*"
Missing Policy Summary
The IAM console includes policy summary tables that describe the access level, resources, and conditions
that are allowed or denied for each service in a policy. Policies are summarized in three tables: the policy
summary (p. 259), the service summary (p. 269), and the action summary (p. 273). The policy summary
table includes a list of services and summaries of the permissions that are defined by the chosen policy.
You can view the policy summary (p. 258) for any policies that are attached to a user on the Users page.
You can view the policy summary for managed policies on the Policies page. If AWS is unable to render
a summary for a policy, then you see the JSON policy document instead of the summary, and receive the
following error:
A summary for this policy cannot be generated. You can still view or edit the JSON policy document.
If your policy does not include a summary, one of the following errors has occurred:
• Unsupported policy element – IAM does not support generating policy summaries for policies that
include one of the following policy elements (p. 374):
• Principal
• NotPrincipal
• NotResource
• No policy permissions – If a policy does not provide any effective permissions, then the policy
summary cannot be generated. For example, if a policy includes a single statement with the element
"NotAction": "*", then it grants access to all actions except "all actions" (*). This means it grants Deny
or Allow access to nothing.
Note
You must be careful when using these policy elements such as NotPrincipal, NotAction,
and NotResource. For information about using policy elements, see IAM Policy Elements
Reference (p. 374).
You can create a policy that does not provide effective permissions if you provide mismatched services
and resources. This can occur if you specify actions in one service and resources from another service.
In this case, the policy summary does appear. The only indication that there is a problem is that the
resource column in the summary can include a resource from a different service. If this column includes
a mismatched resource, then you should review your policy for errors. To better understand your
policies, always test them with the policy simulator (p. 283).
Policy Summary Includes Unrecognized Services,
Actions, or Resource Types
In the IAM console, if a policy summary (p. 258) includes a warning symbol (
), then the policy
might include an unrecognized service, action or resource type. To learn about warnings within a policy
summary, see Policy Summary (List of Services) (p. 259).
Note
IAM reviews service names, actions, and resource types for services that support policy
summaries. However, your policy summary might include a resource value or condition that does
not exist. Always test your policies with the policy simulator (p. 283).
340
AWS Identity and Access Management User Guide
Service Does Not Support IAM Policy Summaries
If your policy includes unrecognized services, actions or resource types, one of the following errors has
occurred:
• Preview service – Services that are in preview do not support policy summaries.
• Custom service – Custom services do not support policy summaries.
• Service does not support summaries – If your policy includes a generally available (GA) service
that does not support policy summaries, then the service is included in the Unrecognized services
section of the policy summary table. Generally available services are services that are released
publicly and are not preview or custom services. If an unrecognized service is generally available
and the name is spelled correctly, then the service does not support IAM policy summaries. To learn
how to request policy summary support for a GA service, see Service Does Not Support IAM Policy
Summaries (p. 341).
• Action does not support summaries – If your policy includes a supported service with an unsupported
action, then the action is included in the Unrecognized actions section of the service summary table.
To learn about warnings within a service summary, see Service Summary (List of Actions) (p. 269).
• Resource type does not support summaries – If your policy includes a supported action with an
unsupported resource type, then the resource is included in the Unrecognized resource types section
of the service summary table. To learn about warnings within a service summary, see Service Summary
(List of Actions) (p. 269).
• Typo – Because the policy validator in AWS checks only that the JSON is syntactically correct, you
can create a policy that includes a typo. If you are certain that your policy contains none of the errors
above, then your policy might include a typo. Check for misspelled service, action, and resource type
names. For example, you might use s2 instead of s3 and ListMyBuckets instead of ListAllMyBuckets.
Another common action typo is the inclusion of unnecessary text in ARNs, such as arn:aws:s3: : :*,
or missing colons in actions, such as AWSAuthRuntimeService.AuthenticatePassword. You can evaluate
a policy that might include typos by using the policy simulator (p. 283) to confirm whether the policy
provides the permissions you intended.
Service Does Not Support IAM Policy Summaries
When a generally available (GA) service or action is not recognized by IAM policy summaries, it is possible
that the service does not support these summaries. Generally available services are services that are
released publicly and are not previewed or custom services. If an unrecognized service is generally
available and the name is spelled correctly, then the service does not support IAM policy summaries.
If your policy includes a supported service with an unsupported action, then the service does not fully
support IAM policy summaries.
To request that a service add IAM policy summary support
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
Locate the policy that includes the unsupported service:
• If the policy is a managed policy, choose Policies in the navigation pane. In the list of policies,
choose the name of the policy that you want to view.
• If the policy is an inline policy attached to the user, choose Users in the navigation pane. In the list
of users, choose the name of the user whose policy you want to view. In the table of policies for
the user, expand the header for the policy summary that you want to view.
3.
In the left side on the AWS Management Console footer, choose Feedback. In the Tell us about your
experience: box, type I request that the <ServiceName> service add support for IAM policy
summaries. If you want more than one service to support summaries, type I request that the
<ServiceName1>, <ServiceName2>, and <ServiceName3> services add support for IAM policy
summaries.
341
AWS Identity and Access Management User Guide
My Policy Does Not Grant the Expected Permissions
To request that a service add IAM policy summary support for a missing action
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.amazonaws.cn/iam/.
2.
Locate the policy that includes the unsupported service:
• If the policy is a managed policy, choose Policies in the navigation pane. In the list of policies,
choose the name of the policy that you want to view.
• If the policy is an inline policy attached to the user, choose Users in the navigation pane. In the list
of users, choose the name of the user whose policy you want to view. In the table of policies for
the user, choose the name of the policy that you want to view to expand the policy summary.
3.
In the policy summary, choose the name of the service that includes an unsupported action.
4.
In the left side on the AWS Management Console footer, choose Feedback. In the Tell us about
your experience: box, type I request that the <ServiceName> service add IAM policy summary
support for the <ActionName> action. If you want to report more than one unsupported action,
type I request that the <ServiceName> service add IAM policy summary support for the
<ActionName1>, <ActionName2>, and <ActionName3> actions.
To request that a different service includes missing actions, repeat the last three steps.
My Policy Does Not Grant the Expected Permissions
To assign permissions to a user, group, role, or resource, you create a policy, which is a document that
defines permissions. The policy document includes the following elements:
• Effect – whether the policy allows or denies access
• Action – the list of actions that are allowed or denied by the policy
• Resource – the list of resources on which the actions can occur
• Condition (Optional) – the circumstances under which the policy grants permission
To learn about these and other policy elements, see IAM Policy Elements Reference (p. 374).
To grant access, your policy must define an action with a supported resource. If your policy also includes
a condition, that condition must include a global condition key (p. 422) or must apply to the action. To
learn which resources are supported by an action, see the AWS documentation for your service. To learn
which conditions are supported by an action, see AWS Service Actions and Condition Context Keys for
Use in IAM Policies (p. 430).
To learn whether your policy defines an action, resource, or condition that does not grant permissions,
you can view the policy summary (p. 259) for your policy using the IAM console at https://
console.amazonaws.cn/iam/. You can use policy summaries to identify and correct problems in your
policy.
There are several reasons why an element might not grant permissions despite being defined in the IAM
policy:
• An action is defined without an applicable resource (p. 343)
• A resource is defined without an applicable action (p. 343)
• A condition is defined without an applicable action (p. 344)
To view examples of policy summaries that include warnings, see the section called “Policy Summary
(List of Services)” (p. 259).
342
AWS Identity and Access Management User Guide
My Policy Does Not Grant the Expected Permissions
An action is defined without an applicable resource
The policy below defines all ec2:Describe* actions and defines a specific resource. None of the
ec2:Describe actions are granted because none of these actions support resource-level permissions.
Resource-level permissions mean that the action supports resources using ARNs in the policy's
Resource (p. 383) element. If an action does not support resource-level permissions, then that
statement in the policy must use a wildcard (*) in the Resource element. To learn which services support
resource-level permissions, see AWS Services That Work with IAM (p. 363).
{
}
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2:Describe*",
"Resource": "arn:aws:ec2:us-east-2:ACCOUNT-ID:instance/*"
}]
This policy does not provide any permissions, and the policy summary includes the following error:
This policy does not grant any permissions. To grant access, policies must have an action
that has an applicable resource or condition.
To fix this policy, you must use * in the Resource element.
{
}
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "ec2:Describe*",
"Resource": "*"
}]
A resource is defined without an applicable action
The policy below defines an Amazon S3 bucket resource but does not include an S3 action that can be
performed on that resource. This policy also grants full access to all Amazon CloudFront actions.
{
}
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "cloudfront:*",
"Resource": [
"arn:aws:cloudfront:*",
"arn:aws:s3:::examplebucket"
]
}]
This policy provides permissions for all CloudFront actions. But because the policy defines the S3
examplebucket resource without defining any S3 actions, the policy summary includes the following
warning:
This policy defines some actions, resources, or conditions that do not provide permissions.
To grant access, policies must have an action that has an applicable resource or condition.
To fix this policy to provide S3 bucket permissions, you must define S3 actions that can be performed on
a bucket resource.
343
AWS Identity and Access Management User Guide
My Policy Does Not Grant the Expected Permissions
{
}
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"cloudfront:*",
"s3:CreateBucket",
"s3:ListBucket*",
"s3:PutBucket*",
"s3:GetBucket*"
],
"Resource": [
"arn:aws:cloudfront:*",
"arn:aws:s3:::examplebucket"
]
}]
Alternately, to fix this policy to provide only CloudFront permissions, remove the S3 resource.
A condition is defined without an applicable action
The policy below defines two Amazon S3 actions for all S3 resources, if the S3 prefix equals custom and
the version ID equals 1234. However, the s3:VersionId condition key is used for object version tagging
and is not supported by the defined bucket actions. To learn which conditions are supported by an
action, see AWS Service Actions and Condition Context Keys for Use in IAM Policies (p. 430) and follow
the link to the service documentation for condition keys.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucketVersions",
"s3:ListBucket"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"s3:prefix": [
"custom"
],
"s3:VersionId": [
"1234"
]
}
}
}
]
This policy provides permissions for the s3:ListBucket action and the s3:ListBucket action if the
bucket name includes the custom prefix. But because the s3:VersionId condition is not supported by any
of the defined actions, the policy summary includes the following error:
This policy does not grant any permissions. To grant access, policies must have an action
that has an applicable resource or condition.
To fix this policy to use S3 object version tagging, you must define an S3 action that supports the
s3:VersionId condition key.
344
AWS Identity and Access Management User Guide
My Policy Does Not Grant the Expected Permissions
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucketVersions",
"s3:ListBucket",
"s3:GetObjectVersion"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"s3:prefix": [
"custom"
],
"s3:VersionId": [
"1234"
]
}
}
}
]
This policy provides permissions for every action and condition in the policy. However, the policy
still does not provide any permissions because there is no case where a single action matches both
conditions. Instead, you must create two separate statements that each include only actions with the
conditions to which they apply.
To fix this policy, create two statements. The first statement includes the actions that support the
s3:prefix condition, and the second statement includes the actions that support the s3:VersionId
condition.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucketVersions",
"s3:ListBucket"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"s3:prefix": "custom"
}
}
},
{
"Effect": "Allow",
"Action": "s3:GetObjectVersion",
"Resource": "*",
"Condition": {
"StringEquals": {
"s3:VersionId": "1234"
}
}
}
]
345
AWS Identity and Access Management User Guide
Missing Version Element
Missing Version Element
A Version policy element is different from a policy version. The Version policy element is used within
a policy and defines the version of the policy language. A policy version, on the other hand, is created
when you make changes to a customer managed policy in IAM. The changed policy doesn't overwrite
the existing policy. Instead, IAM creates a new version of the managed policy. To learn more about the
Version policy element see the section called “Version” (p. 375). To learn more about policy versions,
see the section called “Versioning for Managed Policies” (p. 240).
As AWS features evolve, new capabilities are added to IAM policies to support those features.
Sometimes, an update to the policy syntax includes a new version number. If you use newer features
of the policy grammar in your policy, then you must tell the policy parsing engine which version
you are using. The default policy version is "2008-10-17." If you want to use any policy feature that
was introduced later, then you must specify the version number that supports the feature you want.
We recommend that you always include the latest policy syntax version number, which is currently
"Version": "2012-10-17". For example, the following policy is incorrect because it uses a policy variable
${...} in the ARN for a resource without specifying a policy syntax version that supports policy variables
(called out in red):
{
}
"Statement":
{
"Action": "iam:*AccessKey*",
"Effect": "Allow",
"Resource": "arn:aws-cn:iam::123456789012:user/${aws:username}"
}
Adding a Version element at the top of the policy with the value 2012-10-17, the first IAM API version
that supports policy variables, solves this problem (called out in bold):
{
}
"Version": "2012-10-17",
"Statement":
{
"Action": "iam:*AccessKey*",
"Effect": "Allow",
"Resource": "arn:aws-cn:iam::123456789012:user/${aws:username}"
}
I Can't Attach or Detach a Policy in My IAM Account
Some AWS managed policies are linked to a service. These policies are used only with a service-linked
role (p. 99) for that service. In the IAM console, when you view the Summary page for a policy, the
page includes a banner to indicate that the policy is linked to a service. You cannot attach this policy
to a user, group, or role within IAM. When you create a service-linked role for the service, this policy is
automatically attached to your new role. Because the policy is required, you cannot detach the policy
from the service-linked role.
Troubleshooting IAM Roles
Use the information here to help you diagnose and fix common issues that you might encounter when
working with IAM roles.
346
AWS Identity and Access Management User Guide
I Can't Assume a Role
Topics
• I Can't Assume a Role (p. 347)
• A New Role Appeared in My IAM Account (p. 347)
• I Can't Edit or Delete a Role in My IAM Account (p. 348)
I Can't Assume a Role
• Verify that your IAM policy grants you permission to call sts:AssumeRole for the role that you want to
assume. The Action element of your IAM policy must allow you to call the AssumeRole action, and the
Resource element of your IAM policy must specify the role that you want to assume. For example, the
Resource element can specify a role by its Amazon Resource Name (ARN) or by using a wildcard (*). For
example, at least one policy applicable to you must grant permissions similar to the following:
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws-cn:iam::account_id_number:role/role-name-you-want-to-assume"
• Verify that you meet all the conditions that are specified in the role's trust policy. A Condition can
specify an expiration date, an external ID, or that a request must come only from specific IP addresses.
In the following example, if the current date is any time after the specified date, then the policy never
matches and cannot grant you the permission to assume the role.
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws-cn:iam::account_id_number:role/role-name-you-want-to-assume"
"Condition": {
"DateLessThan" : {
"aws:CurrentTime" : "2016-05-01T12:00:00Z"
}
}
• Verify that the AWS account that you are calling AssumeRole from is a trusted entity for the role that
you are assuming. Trusted entities are defined as a Principal in a role's trust policy. The following
example is a trust policy attached to the role you want to assume. In this example, the account ID
with the IAM user you signed-in with must be 123456789012. If your account number is not listed
in the Principal element of the role's trust policy, then you cannot assume the role, no matter what
permissions are granted to you in access policies. Note that the example policy limits permissions to
actions that occur between July 1, 2017 and December 31, 2017 (UTC), inclusive. If you log in before
or after those dates, then the policy does not match, and you cannot assume the role.
"Effect": "Allow",
"Principal": { "AWS": "arn:aws-cn:iam::123456789012:root" },
"Action": "sts:AssumeRole",
"Condition": {
"DateGreaterThan": {"aws:CurrentTime": "2017-07-01T00:00:00Z"},
"DateLessThan": {"aws:CurrentTime": "2017-12-31T23:59:59Z"}
}
A New Role Appeared in My IAM Account
Some AWS services require that you use a unique type of service role that is linked directly to the service.
This service-linked role (p. 99) is predefined by the service and includes all the permissions that the
service requires. This makes setting up a service easier because you don’t have to manually add the
necessary permissions. For general information about service-linked roles, see Using Service-Linked
Roles (p. 139).
347
AWS Identity and Access Management User Guide
I Can't Edit or Delete a Role in My IAM Account
You might already be using a service when it begins supporting service-linked roles. If so, you might
receive an email telling you about a new role in your account. This role includes all the permissions that
the service needs to perform actions on your behalf. You don't need to take any action to support this
role. However, you should not delete the role from your account. Doing so could remove permissions that
the service needs to access AWS resources. You can view the service-linked roles in your account by going
to the IAM Roles page of the IAM console. Service-linked roles appear with (Service-linked role) in the
Trusted entities column of the table.
For information about which services support service-linked roles, see AWS Services That Work
with IAM (p. 363) and look for the services that have Yes in the Service-Linked Role column. For
information about using the service-linked role for a service, choose the Yes link.
I Can't Edit or Delete a Role in My IAM Account
You cannot delete or edit the permissions for a service-linked role (p. 99) in IAM. These roles include
predefined trusts and permissions that are required by the service in order to perform actions on your
behalf. You can use the IAM console, AWS CLI, or API to edit only the description of a service-linked role.
You can view the service-linked roles in your account by going to the IAM Roles page in the console.
Service-linked roles appear with (Service-linked role) in the Trusted entities column of the table. A
banner on the role's Summary page also indicates that the role is a service-linked role. You can manage
and delete these roles only through the linked service, if that service supports the action. Be careful
when modifying or deleting a service-linked role because doing so could remove permissions that the
service needs to access AWS resources.
For information about which services support service-linked roles, see AWS Services That Work with
IAM (p. 363) and look for the services that have Yes in the Service-Linked Role column.
Troubleshooting Amazon EC2 and IAM
Use the information here to help you troubleshoot and fix access denied or other issues that you might
encounter when working with Amazon EC2 and IAM.
Topics
• When attempting to launch an instance, I don't see the role I expected to see in the Amazon EC2
console IAM role list. (p. 348)
• The credentials on my instance are for the wrong role. (p. 349)
• When I attempt to call the AddRoleToInstanceProfile, I get an AccessDenied error. (p. 349)
• Amazon EC2: When I attempt to launch an instance with a role, I get an AccessDenied error. (p. 349)
• I can't access the temporary security credentials on my EC2 instance. (p. 350)
• What do the errors from the info document in the IAM subtree mean? (p. 350)
When attempting to launch an instance, I don't see
the role I expected to see in the Amazon EC2 console
IAM role list.
Check the following:
• If you are signed in as an IAM user, verify that you have permission to call ListInstanceProfiles.
For information about the permissions necessary to work with roles, see "Permissions Required for
348
AWS Identity and Access Management User Guide
The credentials on my instance are for the wrong role.
Using Roles with Amazon EC2" in Using an IAM Role to Grant Permissions to Applications Running on
Amazon EC2 Instances (p. 177). For information about adding permissions to a user, see Working with
Policies (p. 250).
If you cannot modify your own permissions, you must contact an administrator who can work with IAM
in order to update your permissions.
• If you created a role by using the IAM CLI or API, verify that you created an instance profile and added
the role to that instance profile. Also, if you name your role and instance profile differently, you won't
see the correct role name in the list of IAM roles in the Amazon EC2 console. The IAM Role list in the
Amazon EC2 console lists the names of instance profiles, not the names of roles. You will have to
select the name of the instance profile that contains the role you want. For details about instance
profiles, see Using Instance Profiles (p. 180).
Note
If you use the IAM console to create roles, you don't need to work with instance profiles. For
each role that you create in the IAM console, an instance profile is created with the same
name as the role, and the role is automatically added to that instance profile. An instance
profile can contain only one IAM role, and that limit cannot be increased.
The credentials on my instance are for the wrong
role.
If the role in the instance profile was replaced recently, your application will need to wait for the next
automatically scheduled credential rotation before credentials for your role become available.
When I attempt to call the AddRoleToInstanceProfile, I get an
AccessDenied error.
If you are making requests as an IAM user, verify that you have the following permissions:
• iam:AddRoleToInstanceProfile with the resource matching the instance profile ARN (for example,
arn:aws-cn:iam::999999999999:instance-profile/ExampleInstanceProfile).
For more information about the permissions necessary to work with roles, see "How Do I Get Started?" in
Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances (p. 177). For
information about adding permissions to a user, see Working with Policies (p. 250).
Amazon EC2: When I attempt to launch an instance
with a role, I get an AccessDenied error.
Check the following:
• Launch an instance without an instance profile. This will help ensure that the problem is limited to IAM
roles for Amazon EC2 instances.
• If you are making requests as an IAM user, verify that you have the following permissions:
• ec2:RunInstances with a wildcard resource ("*")
• iam:PassRole with the resource matching the role ARN (for example, arn:awscn:iam::999999999999:role/ExampleRoleName)
• Call the IAM GetInstanceProfile action to ensure that you are using a valid instance profile name or a
valid instance profile ARN. For more information, see Using IAM roles with Amazon EC2 instances.
349
AWS Identity and Access Management User Guide
I can't access the temporary security
credentials on my EC2 instance.
• Call the IAM GetInstanceProfile action to ensure that the instance profile has a role. Empty instance
profiles will fail with an AccessDenied error. For more information about creating a role, see Creating
IAM Roles (p. 146).
For more information about the permissions necessary to work with roles, see "How Do I Get Started?" in
Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances (p. 177). For
information about adding permissions to a user, see Working with Policies (p. 250).
I can't access the temporary security credentials on
my EC2 instance.
Check the following:
• Can you can access another part of the instance metadata service (IMDS)? If not, check that you have
no firewall rules blocking access to requests to the IMDS.
[[email protected] ~]$ GET http://169.254.169.254/latest/meta-data/
hostname; echo
• Does the iam subtree of the IMDS exist? If not, verify that your instance has an IAM instance profile
associated with it by calling ec2:DescribeInstances.
[[email protected] ~]$ GET http://169.254.169.254/latest/meta-data/iam;
echo
• Check the info document in the IAM subtree for an error. If you have an error, see What do the errors
from the info document in the IAM subtree mean? (p. 350) for more information.
[[email protected] ~]$ GET http://169.254.169.254/latest/meta-data/iam/
info; echo
What do the errors from the info document in the IAM
subtree mean?
The iam/info document indicates "Code":"InstanceProfileNotFound".
Your IAM instance profile has been deleted and Amazon EC2 can no longer provide credentials to your
instance. You will need to terminate your instances and restart with a valid instance profile.
If an instance profile with that name exists, check that the instance profile wasn't deleted and another
was created with the same name.
To verify the status of the instance profile:
1.
Call the IAM GetInstanceProfile action to get the InstanceProfileId.
2.
Call the Amazon EC2 DescribeInstances action to get the IamInstanceProfileId for the instance.
3.
Verify that the InstanceProfileId from the IAM action matches the IamInstanceProfileId from
the Amazon EC2 action.
If the IDs are different, then the instance profile attached to your instances is no longer valid. You will
need to terminate your instances and restart with a valid instance profile.
350
AWS Identity and Access Management User Guide
Troubleshooting Amazon S3 and IAM
The iam/info document indicates a success but indicates
"Message":"Instance Profile does not contain a role..."
The role has been removed from the instance profile by the IAM RemoveRoleFromInstanceProfile action.
You can use the IAM AddRoleToInstanceProfile action to attach a role to the instance profile. Your
application will need to wait until the next scheduled refresh to access the credentials for the role.
The iam/security-credentials/[role-name] document indicates
"Code":"AssumeRoleUnauthorizedAccess".
Amazon EC2 does not have permission to assume the role. Permission to assume the role is controlled by
the trust policy attached to the role, like the example that follows. Use the IAM UpdateAssumeRolePolicy
API to update the trust policy.
{"Version": "2012-10-17","Statement": [{"Effect": "Allow","Principal": {"Service":
["ec2.amazonaws.com"]},"Action": ["sts:AssumeRole"]}]}
Your application will need to wait until the next automatically scheduled refresh to access the credentials
for the role.
Troubleshooting Amazon S3 and IAM
Use the information here to help you troubleshoot and fix issues that you might encounter when
working with Amazon S3 and IAM.
How do I grant anonymous access to an Amazon S3
bucket?
You use an Amazon S3 bucket policy that specifies a wildcard (*) in the principal element, which means
anyone can access the bucket. With anonymous access, anyone (including users without an AWS account)
will be able to access the bucket. For a sample policy, see Example Cases for Amazon S3 Bucket Policies
in the Amazon Simple Storage Service Developer Guide.
Troubleshooting SAML 2.0 Federation with AWS
Use the information here to help you diagnose and fix issues that you might encounter when working
with SAML 2.0 and federation with IAM.
Error: Your request included an invalid SAML
response. To logout, click here.
This error can occur when the SAML response from the identity provider does not include an attribute
with the Name set to https://aws.amazon.com/SAML/Attributes/Role. The attribute must contain one or
more AttributeValue elements, each containing a comma-separated pair of strings:
• The ARN of a role that the user can be mapped to
351
AWS Identity and Access Management User Guide
Error: RoleSessionName is required in AuthnResponse
(Service: AWSSecurityTokenService; Status
Code: 400; Error Code: InvalidIdentityToken)
• The ARN of the SAML provider
For more information, see Configuring SAML Assertions for the Authentication Response (p. 125). To
view the SAML response in your browser, follow the steps listed in How to View a SAML Response in Your
Browser for Troubleshooting (p. 353).
Error: RoleSessionName is required in AuthnResponse
(Service: AWSSecurityTokenService; Status Code: 400;
Error Code: InvalidIdentityToken)
This error can occur when the SAML response from the identity provider does not include an attribute
with the Name set to https://aws.amazon.com/SAML/Attributes/RoleSessionName. The attribute value is
an identifier for the user and is typically a user ID or an email address.
For more information, see Configuring SAML Assertions for the Authentication Response (p. 125). To
view the SAML response in your browser, follow the steps listed in How to View a SAML Response in Your
Browser for Troubleshooting (p. 353).
Error: Not authorized to perform
sts:AssumeRoleWithSAML (Service:
AWSSecurityTokenService; Status Code: 403; Error
Code: AccessDenied)
This error can occur if the IAM role specified in the SAML response is misspelled or does not exist. Correct
the name of the role in the SAML service provider configuration.
This error can also occur if the federated users do not have permissions to assume the role. The role must
have a trust policy that specifies the ARN of the IAM SAML identity provider as the Principal. The role
also contains conditions that control which users can assume the role. Ensure that your users meet the
requirements of the conditions.
This error can also occur if the SAML response does not include a Subject containing a NameID.
For more information see Establish Permissions in AWS for Federated Users and Configuring SAML
Assertions for the Authentication Response (p. 125). To view the SAML response in your browser, follow
the steps listed in How to View a SAML Response in Your Browser for Troubleshooting (p. 353).
Error: RoleSessionName in AuthnResponse
must match [a-zA-Z_0-9+=,[email protected]]{2,64} (Service:
AWSSecurityTokenService; Status Code: 400; Error
Code: InvalidIdentityToken)
This error can occur if the RoleSessionName attribute value is too long or contains invalid characters. The
maximum valid length is 64 characters.
For more information, see Configuring SAML Assertions for the Authentication Response (p. 125). To
view the SAML response in your browser, follow the steps listed in How to View a SAML Response in Your
Browser for Troubleshooting (p. 353).
352
AWS Identity and Access Management User Guide
Error: Response signature invalid (Service:
AWSSecurityTokenService; Status Code:
400; Error Code: InvalidIdentityToken)
Error: Response signature invalid (Service:
AWSSecurityTokenService; Status Code: 400; Error
Code: InvalidIdentityToken)
This error can occur when federation metadata of the identity provider does not match the metadata
of the IAM identity provider. For example, the metadata file for the identity service provider might have
changed to update an expired certificate. Download the updated SAML metadata file from your identity
service provider. Then update it in the AWS identity provider entity that you define in IAM with the aws
iam update-saml-provider cross-platform CLI command or the Update-IAMSAMLProvider PowerShell
cmdlet.
Error: Failed to assume role: Issuer not
present in specified provider (Service:
AWSOpenIdDiscoveryService; Status Code: 400; Error
Code: AuthSamlInvalidSamlResponseException)
This error can occur if the issuer in the SAML response does not match the issuer declared in the
federation metadata file uploaded to AWS when you created the identity provider in IAM.
Error: Could not parse metadata.
This error can occur if your metadata file is not formatted properly.
When you create or manage a SAML identity provider (p. 122) in the AWS Management Console, you
must retrieve the SAML metadata document from your identity provider. This metadata file includes the
issuer's name, expiration information, and keys that can be used to validate the SAML authentication
response (assertions) that are received from the IdP. The metadata file must be encoded in UTF-8
format without a byte order mark (BOM). Also, the x.509 certificate that is included as part of the SAML
metadata document must use a key size of at least 1024 bits. If the key size is smaller, the IdP creation
fails with an "Unable to parse metadata" error. To remove the BOM, you can encode the file as UTF-8
using a text editing tool, such as Notepad++.
How to View a SAML Response in Your Browser for
Troubleshooting
The following procedures describe how to view the SAML response from your service provider from in
your browser when troubleshooting a SAML 2.0–related issue.
For all browsers, go to the page where you can reproduce the issue. Then follow the steps for the
appropriate browser:
Topics
• Google Chrome (p. 354)
• Mozilla Firefox (p. 354)
• Apple Safari (p. 354)
• Microsoft Internet Explorer (p. 354)
• What to do with the Base64-encoded SAML response (p. 355)
353
AWS Identity and Access Management User Guide
How to View a SAML Response in
Your Browser for Troubleshooting
Google Chrome
To view a SAML response in Chrome
These steps were tested using version 54.0.2840.87m. If you use another version, you might need to
adapt the steps accordingly.
1.
Press F12 to start the developer console.
2.
Select the Network tab, and then select Preserve log.
3.
Reproduce the issue.
4.
Look for a SAML Post in the developer console pane. Select that row, and then view the Headers tab
at the bottom. Look for the SAMLResponse attribute that contains the encoded request.
Mozilla Firefox
To view a SAML response in Firefox
This procedure was tested on version 37.0.2 of Mozilla Firefox. If you use another version, you might
need to adapt the steps accordingly.
1.
Press F12 to start the developer console.
2.
In the upper right of the developer tools window, click options (the small gear icon). Under Common
Preferences select Enable persistent logs.
3.
Select the Network tab.
4.
Reproduce the issue.
5.
Look for a POST SAML in the table. Select that row. In the Form Data window on the right, select
the Params tab and find the SAMLResponse element.
Apple Safari
To view a SAML response in Safari
These steps were tested using version 8.0.6 (10600.6.3). If you use another version, you might need to
adapt the steps accordingly.
1.
Enable Web Inspector in Safari. Open the Preferences window, select the Advanced tab, and then
select Show Develop menu in the menu bar.
2.
Now you can open Web Inspector. Click Develop, then select Show Web Inspector.
3.
Select the Resources tab.
4.
Reproduce the issue.
5.
Look for a saml-signin.aws.amazon.com request.
6.
Scroll down to find Request Data with the name SAMLResponse. The associated value is the Base64encoded response.
Microsoft Internet Explorer
To view a SAML response in Internet Explorer
The best way analyze network traffic in Internet Explorer is through the use of a third-party tool.
354
AWS Identity and Access Management User Guide
How to View a SAML Response in
Your Browser for Troubleshooting
•
Follow the steps at http://social.technet.microsoft.com/wiki/contents/articles/3286.ad-fs-2-0-howto-use-fiddler-web-debugger-to-analyze-a-ws-federation-passive-sign-in.aspx to download and
install Fiddler and capture the data.
What to do with the Base64-encoded SAML response
Once you find the Base64-encoded SAML response element in your browser, copy it and use your favorite
Base-64 decoding tool to extract the XML tagged response.
Security Tip
Because the SAML response data that you are viewing might contain sensitive security data, we
recommend that you do not use an online base64 decoder. Instead use a tool installed on your
local computer that does not send your SAML data over the network.
Built-in option for Windows systems (PowerShell):
PS C:
\> [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String("base64encodedtext"))
Built-in option for MacOS and Linux systems:
$ echo "base64encodedtext" | base64 --decode
355
AWS Identity and Access Management User Guide
IAM Identifiers
Reference Information for AWS
Identity and Access Management
Use the topics in this section to find detailed reference material for various aspects of IAM and AWS STS.
Topics
• IAM Identifiers (p. 356)
• Limitations on IAM Entities and Objects (p. 360)
• AWS Services That Work with IAM (p. 363)
• AWS IAM Policy Reference (p. 373)
IAM Identifiers
IAM uses a few different identifiers for users, groups, roles, policies, and server certificates. This section
describes the identifiers and when you use each.
Topics
• Friendly Names and Paths (p. 356)
• IAM ARNs (p. 357)
• Unique IDs (p. 359)
Friendly Names and Paths
When you create a user, a role, a group, or a policy, or when you upload a server certificate, you give it a
friendly name, such as Bob, TestApp1, Developers, ManageCredentialsPermissions, or ProdServerCert.
If you are using the IAM API or AWS Command Line Interface (AWS CLI) to create IAM entities, you
can also give the entity an optional path. You can use a single path, or nest multiple paths as if they
were a folder structure. For example, you could use the nested path /division_abc/subdivision_xyz/
product_1234/engineering/ to match your company's organizational structure. You could then create
a policy to allow all users in that path to access the policy simulator API. To view this policy, see IAM:
Access the Policy Simulator API Based on User Path (p. 313). For additional examples of how you might
use paths, see IAM ARNs (p. 357).
Just because you give a user and group the same path doesn't automatically put that user in that group.
For example, you might create a Developers group and specify its path as /division_abc/subdivision_xyz/
356
AWS Identity and Access Management User Guide
IAM ARNs
product_1234/engineering/. Just because you create a user named Bob and give him that same path
doesn't automatically put Bob in the Developers group. IAM doesn't enforce any boundaries between
users or groups based on their paths. Users with different paths can use the same resources (assuming
they've been granted permission to those resources). For information about limitations on names, see
Limitations on IAM Entities and Objects (p. 360).
IAM ARNs
Most resources have a friendly name (for example, a user named Bob or a group named Developers).
However, the access policy language requires you to specify the resource or resources using the following
Amazon Resource Name (ARN) format.
arn:partition:service:region:account:resource
Where:
• partition identifies the partition that the resource is in. For standard AWS regions, the partition is aws.
If you have resourses in other partitions, the partition is aws-partitionname. For example, the partition
for resources in the China (Beijing) region is aws-cn.
• service identifies the AWS product. For IAM resources, this is always iam.
• region is the region the resource resides in. For IAM resources, this is always left blank.
• account is the AWS account ID with no hyphens (for example, 123456789012).
• resource is the portion that identifies the specific resource by name.
You can use ARNs in IAM for users (IAM and federated), groups, roles, policies, instance profiles, and
server certificates (p. 87). The following table shows the ARN format for each and an example. The
region portion of the ARN is blank because IAM resources are global.
Note
Many of the following examples include paths in the resource part of the ARN. Paths cannot be
created or manipulated in the AWS Management Console. To use paths you must work with the
resource by using the AWS API, the AWS CLI, or the Tools for Windows PowerShell.
The following examples show ARNs for different types of IAM resources.
• The AWS account - the account itself:
arn:aws-cn:iam::123456789012:root
• An IAM user in the account:
arn:aws-cn:iam::123456789012:user/Bob
• Another user with a path reflecting an organization chart:
arn:aws-cn:iam::123456789012:user/division_abc/subdivision_xyz/Bob
• An IAM group:
arn:aws-cn:iam::123456789012:group/Developers
• An IAM group with a path:
arn:aws-cn:iam::123456789012:group/division_abc/subdivision_xyz/product_A/Developers
• An IAM role:
arn:aws-cn:iam::123456789012:role/S3Access
• A managed policy:
arn:aws-cn:iam::123456789012:policy/ManageCredentialsPermissions
357
AWS Identity and Access Management User Guide
IAM ARNs
• An instance profile that can be associated with an EC2 instance:
arn:aws-cn:iam::123456789012:instance-profile/Webserver
• A federated user identified in IAM as "Bob":
arn:aws-cn:sts::123456789012:federated-user/Bob
• The active session of someone assuming the role of "Accounting-Role", with a role session name of
"Mary":
arn:aws-cn:sts::123456789012:assumed-role/Accounting-Role/Mary
• A server certificate
arn:aws-cn:iam::123456789012:server-certificate/ProdServerCert
• A server certificate with a path that reflects an organization chart:
arn:aws-cn:iam::123456789012:server-certificate/division_abc/subdivision_xyz/
ProdServerCert
• Identity providers (SAML and OIDC):
arn:aws-cn:iam::123456789012:saml-provider/ADFSProvider
arn:aws-cn:iam::123456789012:oidc-provider/GoogleProvider
The following example shows a policy you could assign to Bob to allow him to manage his own access
keys. Notice that the resource is the IAM user Bob.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["iam:*AccessKey*"],
"Resource": "arn:aws-cn:iam::ACCOUNT-ID-WITHOUT-HYPHENS:user/division_abc/
subdivision_xyz/Bob"
}]
}
Note
When you use ARNs to identify resources in an IAM policy, you can include policy variables that
let you include placeholders for run-time information (such as the user's name) as part of the
ARN. For more information, see IAM Policy Variables Overview (p. 395)
You can use wildcards in the resource portion of the ARN to specify multiple users or groups or policies.
For example, to specify all users working on product_1234, you would use:
arn:aws-cn:iam::123456789012:user/division_abc/subdivision_xyz/product_1234/*
Let's say you have users whose names start with the string app_. You could refer to them all with the
following ARN.
arn:aws-cn:iam::123456789012:user/division_abc/subdivision_xyz/product_1234/app_*
To specify all users, groups, or policies in your AWS account, use a wildcard after the user/, group/, or
policy part of the ARN, respectively.
arn:aws-cn:iam::123456789012:user/*
arn:aws-cn:iam::123456789012:group/*
358
AWS Identity and Access Management User Guide
Unique IDs
arn:aws-cn:iam::123456789012:policy/*
Don't use a wildcard in the user/, group/, or policy part of the ARN. In other words, the following is not
allowed:
arn:aws-cn:iam::123456789012:u*
Example Use of Paths and ARNs for a Project-Based Group
Paths cannot be created or manipulated in the AWS Management Console. To use paths you must work
with the resource by using the AWS API, the AWS CLI, or the Tools for Windows PowerShell.
In this example, Jules in the Marketing_Admin group creates a project-based group within the /
marketing/ path, and assigns users from different parts of the company to the group. This example
illustrates that a user's path isn't related to the groups the user is in.
The marketing group has a new product they'll be launching, so Jules creates a new group in the /
marketing/ path called Widget_Launch. Jules then assigns the following policy to the group, which gives
the group access to objects in the part of the example_bucket designated to this particular launch.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "arn:aws-cn:s3:::example_bucket/marketing/newproductlaunch/widget/*"
},
{
"Effect": "Allow",
"Action": "s3:ListBucket*",
"Resource": "arn:aws-cn:s3:::example_bucket",
"Condition": {"StringLike": {"s3:prefix": "marketing/newproductlaunch/widget/*"}}
}
]
Jules then assigns the users who are working on this launch to the group. This includes Patricia and Eli
from the /marketing/ path. It also includes Chris and Chloe from the /sales/ path, and Aline and Jim
from the /legal/ path.
Unique IDs
When IAM creates a user, group, role, policy, instance profile, or server certificate, it assigns to each
entity a unique ID that looks like the following example:
AIDAJQABLZS4A3QDU576Q
For the most part, you use friendly names and ARNs when you work with IAM entities, so you don't need
to know the unique ID for a specific entity. However, the unique ID can sometimes be useful when it isn't
practical to use friendly names.
One example pertains to reusing friendly names in your AWS account. Within your account, a friendly
name for a user, group, or policy must be unique. For example, you might create an IAM user named
David. Your company uses Amazon S3 and has a bucket with folders for each employee; the bucket has
a resource-based policy (a bucket policy) that lets users access only their own folders in the bucket.
Suppose that the employee named David leaves your company and you delete the corresponding IAM
user. But later another employee named David starts and you create a new IAM user named David. If the
359
AWS Identity and Access Management User Guide
Limits
bucket policy specifies the IAM user named David, the policy could end up granting the new David access
to information in the Amazon S3 bucket that was left by the former David.
However, every IAM user has a unique ID, even if you create a new IAM user that reuses a friendly name
that you deleted before. In the example, the old IAM user David and the new IAM user David have
different unique IDs. If you create resource policies for Amazon S3 buckets that grant access by unique ID
and not just by user name, it reduces the chance that you could inadvertently grant access to information
that an employee should not have.
Another example where user IDs can be useful is if you maintain your own database (or other store) of
IAM user information. The unique ID can provide a unique identifier for each IAM user you create, even if
over time you have IAM users that reuse a name, as in the previous example.
Getting the Unique ID
The unique ID for an IAM entity is not available in the IAM console. To get the unique ID, you can use the
following AWS CLI commands or IAM API calls.
AWS CLI:
• get-group
• get-role
• get-user
• get-policy
• get-instance-profile
• get-server-certificate
IAM API:
• GetGroup
• GetRole
• GetUser
• GetPolicy
• GetInstanceProfile
• GetServerCertificate
Limitations on IAM Entities and Objects
Entities and objects in IAM have size limitations. IAM limits how you name an entity, the number of
entities you can create, and the number of characters you can use in an entity.
Note
To get account-level information about entity usage and quotas, use the GetAccountSummary
API action or the get-account-summary AWS CLI command.
IAM Entity Name Limits
The following are restrictions on IAM names:
• Policy documents can contain only the following Unicode characters: horizontal tab (U+0009), linefeed
(U+000A), carriage return (U+000D), and characters in the range U+0020 to U+00FF.
• Names of users, groups, roles, policies, instance profiles, and server certificates must be alphanumeric,
including the following common characters: plus (+), equal (=), comma (,), period (.), at (@), underscore
(_), and hyphen (-).
360
AWS Identity and Access Management User Guide
IAM Entity Object Limits
• Names of users, groups, and roles must be unique within the account. They are not distinguished by
case, for example, you cannot create groups named both "ADMINS" and "admins".
• Path names must begin and end with a forward slash (/).
• Policy names for inline policies (p. 235) must be unique to the user, group, or role they are embedded
in, and can contain any Basic Latin (ASCII) characters minus the following reserved characters:
backward slash (\), forward slash (/), asterisk (*), question mark (?), and white space. These characters
are reserved according to RFC 3986.
• User passwords (login profiles) can contain any Basic Latin (ASCII) characters.
• AWS account ID aliases must be unique across AWS products, and must be alphanumeric following
DNS naming conventions. An alias must be lowercase, it must not start or end with a hyphen, it cannot
contain two consecutive hyphens, and it cannot be a 12 digit number.
For a list of Basic Latin (ASCII) characters, go to the Library of Congress Basic Latin (ASCII) Code Table.
IAM Entity Object Limits
AWS allows you to request an increase to default IAM entity limits. To learn how to request a limit
increase to these default limits, see AWS Service Limits in the Amazon Web Services General Reference
documentation.
Default limits for IAM entities:
Resource
Default Limit
Customer managed policies in an AWS account
1500
Groups in an AWS account
300
Roles in an AWS account
1000
Users in an AWS account
5000 (If you need to add a large number
of users, consider using temporary security
credentials (p. 193).)
Instance profiles in an AWS account
1000
Server certificates stored in an AWS account
20
For most IAM entity limits, you cannot request a limit increase.
Limits for IAM entities:
Resource
Limit
Access keys assigned to an IAM user
2
Aliases for an AWS account
1
Groups an IAM user can be a member of
10
Identity providers (IdPs) associated with an IAM
SAML provider object
10
Keys per SAML provider
10
Login profiles for an IAM user
1
361
AWS Identity and Access Management User Guide
IAM Entity Character Limits
Resource
Limit
Managed policies attached to an IAM group
10
Managed policies attached to an IAM role
10
Managed policies attached to an IAM user
10
Roles in an instance profile
1
SAML providers in an AWS account
100
Signing certificates assigned to an IAM user
2
SSH public keys assigned to an IAM user
5
Versions of a managed policy that can be stored
5
IAM Entity Character Limits
The following are the maximum lengths for entities:
Description
Limit
Path
512 characters
User name
64 characters
Group name
128 characters
Role name
64 characters
Important
If you intend to use a role with the Switch
Role feature in the AWS console, then
the combined Path and RoleName cannot
exceed 64 characters.
Instance profile name
128 characters
Unique IDs created by IAM, for example:
128 characters
•
•
•
•
User IDs that begin with AIDA
Group IDs that begin with AGPA
Role IDs that begin with AROA
Managed policy IDs that begin with ANPA
• Server certificate IDs that begin with ASCA
Note
This is not intended to be an exhaustive
list, nor is it a guarantee that IDs of a
certain type begin only with the specified
letter combination.
Policy name
128 characters
Password for a login profile
1 to 128 characters
362
AWS Identity and Access Management User Guide
AWS Services That Work with IAM
Description
Limit
Alias for an AWS account ID
3 to 63 characters
Role trust policy JSON text (the policy that
determines who is allowed to assume the role)
2,048 characters
Role session name
64 characters
For inline policies (p. 235)
You can add as many inline policies as you want
to an IAM user, role, or group, but the total
aggregate policy size (the sum size of all inline
policies) per entity cannot exceed the following
limits:
• User policy size cannot exceed 2,048 characters
• Role policy size cannot exceed 10,240
characters
• Group policy size cannot exceed 5,120
characters
Note
IAM does not count whitespace when
calculating the size of a policy against
these limitations.
For managed policies (p. 235)
• You can add up to 10 managed policies to an
IAM user, role, or group.
• The size of each managed policy cannot exceed
6,144 characters.
Note
IAM does not count whitespace when
calculating the size of a policy against
this limitation.
AWS Services That Work with IAM
Many AWS services are integrated with AWS Identity and Access Management. The following tables
group these services by category and show the IAM permission types that each service supports, tips to
help you write policies to control service access, and links to related information.
Specifically, each table provides the following information:
• Action-level permissions. The service supports specifying individual actions in a policy's Action
element (p. 381). If the service does not support action-level permissions, policies for the service use
* in the Action element. For a list of all of the permissions for the AWS services can be used in IAM
policies, see AWS Service Actions and Condition Context Keys for Use in IAM Policies (p. 430).
• Resource-level permissions. The service has one or more APIs that support specifying individual
resources (using ARNs) in the policy's Resource element (p. 383). If an API does not support resourcelevel permissions, then that statement in the policy must use * in the Resource element. See the
footnotes after each table for more information.
• Resource-based permissions. The service enables you to attach resource-based policies to the
service's resources. Resource-based policies include a Principal element to specify an IAM identity
363
AWS Identity and Access Management User Guide
Compute Services
that can access that resource. Identity-based ( IAM) permissions are different. They are attached
to users, groups, or roles and include a Resource element to specify the resource that can be
accessed by the identity. For more details, see Identity-Based (IAM) Permissions and Resource-Based
Permissions (p. 223).
• Tag-based permissions. The service supports testing resource tags in a Condition element (p. 385).
• Temporary security credentials. The service lets users make requests using temporary security
credentials that are obtained by calling AWS STS APIs like AssumeRole or GetFederationToken.
Temporary credentials are commonly used in federation scenarios (p. 105). For more information, see
Temporary Security Credentials (p. 193).
• Service-linked roles. The service requires that you use a unique type of service role (p. 98) that is
linked directly to the service. This service-linked role (p. 99) is predefined by the service, and includes
all the permissions that the service requires. To learn how to create a role used to delegate permissions
to a service, see Creating a Role to Delegate Permissions to an AWS Service (p. 153).
• More information. Links to more information in the documentation of the product.
Compute Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon
Elastic
Compute
Cloud
(Amazon
EC2)
Yes
Yes¹
No
Yes¹
Yes
No
Amazon EC2
Container
Registry
(Amazon
ECR)
Yes
Yes
No
No
Yes
No
Amazon EC2
Container
Service
(Amazon
ECS)
Yes
Yes²
No
No
Yes
No
AWS Elastic
Beanstalk
Yes
Yes³
No
No
Yes
Yes
AWS
Lambda
Yes
Yes
Yes⁴
No
Yes
No
Amazon
Lightsail
Yes
No
No
No
Yes
No
Auto Scaling
Yes
Yes
No
No
Yes
No
Application
Auto Scaling
Yes
No
No
No
Yes
No
364
AWS Identity and Access Management User Guide
Storage and Content Delivery Services
Elastic Load
Balancing
Yes
Yes⁵
No
No
Yes
No
¹ Amazon EC2 supports resource-level permissions and tags only for some APIs. For more information,
see Supported Resources and Conditions for Amazon EC2 API Actions in the Amazon EC2 User Guide for
Linux Instances.
² Amazon ECS supports resource-level permissions only for some APIs. For more information, see
Supported Resource-Level Permissions for Amazon ECS API Actions in the Amazon EC2 Container Service
Developer Guide.
³ Only some API actions for Elastic Beanstalk can be used as permissions against specific resources.
For more information, see Resources and Conditions for Elastic Beanstalk Actions in the AWS Elastic
Beanstalk Developer Guide.
⁴ The only AWS Lambda API action that can be specified in a resource-based policy is
lambda:InvokeFunction. For more information, see Using Resource-Based Policies for AWS Lambda
(Lambda Function Policies) in the AWS Lambda Developer Guide.
⁵ Only some API actions for Elastic Load Balancing can be used as permissions against specific resources.
For more information, see Control Access to Your Load Balancer in the Elastic Load Balancing User Guide.
Storage and Content Delivery Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon
Simple
Storage
Service
(Amazon S3)
Yes
Yes
Yes
Yes
Yes
No
Amazon
Elastic
Block Store
(Amazon
EBS)
Yes
Yes¹
No
Yes
Yes
No
Amazon EFS
Yes
Yes
No
No
Yes
No
Amazon
Glacier
Yes
Yes
Yes
Yes
Yes
No
AWS
Snowball
and AWS
Snowball
Edge
Yes
No
No
No
Yes
No
AWS
Storage
Gateway
Yes
Yes
No
No
Yes
No
365
AWS Identity and Access Management User Guide
Database Services
¹ For information about which EBS actions support resource-level permissions, see Supported Resources
and Conditions for Amazon EC2 API Actions in the Amazon EC2 User Guide for Linux Instances.
Database Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon
Relational
Database
Service
(Amazon
RDS)
Yes
Yes
No
Yes
Yes
No
Amazon
DynamoDB
Yes
Yes
No
No
Yes
No
Amazon
ElastiCache
Yes
No
No
No
Yes
No
Amazon
Redshift
Yes
Yes
No
No
Yes
No
Amazon
SimpleDB
Yes
Yes
No
No
Yes
No
Networking and Content Delivery Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon
Virtual
Private
Cloud
(Amazon
VPC)
Yes
Yes¹
Yes²
Yes
Yes
No
Amazon
CloudFront
Yes³
No
No
No
Yes
No
AWS Direct
Connect
Yes
No
No
No
Yes
No
Amazon
Route 53
Yes
Yes
No
No
Yes
No
¹ In an IAM user policy, you cannot restrict permissions to a specific Amazon VPC endpoint. Any Action
element that includes the ec2:*VpcEndpoint* or ec2:DescribePrefixLists API actions must specify
366
AWS Identity and Access Management User Guide
Migration Services
""Resource": "*"". For more information, see Controlling the Use of Endpoints in the Amazon VPC User
Guide.
² Amazon VPC supports attaching a single resource policy to a VPC endpoint to restrict what can be
accessed through that endpoint. For more information about using resource-based policies to control
access to resources from specific Amazon VPC endpoints, see Using Endpoint Policies in the Amazon VPC
User Guide.
Migration Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
AWS
Import/
Export
Yes
No
No
No
Yes
No
Developer Tools and Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
AWS
CodeCommit
Yes
Yes
No
No
Yes
No
AWS
CodeBuild
Yes
Yes
No
No
Yes
No
AWS
CodeDeploy
Yes
Yes
No
No
Yes
No
AWS
CodePipeline
Yes
Yes¹
No
No
Yes
No
AWS
CodeStar
Yes
Yes¹
No
No
No
No
¹ Only some API actions for AWS CodePipeline can be used as permissions against specific resources. For
more information, see AWS CodePipeline Resources and Operations in the AWS CodePipeline User Guide.
Management Tools and Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon
CloudWatch
Yes
No
No
No
Yes
No
367
AWS Identity and Access Management User Guide
Security, Identity, and Compliance Services
Amazon
CloudWatch
Events
Yes
Yes
No
No
Yes
No
Amazon
CloudWatch
Logs
Yes
Yes
No
No
Yes
No
AWS
CloudFormation
Yes
Yes
No
No
Yes
No
AWS
CloudTrail
Yes
Yes
No
No
Yes
No
AWS Config
Yes
No
No
No
Yes
No
AWS
OpsWorks
for Chef
Automate
Yes
Yes
Yes
No
Yes
No
AWS
OpsWorks
Yes
Yes
Yes
No
Yes
No
AWS Service
Catalog
Yes
No
No
No
Yes
No
AWS Trusted
Advisor
Yes¹
Yes
No
No
Yes¹
No
AWS Health
Yes
No
No
No
Yes
No
¹ API access to Trusted Advisor is through the AWS Support API and is controlled by AWS Support IAM
policies.
Security, Identity, and Compliance Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
AWS Artifact
Yes
Yes
No
No
Yes
No
AWS
Certificate
Manager
(ACM)
Yes
Yes
No
No
Yes
No
AWS
CloudHSM
Yes
Yes
No
No
Yes
No
AWS
CloudHSM
Classic
Yes
No
No
No
No
No
368
AWS Identity and Access Management User Guide
Analytics Services
AWS
Directory
Service
Yes
No
No
No
Yes
No
AWS
Identity
and Access
Management
(IAM)
Yes
Yes
No
No
Yes¹
No
Amazon
Inspector
Yes
No
No
No
Yes¹
No
AWS Key
Management
Service
(AWS KMS)
Yes
Yes
Yes
No
Yes
No
AWS
Organizations
Yes
Yes
No
No
Yes
No
AWS Shield
Advanced
Yes
No
No
No
Yes
No
AWS
Security
Token
Service
(AWS STS)
Yes
Yes²
No
No
Yes²
No
AWS WAF
Yes
Yes
No
No
Yes
No
¹ Only some of the API actions for IAM can be called with temporary credentials. For more information,
see Comparing your API options
² AWS STS does not have "resources," but does allow restricting access in a similar way to users. For more
information, see Denying Access to Temporary Security Credentials by Name. Only some of the APIs for
AWS STS support calling with temporary credentials. For more information, see Comparing your API
options.
Analytics Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon
EMR
Yes
No
No
Yes
Yes
No
Amazon
CloudSearch
Yes
Yes
No
No
Yes
No
Amazon
Elasticsearch
Service
Yes
Yes
Yes
No
Yes
No
369
AWS Identity and Access Management User Guide
Artificial Intelligence
Amazon
Kinesis
Streams
Yes
Yes
No
No
Yes
No
Amazon
Kinesis
Analytics
Yes
Yes
No
No
Yes
No
Amazon
Kinesis
Firehose
Yes
Yes
No
No
Yes
No
AWS Data
Pipeline
Yes
No
No
Yes
Yes
No
Artificial Intelligence
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon Lex
Yes
Yes
No
No
Yes
Yes¹
Amazon
Machine
Learning
Yes
Yes
No
No
Yes
No
Amazon
Polly
Yes
Yes
No
No
Yes
No
¹This service-linked role cannot be deleted using IAM. To learn how to delete the role, see Deleting
Service-Linked Roles in the Amazon Lex Developer Guide.
Internet of Things
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
AWS IoT
Yes¹
Yes²
Yes³
No
Yes
No
AWS
Greengrass
Yes¹
Yes²
Yes³
No
Yes
No
¹ For more information about AWS IoT action-level permissions, see AWS IoT Policy Actions in the AWS
IoT User Guide.
² For information about which AWS IoT actions support resource-level permissions and which resources
you can specify for each, see Action Resources in the AWS IoT Developer Guide.
370
AWS Identity and Access Management User Guide
Game Development Services
³ Devices connected to AWS IoT are authenticated by using X.509 certificates. You can attach AWS IoT
policies to an X.509 certificate to control what the device is authorized to do. For more information, see
Create an AWS IoT Policy in the AWS IoT Developer Guide.
Game Development Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon
GameLift
Yes
No
No
No
Yes
No
Mobile Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon
Cognito
Yes
Yes
No
No
Yes
No
AWS Device
Farm
Yes
No
No
No
Yes
No
Amazon
Mobile
Analytics
Yes
No
No
No
Yes
No
Amazon
Pinpoint
Yes
Yes
No
No
Yes
No
Application Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon API
Gateway
Yes
Yes
No
No
Yes
No
Amazon
Elastic
Transcoder
Yes
Yes
No
No
Yes
No
Amazon
Simple
Workflow
Yes
Yes
No
Yes
Yes
No
371
AWS Identity and Access Management User Guide
Messaging Services
Service
(Amazon
SWF)
Messaging Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon
Simple
Notification
Service
(Amazon
SNS)
Yes
Yes
Yes
No
Yes
No
Amazon
Simple
Email
Service
(Amazon
SES)
Yes
Yes¹
No
No
Yes²
No
Amazon
Simple
Queue
Service
(Amazon
SQS)
Yes
Yes
Yes
No
Yes
No
¹ Amazon SES supports resource-level permissions in policies that grant permissions to delegate senders
to access specific SES identities.
² Only the Amazon SES API supports temporary security credentials. The Amazon SES SMTP interface
does not support SMTP credentials that are derived from temporary security credentials.
Business Productivity
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon
WorkDocs
Yes
No
No
No
Yes
No
Amazon
WorkMail
Yes
No
No
No
Yes
No
372
AWS Identity and Access Management User Guide
Desktop and App Streaming Services
Desktop and App Streaming Services
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
Amazon
WorkSpaces
Yes
Yes
No
No
Yes
No
Amazon
WAM
Yes
No
No
No
Yes
No
Amazon
AppStream
Yes
No
No
No
Yes
No
Amazon
AppStream
2.0
Yes
No
No
No
Yes
No
Additional Resources
Supports the following permissions
Service and
Related
IAM Info
Action Level
Resource
Level
Resource
Based
Tag Based
Temporary
Credentials
ServiceLinked Role
AWS Billing
and Cost
Management
Yes
No
No
No
Yes
No
AWS
Marketplace
Yes
Yes
No
No
Yes
No
AWS
Support
No
No
No
No
Yes
No
AWS Trusted
Advisor
Yes¹
Yes
No
No
Yes¹
No
AWS IAM Policy Reference
This section presents detailed syntax, descriptions, and examples of the elements, variables, and
evaluation logic of IAM policies. It includes the following sections.
• IAM Policy Elements Reference (p. 374) — Learn more about the elements that you can use when you
create a policy. View additional policy examples and learn about conditions, supported data types, and
how they are used in various services.
• IAM Policy Variables Overview (p. 395) — This section describes placeholders that you can specify in
a policy that are replaced during policy evaluation with values from the request.
• Creating a Condition That Tests Multiple Key Values (Set Operations) (p. 401) — This section
describes how to create policies for requests in which a request key includes multiple items that you
need to test against a set of values.
373
AWS Identity and Access Management User Guide
Element Reference
• IAM Policy Evaluation Logic (p. 405) — This section describes AWS requests, how they are
authenticated, and how AWS uses policies to determine access to resources.
• Grammar of the IAM Policy Language (p. 410) — This section presents a formal grammar for the
language used to create policies in IAM.
• AWS Managed Policies for Job Functions (p. 415) — This section lists all of the AWS managed
policies that directly map to common job functions in the IT industry. Use these policies to grant
the permissions needed to carry out the tasks expected of someone in a specific job function. These
policies consolidate permissions for many services into a single policy.
• AWS Service Actions and Condition Context Keys for Use in IAM Policies (p. 430) — This section
presents a list of all of the AWS API actions that can be used as permissions in an IAM policy and the
service-specific condition keys that can be used to further refine the request.
• AWS IAM Policy Actions Grouped by Access Level (p. 529) — This section presents a list the access
levels that all AWS API actions are members of. Each API action that can be used as a policy permission
is categorized into one access level.
Important
You cannot save any policy that does not comply with the established policy syntax. You can
use Policy Validator to detect and correct invalid policies. One click takes you to an editor
that shows both the existing policy and a copy with the recommended changes. You can
accept the changes or make further modifications. For more information, see Using Policy
Validator (p. 292).
IAM Policy Elements Reference
An IAM policy is made up of elements. The elements are listed here in the general order you use them in
a policy. The order of the elements doesn't matter—for example, the Resource element can come before
the Action element. You're not required to specify any Condition elements in the policy.
Topics
• Version (p. 375)
• Id (p. 375)
• Statement (p. 375)
• Sid (p. 376)
• Effect (p. 376)
• Principal (p. 377)
• NotPrincipal (p. 380)
• Action (p. 381)
• NotAction (p. 382)
• Resource (p. 383)
• NotResource (p. 384)
• Condition (p. 385)
• Supported Data Types (p. 394)
Note
The details of what goes into a policy vary for each service, depending on what actions the
service makes available, what types of resources it contains, and so on. When you're writing
policies for a specific service, it's helpful to see examples of policies for that service. For a list
of all the services that support IAM, and for links to the documentation in those services that
discusses IAM and policies, see AWS Services That Work with IAM (p. 363).
374
AWS Identity and Access Management User Guide
Element Reference
Version
A Version policy element is different from a policy version. The Version policy element is used within
a policy and defines the version of the policy language. A policy version, on the other hand, is created
when you make changes to a customer managed policy in IAM. The changed policy doesn't overwrite
the existing policy. Instead, IAM creates a new version of the managed policy. To learn more about the
Version policy element see the section called “Version” (p. 375). To learn more about policy versions,
see the section called “Versioning for Managed Policies” (p. 240).
The Version element must appear before the Statement element. The only allowed values are these:
• 2012-10-17. This is the current version of the policy language, and you should use this version number
for all policies.
• 2008-10-17. This was an earlier version of the policy language. You might see this version on existing
policies. Do not use this version for any new policies or any existing policies that you are updating.
If you do not include a Version element, the value defaults to 2008-10-17. However, it is a good practice
to always include a Version element and set it to 2012-10-17.
Note
If your policy uses any features that were introduced in a later version, such as policy
variables (p. 395), you must include a Version element and set it to 2012-10-17. If you
don't include a Version element set to 2012-10-17, variables such as ${aws:username} aren't
recognized as variables and are instead treated as literal strings in the policy.
"Version": "2012-10-17"
Id
The Id element specifies an optional identifier for the policy. The ID is used differently in different
services.
For services that let you set an ID element, we recommend you use a UUID (GUID) for the value, or
incorporate a UUID as part of the ID to ensure uniqueness.
"Id": "cd3ad3d9-2776-4ef1-a904-4c229d1642ee"
Note
Some AWS services (for example, Amazon SQS or Amazon SNS) might require this element and
have uniqueness requirements for it. For service-specific information about writing policies,
refer to the documentation for the service you're working with.
Statement
The Statement element is the main element for a policy. This element is required. It can include multiple
elements (see the subsequent sections in this page). The Statement element contains an array of
individual statements. Each individual statement is a JSON block enclosed in braces { }.
"Statement": [{...},{...},{...}]
The following example shows a policy that contains an array of three statements inside a single
Statement element. (The policy allows you to access your own "home folder" in the Amazon S3 console.)
The policy includes the aws:username variable, which is replaced during policy evaluation with the user
name from the request. For more information, see Introduction (p. 395).
375
AWS Identity and Access Management User Guide
Element Reference
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets",
"s3:GetBucketLocation"
],
"Resource": "arn:aws-cn:s3:::*"
},
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws-cn:s3:::BUCKET-NAME",
"Condition": {"StringLike": {"s3:prefix": [
"",
"home/",
"home/${aws:username}/"
]}}
},
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": [
"arn:aws-cn:s3:::BUCKET-NAME/home/${aws:username}",
"arn:aws-cn:s3:::BUCKET-NAME/home/${aws:username}/*"
]
}
]
Sid
The Sid (statement ID) is an optional identifier that you provide for the policy statement. You can assign
a Sid value to each statement in a statement array. In services that let you specify an ID element, such
as SQS and SNS, the Sid value is just a sub-ID of the policy document's ID. In IAM, the Sid value must be
unique within a policy.
"Sid": "1"
In IAM, the Sid is not exposed in the IAM API. You can't retrieve a particular statement based on this ID.
Note
Some AWS services (for example, Amazon SQS or Amazon SNS) might require this element and
have uniqueness requirements for it. For service-specific information about writing policies,
refer to the documentation for the service you're working with.
Effect
The Effect element is required and specifies whether the statement results in an allow or an explicit
deny. Valid values for Effect are Allow and Deny.
"Effect":"Allow"
By default, access to resources is denied. To allow access to a resource, you must set the Effect element
to Allow. To override an allow (for example, to override an allow that is otherwise in force), you set the
Effect element to Deny. For more information, see IAM Policy Evaluation Logic (p. 405).
376
AWS Identity and Access Management User Guide
Element Reference
Principal
Use the Principal element to specify the user (IAM user, federated user, or assumed-role user), AWS
account, AWS service, or other principal entity that is allowed or denied access to a resource. You use the
Principal element in the trust policies for IAM roles and in resource-based policies—that is, in policies
that you embed directly in a resource. For example, you can embed such policies in an Amazon S3
bucket, an Amazon Glacier vault, an Amazon SNS topic, an Amazon SQS queue, or an AWS KMS customer
master key (CMK).
Use the Principal element in these ways:
• In IAM roles, use the Principal element in the role's trust policy to specify who can assume the role.
For cross-account access, you typically specify the identifier of the trusted account.
Note
You cannot specify anything other than a 12-digit