Menu
AWS Identity and Access Management
User Guide

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 to obtain 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 to help 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.

For information about how to use roles to delegate permissions, see Roles Terms and Concepts.

Creating a Role (AWS Management Console)

You can use the AWS Management Console to create a role that an IAM user can switch to.

To create a role (AWS Management Console)

  1. Sign in to the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane of the console, click Roles and then click Create New Role.

  3. For Role name, type a role name to help identify the purpose of this role. Role names must be unique within your AWS account. After you enter the name, click Next Step.

    Role names have character limitations. The number of roles in an AWS account and the policy size for policies attached to roles are also limited. For more information, see Limitations on IAM Entities and Objects. Note that you cannot edit the name of the role after it is created.

    Important

    Role names must be unique within an account. They are not distinguished by case, for example, you cannot create roles named both "PRODROLE" and "prodrole".

  4. On the Select Role Type page, select the Role for Cross-Account Access section, and then select the type of role that you want to create:

    • Select Provide access between AWS accounts you own if you are the administrator of both the user account and the resource account, or both accounts belong to the same company. This is also the option to select when the users, role, and resource to be accessed are all in the same account.

    • Select Allows IAM users from a 3rd party AWS account to access this account if you are the administrator of the account that owns the resource and you want to grant permissions to users from an account that you do not control. This option requires you to specify an external ID (which the third party must provide to you) to provide additional control over the circumstances in which the third party can use the role to access your resources. For more information, see How to Use an External ID When Granting Access to Your AWS Resources to a Third Party.

      Important

      Selecting this option enables 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.

  5. On the next page, specify the AWS account ID to which you want to grant access to your resources.

    The administrator of the specified trusted account can grant permission to assume this role to any IAM user in the trusted account. To do this, the administrator attaches a policy to the user or a group that grants permission for the sts:AssumeRole action and that specifies the role's ARN as the Resource.

  6. If you selected Allows IAM users from a 3rd party AWS account to access this account on the Select Role Type page, type the external ID provided by the administrator of the third party account. This 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.

  7. If you want to restrict the role to users who sign in by using multi-factor authentication (MFA) device, select the Require MFA option. This adds a condition to the role's trust policy that checks for an MFA sign-in. A user who wants to assume the role must sign in with a temporary one-time password from a configured MFA device. Users without MFA authentication cannot assume the role. For more information about MFA, see Using Multi-Factor Authentication (MFA) in AWS

  8. Click Next Step.

  9. On the Attach Policy page, select one or more permissions policies to attach to the role to specify what actions can be done on specific resources (similar to setting permissions for IAM groups). For information about managing permissions by using policies, see Overview of AWS IAM Permissions.

    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, and then click Attach Policy. You can choose to select no policies at this time, create the policies later, and then attach them to the role.

  10. Click Next Step to review the role settings. Note the link provided for you to give to users who can use the role. When the user clicks this link, the user is taken directly to the Switch Role page with the Account ID and Role Name already filled in. The user is asked for credentials if he or she is not already signed in. The user can optionally set a Display Name and can select a Display Color. When the user clicks Switch Role, the user immediately begins operating with the new permissions.

    Note

    For later easy selection, the IAM console caches the last five roles that you use. If your users need more than five roles, consider the following solutions for easy access:

    • If only a small number of users switch roles, recommend that they bookmark the links that you send them.

    • If many users switch roles, consider creating a central location like a web page that contains all the links that users need to access.

    The format of the link is as follows:

    https://signin.aws.amazon.com/switchrole?account=ACCOUNT_NUMBER&roleName=ROLE_NAME&displayName=DISPLAYNAME

  11. Click Create Role to complete the creation of the role.

    Important

    Remember that this is only the first half of the configuration required. You must also enable individual users in the trusted account with permissions to switch to the role. For more information about this step, see Granting a User Permissions to Switch Roles.

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 a Role (AWS Management Console).

Creating a Role (AWS Command Line Interface)

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)

Use the following commands:

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 , but only if the user provides MFA authentication. For more information about MFA, see Using Multi-Factor Authentication (MFA) in AWS.

Copy
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:root" }, "Action": "sts:AssumeRole", "Condition": { "Bool": { "aws:MultiFactorAuthPresent": "true" } } } }

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 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.

The managed policy referenced in the second command is assumed to already exists in IAM and 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:

Copy
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::example_bucket" } }

The commands to run are the following:

Copy
# 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:aws:iam::123456789012:role/PolicyForRole

Important

Remember that this is only the first half of the configuration required. You must also enable individual users in the trusted account with permissions to switch to the role. For more information about this step, see Granting a User Permissions to Switch Roles.

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).

Creating a Role (Tools for Windows PowerShell)

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 Windows PowerShell cmdlets you must explicitly perform each step yourself. You must create the policy, and assign an access policy to the role.

To create a role for cross-account access (Tools for Windows PowerShell)

Use the following commands:

The following example shows both steps in a simple environment. The example assumes that you have already configured your Tools for Windows PowerShell with your account credentials and region. For more information, see Using AWS Credentials in the AWS Tools for Windows PowerShell User Guide.

The sample trust policy file referenced in the first command contains the following JSON code to enable users in the account 123456789012 to assume the role, but only if the user provides MFA authentication. For more information about MFA, see Using Multi-Factor Authentication (MFA) in AWS.

Copy
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:root" }, "Action": "sts:AssumeRole", "Condition": { "Bool": { "aws:MultiFactorAuthPresent": "true" } } } }

The managed policy referenced in the second command is assumed to already exists in IAM and 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:

Copy
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::example_bucket" } }

The commands to run are the following:

Copy
# Create the role and attach the trust policy that allows users in an account to switch to the role. New-IAMRole -RoleName Test-UserAccess-Role -AssumeRolePolicyDocument (Get-Content -raw 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. Register-IAMRolePolicy -RoleName Test-UserAccess-Role --policy-arn arn:aws:iam::123456789012:role/PolicyForRole

Important

Remember that this is only the first half of the configuration required. You must also enable individual users in the trusted account with permissions to switch to the role. For more information about this step, see Granting a User Permissions to Switch Roles.

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 (Tools for Windows PowerShell).

Creating a 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 using the API

Use the following commands:

  • 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

    -or-

    Create an inline access policy for the role: PutRolePolicy

Important

Remember that this is only the first half of the configuration required. You must also enable individual users in the trusted account with permissions to switch to the role. For more information about this step, see Granting a User Permissions to Switch Roles.

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).

For more information about MFA, see Using Multi-Factor Authentication (MFA) in AWS.

On this page:

  • Creating a Role (AWS Management Console)
  • Creating a Role (AWS Command Line Interface)
  • Creating a Role (Tools for Windows PowerShell)
  • Creating a Role (AWS API)
  • How to Use an External ID When Granting Access to Your AWS Resources to a Third PartyUsing an External ID for Third-Party Access Add an external ID to an IAM policy in order to add security for delegating AWS access to third parties. 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. 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. For more information about the AssumeRole and other AWS APIs that you can call to obtain temporary security credentials, see . Here's a more detailed breakdown of this scenario: 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. 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. 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"}} 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. After you create the role, you provide the Amazon Resource Name (ARN) of the role to Example Corp. 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.
  • Why Do You Need to Use an External ID?
  • When Should I Use the External ID?