# IAM role creation
Role creation
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 SAML or OIDC federated principal.
**Roles for IAM users**
Create this role to delegate permissions within your AWS account or to roles defined in other AWS accounts that you own. 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.
For more information, see [Create a role to give permissions to an IAM user](id_roles_create_for-user.md).
For more information about creating roles for cross account access, see [Create a role using custom trust policies](id_roles_create_for-custom.md).
**Roles for AWS services**
Create this role to delegate permissions to a service that can perform actions on your behalf. A [service role](id_roles.md#iam-term-service-role) that you pass to a service must have an IAM policy with the permissions that allow the service to perform actions associated with that service. Different permissions are required for each AWS service.
For more information about creating service roles, see [Create a role to delegate permissions to an AWS service](id_roles_create_for-service.md).
For more information about creating service-linked roles, see [Create a service-linked role](id_roles_create-service-linked-role.md).
**Roles for identity federation**
Create this role to delegate permissions to users that already have identities outside of AWS. When you use an identity provider, you don't have to create custom sign-in code or manage your own user identities. Your external users sign in through an IdP, and 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 access keys, in your application.
For more information, see [Create a role for a third-party identity provider](id_roles_create_for-idp.md).
# Create a role to give permissions to an IAM user
Create a role for an IAM user
You can use IAM roles to provide 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. However, it is possible for another account to own a resource in your account. For example, the trusting account might allow the trusted account to create new resources, such as creating new objects in an Amazon S3 bucket. In that case, the account that creates the resource owns the resource and controls who can access that 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) [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API operation. This operation 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 an AWS account that you do not control, then you can use the `externalId` attribute. 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 [Access to AWS accounts owned by third parties](id_roles_common-scenarios_third-party.md).
For information about how to use roles to delegate permissions, see [Roles terms and concepts](id_roles.md#id_roles_terms-and-concepts). For information about using a service role to allow services to access resources in your account, see [Create a role to delegate permissions to an AWS service](id_roles_create_for-service.md).
## Creating an IAM role (console)
You can use the AWS Management Console to create a role that an IAM user can assume. For example, assume that your organization has multiple AWS accounts to isolate a development environment from a production environment. For high-level information about creating 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](id_roles_common-scenarios_aws-accounts.md#id_roles_common-scenarios_aws-accounts-example).
**Minimum permissions**
To perform the following steps, you must have at least the following IAM permissions:
`access-analyzer:ValidatePolicy`
`iam:AttachRolePolicy`
`iam:CreatePolicy`
`iam:CreateRole`
`iam:GetAccountSummary`
`iam:GetPolicy`
`iam:GetPolicyVersion`
`iam:GetRole`
`iam:ListAccountAliases`
`iam:ListAttachedRolePolicies`
`iam:ListOpenIDConnectProviders`
`iam:ListPolicies`
`iam:ListRolePolicies`
`iam:ListRoles`
`iam:ListRoleTags`
`iam:ListSAMLProviders`
------
#### [ Console ]
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane of the console, choose **Roles** and then choose **Create role**.
1. Choose **AWS account** role type.
1. To create a role for your account, choose **This account**. To create a role for another account, choose **Another AWS account** and enter the **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`.
1. If you are granting permissions to users from an account that you do not control, and the users will assume this role programmatically, 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 [Access to AWS accounts owned by third parties](id_roles_common-scenarios_third-party.md).
**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](https://aws.amazon.com/blogs/security/how-to-enable-cross-account-access-to-the-aws-management-console) in the AWS Security Blog.
1. If you want to restrict the role to users who sign in with multi-factor authentication (MFA), select **Require MFA**. 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 [AWS Multi-factor authentication in IAM](id_credentials_mfa.md)
1. Choose **Next**.
1. IAM includes a list of the AWS managed and customer managed policies in your account. Select the policy to use for the permissions policy or choose **Create policy** to open a new browser tab and create a new policy from scratch. For more information, see [Creating IAM policies](access_policies_create-console.md#access_policies_create-start). After you create the policy, close that tab and return to your original tab. Select the checkbox next to the permissions policies that you want anyone who assumes the role to have. If you prefer, you can select no policies at this time, and then attach policies to the role later. By default, a role has no permissions.
1. (Optional) Set a [permissions boundary](access_policies_boundaries.md). This is an advanced feature.
Open the **Set permissions boundary** section and choose **Use a permissions boundary to control the maximum role permissions**. Select the policy to use for the permissions boundary.
1. Choose **Next**.
1. For **Role name**, enter a name for your role. Role names must be unique within your AWS account. When a role name is used in a policy or as part of an ARN, the role name is case sensitive. When a role name appears to customers in the console, such as during the sign-in process, the role name is case insensitive. Because various entities might reference the role, you can't edit the name of the role after it is created.
1. (Optional) For **Description**, enter a description for the new role.
1. Choose **Edit** in the **Step 1: Select trusted entities** or **Step 2: Add permissions** sections to edit the use cases and permissions for the role. You will be returned to previous pages to make the edits.
1. (Optional) Add metadata to the role by attaching tags as key–value pairs. For more information about using tags in IAM, see [Tags for AWS Identity and Access Management resources](id_tags.md).
1. Review the role and then choose **Create role**.
**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 in the console, or assume the role programmatically. For more information about this step, see [Grant a user permissions to switch roles](id_roles_use_permissions-to-switch.md).
------
## 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 role and then assign a permissions policy to the role. Optionally, you can also set the [permissions boundary](access_policies_boundaries.md) for your role.
**To create a role for cross-account access (AWS CLI)**
1. Create a role: [aws iam create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html)
1. Attach a managed permissions policy to the role: [aws iam attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html)
or
Create an inline permissions policy for the role: [aws iam put-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-policy.html)
1. (Optional) Add custom attributes to the role by attaching tags: [aws iam tag-role](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-role.html)
For more information, see [Managing tags on IAM roles (AWS CLI or AWS API)](id_tags_roles.md#id_tags_roles_procs-cli-api).
1. (Optional) Set the [permissions boundary](access_policies_boundaries.md) for the role: [aws iam put-role-permissions-boundary](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-permissions-boundary.html)
A permissions boundary controls the maximum permissions that a role can have. Permissions boundaries are an advanced AWS feature.
The following example shows the first two, and most common steps for creating a cross-account role in a simple environment. This example allows any user in the `123456789012` account to assume the role and view the `example_bucket` Amazon S3 bucket. This example also 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html).
In this example, include the following trust policy in the first command when you create the role. This trust policy allows users in the `123456789012` account to assume the role using the `AssumeRole` operation, but only if the user provides MFA authentication using the `SerialNumber` and `TokenCode` parameters. For more information about MFA, see [AWS Multi-factor authentication in IAM](id_credentials_mfa.md).
------
#### [ JSON ]
****
```
{
"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 the ARN for 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 permissions 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 principal ID appears in the console because AWS can no longer map it back to an ARN. Therefore, 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.
When you use the second command, you must attach an existing managed policy to the role. The following permissions policy allows anyone who assumes the role to perform only the `ListBucket` action on the `example_bucket` Amazon S3 bucket.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::example_bucket"
}
]
}
```
------
To create this `Test-UserAccess-Role` role, you must first save the previous trust policy with the name `trustpolicyforacct123456789012.json` to the `policies` folder in your local `C:` drive. Then save the previous permissions policy as a customer managed policy in your AWS account with the name `PolicyForRole`. You can then use the following commands to create the role and attach the managed policy.
```
# Create the role and attach the trust policy file that allows users in the specified account to assume 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:policy/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 [Grant a user permissions to switch roles](id_roles_use_permissions-to-switch.md).
After you create the role and grant it permissions to perform AWS tasks or access AWS resources, any users in the `123456789012` account can assume the role. For more information, see [Switch to an IAM role (AWS CLI)](id_roles_use_switch-role-cli.md).
## Creating an IAM role (AWS API)
Creating a role from the AWS API involves multiple steps. When you use the console to create a role, many of the steps are done for you, but with the API you must explicitly perform each step yourself. You must create the role and then assign a permissions policy to the role. Optionally, you can also set the [permissions boundary](access_policies_boundaries.md) for your role.
**To create a role in code (AWS API)**
1. Create a role: [CreateRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html)
For the role's trust policy, you can specify a file location.
1. Attach a managed permission policy to the role: [AttachRolePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_AttachRolePolicy.html)
or
Create an inline permission policy for the role: [PutRolePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_PutRolePolicy.html)
**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 [Grant a user permissions to switch roles](id_roles_use_permissions-to-switch.md).
1. (Optional) Add custom attributes to the user by attaching tags: [TagRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagRole.html)
For more information, see [Managing tags on IAM users (AWS CLI or AWS API)](id_tags_users.md#id_tags_users_procs-cli-api).
1. (Optional) Set the [permissions boundary](access_policies_boundaries.md) for the role: [PutRolePermissionsBoundary](https://docs.aws.amazon.com/IAM/latest/APIReference/API_PutRolePermissionsBoundary.html)
A permissions boundary controls the maximum permissions that a role can have. Permissions boundaries are an advanced AWS feature.
After you create the role and grant it permissions to perform AWS tasks or access AWS resources, you must grant permissions to users in the account to allow them to assume the role. For more information about assuming a role, see [Switch to an IAM role (AWS API)](id_roles_use_switch-role-api.md).
## Creating an IAM role (AWS CloudFormation)
For information about creating an IAM role in AWS CloudFormation, see the [resource and property reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html) and [examples](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html#aws-resource-iam-role--examples) in the *AWS CloudFormation User Guide*.
For more information about IAM templates in AWS CloudFormation, see [AWS Identity and Access Management template snippets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/quickref-iam.html) in the *AWS CloudFormation User Guide*.
# Create a role to delegate permissions to an AWS service
Create a role for an AWS service
Many AWS services require that you use roles to allow the service to access resources in other services on your behalf. A role that a service assumes to perform actions on your behalf is called a [service role](id_roles.md#iam-term-service-role). When a role serves a specialized purpose for a service, it is categorized as a [service-linked role](id_roles.md#iam-term-service-linked-role). To see what services support using service-linked roles, or whether a service supports any form of temporary credentials, see [AWS services that work with IAM](reference_aws-services-that-work-with-iam.md). To learn how an individual service uses roles, choose the service name in the table to view the documentation for that service.
When setting the `PassRole` permission, you should make sure that a user doesn’t pass a role where the role has more permissions than you want the user to have. For example, Alice might not be allowed to perform any Amazon S3 actions. If Alice could pass a role to a service that allows Amazon S3 actions, the service could perform Amazon S3 actions on behalf of Alice when executing the job.
For information about how roles help you to delegate permissions, see [Roles terms and concepts](id_roles.md#id_roles_terms-and-concepts).
## Service role permissions
You must configure permissions to allow an IAM entity (user or role) to create or edit a service role.
**Note**
The ARN for a service-linked role includes a service principal, which is indicated in the following policies as `SERVICE-NAME.amazonaws.com`. Do not try to guess the service principal, because it is case-sensitive and the format can vary across AWS services. To view the service principal for a service, see its service-linked role documentation.
**To allow an IAM entity to create a specific service role**
Add the following policy to the IAM entity that needs to create the service role. This policy allows you to create a service role for the specified service and with a specific name. You can then attach managed or inline policies to that role.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:CreateRole",
"iam:PutRolePolicy"
],
"Resource": "arn:aws:iam::*:role/SERVICE-ROLE-NAME"
}
]
}
```
------
**To allow an IAM entity to create any service role**
AWS recommends that you allow only administrative users to create any service role. A person with permissions to create a role and attach any policy can escalate their own permissions. Instead, create a policy that allows them to create only the roles that they need or have an administrator create the service role on their behalf.
To attach a policy that allows an administrator to access your entire AWS account, use the [AdministratorAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AdministratorAccess) AWS managed policy.
**To allow an IAM entity to edit a service role**
Add the following policy to the IAM entity that needs to edit the service role.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "EditSpecificServiceRole",
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:DeleteRolePolicy",
"iam:DetachRolePolicy",
"iam:GetRole",
"iam:GetRolePolicy",
"iam:ListAttachedRolePolicies",
"iam:ListRolePolicies",
"iam:PutRolePolicy",
"iam:UpdateRole",
"iam:UpdateRoleDescription"
],
"Resource": "arn:aws:iam::*:role/SERVICE-ROLE-NAME"
},
{
"Sid": "ViewRolesAndPolicies",
"Effect": "Allow",
"Action": [
"iam:GetPolicy",
"iam:ListRoles"
],
"Resource": "*"
}
]
}
```
------
**To allow an IAM entity to delete a specific service role**
Add the following statement to the permissions policy for the IAM entity that needs to delete the specified service role.
```
{
"Effect": "Allow",
"Action": "iam:DeleteRole",
"Resource": "arn:aws:iam::*:role/SERVICE-ROLE-NAME"
}
```
**To allow an IAM entity to delete any service role**
AWS recommends that you allow only administrative users to delete any service role. Instead, create a policy that allows them to delete only the roles that they need or have an administrator delete the service role on their behalf.
To attach a policy that allows an administrator to access your entire AWS account, use the [AdministratorAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AdministratorAccess) AWS managed policy.
## 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](https://docs.aws.amazon.com/) 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. The steps that you can use to control the permissions for your role can vary, depending on how the service defines the use cases, and whether or not you create a service-linked role.
------
#### [ Console ]
**To create a role for an AWS service (IAM console)**
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane of the IAM console, choose **Roles**, and then choose **Create role**.
1. For **Trusted entity type**, choose **AWS service**.
1. For **Service or use case**, choose a service, and then choose the use case. Use cases are defined by the service to include the trust policy that the service requires.
1. Choose **Next**.
1. For **Permissions policies**, the options depend on the use case that you selected:
+ If the service defines the permissions for the role, you can't select permissions policies.
+ Select from a limited set of permission polices.
+ Select from all permission policies.
+ Select no permissions policies, create the policies after the role is created, and then attach the policies to the role.
1. (Optional) Set a [permissions boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html). This is an advanced feature that is available for service roles, but not service-linked roles.
1. Open the **Set permissions boundary** section, and then choose **Use a permissions boundary to control the maximum role permissions**.
IAM includes a list of the AWS managed and customer-managed policies in your account.
1. Select the policy to use for the permissions boundary.
1. Choose **Next**.
1. For **Role name**, the options depend on the service:
+ If the service defines the role name, you can't edit the role name.
+ If the service defines a prefix for the role name, you can enter an optional suffix.
+ If the service doesn't define the role name, you can name the role.
**Important**
When you name a role, note the following:
Role names must be unique within your AWS account, and can't be made unique by case.
For example, don't create roles named both **PRODROLE** and **prodrole**. When a role name is used in a policy or as part of an ARN, the role name is case sensitive, however when a role name appears to customers in the console, such as during the sign-in process, the role name is case insensitive.
You can't edit the name of the role after it's created because other entities might reference the role.
1. (Optional) For **Description**, enter a description for the role.
1. (Optional) To edit the use cases and permissions for the role, in the **Step 1: Select trusted entities** or **Step 2: Add permissions** sections, choose **Edit**.
1. (Optional) To help identify, organize, or search for the role, add tags as key-value pairs. For more information about using tags in IAM, see [Tags for AWS Identity and Access Management resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) in the *IAM User Guide*.
1. 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 role and then assign a permissions 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. Optionally, you can also set the [permissions boundary](access_policies_boundaries.md) for your role.
**To create a role for an AWS service from the AWS CLI**
1. The following `[create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html)` command creates a role named *Test-Role* and attaches a trust policy to it:
`aws iam create-role --role-name Test-Role --assume-role-policy-document file://Test-Role-Trust-Policy.json`
1. Attach a managed permissions policy to the role: [aws iam attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html).
For example, the following `attach-role-policy` command attaches the AWS managed policy named `ReadOnlyAccess` to the IAM role named `ReadOnlyRole`:
`aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess --role-name ReadOnlyRole`
or
Create an inline permissions policy for the role: [aws iam put-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-policy.html)
To add an inline permissions policy, see the following example:
`aws iam put-role-policy --role-name Test-Role --policy-name ExamplePolicy --policy-document file://AdminPolicy.json`
1. (Optional) Add custom attributes to the role by attaching tags: [aws iam tag-role](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-role.html)
For more information, see [Managing tags on IAM roles (AWS CLI or AWS API)](id_tags_roles.md#id_tags_roles_procs-cli-api).
1. (Optional) Set the [permissions boundary](access_policies_boundaries.md) for the role: [aws iam put-role-permissions-boundary](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-permissions-boundary.html)
A permissions boundary controls the maximum permissions that a role can have. Permissions boundaries are an advanced AWS feature.
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 [Use instance profiles](id_roles_use_switch-role-ec2_instance-profiles.md). For information about how to launch an EC2 instance with a role, see [Controlling Access to Amazon EC2 Resources](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/UsingIAM.html#UsingIAMrolesWithAmazonEC2Instances) in the *Amazon EC2 User Guide*.
**To create an instance profile and store the role in it (AWS CLI)**
1. Create an instance profile: [aws iam create-instance-profile](https://docs.aws.amazon.com/cli/latest/reference/iam/create-instance-profile.html)
1. Add the role to the instance profile: [aws iam add-role-to-instance-profile](https://docs.aws.amazon.com/cli/latest/reference/iam/add-role-to-instance-profile.html)
The AWS CLI example command set below demonstrates the first two steps for creating a role and attaching permissions. It also shows the two steps for creating an instance profile and adding the role to the profile. This example trust policy allows the Amazon EC2 service to assume the role and view the `example_bucket` Amazon S3 bucket. The example also 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html).
In this example, include the following trust policy in the first command when you create the role. This trust policy allows the Amazon EC2 service to assume the role.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Principal": {"Service": "ec2.amazonaws.com"},
"Action": "sts:AssumeRole"
}
}
```
------
When you use the second command, you must attach a permissions policy to the role. The following example permissions policy allows the role to perform only the `ListBucket` action on the `example_bucket` Amazon S3 bucket.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::example_bucket"
}
}
```
------
To create this `Test-Role-for-EC2` role, you must first save the previous trust policy with the name `trustpolicyforec2.json` and the previous permissions policy with the name `permissionspolicyforec2.json` to the `policies` directory in your local `C:` drive. You can then use the following commands to create the role, attach the policy, create the instance profile, and add the role to the instance profile.
```
# Create the role and attach the trust policy that allows EC2 to assume this role.
$ aws iam create-role --role-name Test-Role-for-EC2 --assume-role-policy-document file://C:\policies\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-Policy-For-Ec2 --policy-document file://C:\policies\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 --role-name 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)
Creating a role from the AWS API involves multiple steps. When you use the console to create a role, many of the steps are done for you, but with the API you must explicitly perform each step yourself. You must create the role and then assign a permissions 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. Optionally, you can also set the [permissions boundary](access_policies_boundaries.md) for your role.
**To create a role for an AWS service (AWS API)**
1. Create a role: [CreateRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html)
For the role's trust policy, you can specify a file location.
1. Attach a managed permissions policy to the role: [AttachRolePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_AttachRolePolicy.html)
or
Create an inline permissions policy for the role: [PutRolePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_PutRolePolicy.html)
1. (Optional) Add custom attributes to the user by attaching tags: [TagRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagRole.html)
For more information, see [Managing tags on IAM users (AWS CLI or AWS API)](id_tags_users.md#id_tags_users_procs-cli-api).
1. (Optional) Set the [permissions boundary](access_policies_boundaries.md) for the role: [PutRolePermissionsBoundary](https://docs.aws.amazon.com/IAM/latest/APIReference/API_PutRolePermissionsBoundary.html)
A permissions boundary controls the maximum permissions that a role can have. Permissions boundaries are an advanced AWS feature.
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 [Use instance profiles](id_roles_use_switch-role-ec2_instance-profiles.md). For information about how to launch an Amazon EC2 instance with a role, see [Controlling Access to Amazon EC2 Resources](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/UsingIAM.html#UsingIAMrolesWithAmazonEC2Instances) in the *Amazon EC2 User Guide*.
**To create an instance profile and store the role in it (AWS API)**
1. Create an instance profile: [CreateInstanceProfile](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateInstanceProfile.html)
1. Add the role to the instance profile: [AddRoleToInstanceProfile](https://docs.aws.amazon.com/IAM/latest/APIReference/API_AddRoleToInstanceProfile.html)
# Create a service-linked role
A service-linked role is a unique type of IAM 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 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 simplify the process of setting up a service because you don't have to manually add permissions for the service to complete actions on your behalf.
**Note**
Remember that service roles are different from service-linked roles. A service role is an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) that a service assumes to perform actions on your behalf. An IAM administrator can create, modify, and delete a service role from within IAM. For more information, see [Create a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide*. A service-linked role is a type of service role that is linked to an AWS service. The service can assume the role to perform an action on your behalf. Service-linked roles appear in your AWS account and are owned by the service. An IAM administrator can view, but not edit the permissions for service-linked roles.
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.
Before you can delete the roles, you must first delete their related resources. This helps prevent you from inadvertently removing permission to access the resources.
**Tip**
For information about which services support using service-linked roles, see [AWS services that work with IAM](reference_aws-services-that-work-with-iam.md) 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 for an IAM entity (user or role) to allow the user or role to create or edit the service-linked role.
**Note**
The ARN for a service-linked role includes a service principal, which is indicated in the policies below as `SERVICE-NAME.amazonaws.com`. Do not try to guess the service principal, because it is case sensitive and the format can vary across AWS services. To view the service principal for a service, see its service-linked role documentation.
**To allow an IAM entity to create a specific service-linked role**
Add the following policy to the IAM entity that needs to create the service-linked role.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/SERVICE-NAME.amazonaws.com/SERVICE-LINKED-ROLE-NAME-PREFIX*",
"Condition": {"StringLike": {"iam:AWSServiceName": "SERVICE-NAME.amazonaws.com"}}
},
{
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:PutRolePolicy"
],
"Resource": "arn:aws:iam::*:role/aws-service-role/SERVICE-NAME.amazonaws.com/SERVICE-LINKED-ROLE-NAME-PREFIX*"
}
]
}
```
------
**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 service-linked role, or any service role that includes the needed policies. This policy statement does not allow the IAM entity to attach a policy to the role.
```
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/*"
}
```
**To allow an IAM entity to edit the description of any service roles**
Add the following statement to the permissions policy for the IAM entity that needs to edit the description of a service-linked role, or any service role.
```
{
"Effect": "Allow",
"Action": "iam:UpdateRoleDescription",
"Resource": "arn:aws:iam::*:role/aws-service-role/*"
}
```
**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-NAME.amazonaws.com/SERVICE-LINKED-ROLE-NAME-PREFIX*"
}
```
**To allow an IAM entity to delete any service-linked role**
Add the following statement to the permissions policy for the IAM entity that needs to delete a service-linked role, but not service role.
```
{
"Effect": "Allow",
"Action": [
"iam:DeleteServiceLinkedRole",
"iam:GetServiceLinkedRoleDeletionStatus"
],
"Resource": "arn:aws:iam::*:role/aws-service-role/*"
}
```
**To allow an IAM entity to pass an existing role to the service**
Some AWS services allow you to pass an existing role to the service, instead of creating a new service-linked role. To do this, a user must have permissions to *pass the role* to the service. Add the following statement to the permissions policy for the IAM entity that needs to pass a role. This policy statement also allows the entity to view a list of roles from which they can choose the role to pass. For more information, see [Grant a user permissions to pass a role to an AWS service](id_roles_use_passrole.md).
```
{
"Sid": "PolicyStatementToAllowUserToListRoles",
"Effect": "Allow",
"Action": ["iam:ListRoles"],
"Resource": "*"
},
{
"Sid": "PolicyStatementToAllowUserToPassOneSpecificRole",
"Effect": "Allow",
"Action": [ "iam:PassRole" ],
"Resource": "arn:aws:iam::account-id:role/my-role-for-XYZ"
}
```
## Indirect permissions with service-linked roles
Indirect permissions
The permissions granted by a service-linked role can be indirectly transferred to other users and roles. When a service-linked role is used by an AWS service, that service-linked role can use its own permissions to call other AWS services. This means that users and roles with permissions to call a service that uses a service-linked role may have indirect access to services that can be accessed by that service-linked role.
For example, when you create an Amazon RDS DB instance, [a service-linked role for RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAM.ServiceLinkedRoles.html) is automatically created if one does not already exist. This service-linked role allows RDS to call Amazon EC2, Amazon SNS, Amazon CloudWatch Logs, and Amazon Kinesis on your behalf. If you allow users and roles in your account to modify or create RDS databases, then they may be able to indirectly interact with Amazon EC2, Amazon SNS, Amazon CloudWatch Logs logs, and Amazon Kinesis resources by calling RDS, as RDS would use it’s service-linked role to access those resources.
### Methods to create 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 AWS account](troubleshoot_roles.md#troubleshoot_roles_new-role-appeared).
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](reference_aws-services-that-work-with-iam.md) 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html#reference_iam-quotas-entities) 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 (console)
Before you create a service-linked role in IAM, find out whether the linked service automatically creates service-linked roles, In addition, learn whether you can 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.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane of the IAM console, choose **Roles**. Then, choose **Create role**.
1. Choose the **AWS Service** role type.
1. Choose the use case for your service. Use cases are defined by the service to include the trust policy required by the service. Then, choose **Next**.
1. 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 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 checkbox next to the policy that assigns the permissions that you want the role to have, and then choose **Next**.
**Note**
The permissions that you specify are available to any entity that uses the role. By default, a role has no permissions.
1. 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 let you enter an optional suffix.
If possible, enter 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 distinguished by case. For example, you cannot create roles named both **\$1SAMPLE** and **\$1sample**. Because various entities might reference the role, you cannot edit the name of the role after it has been created.
1. (Optional) For **Description**, edit the description for the new service-linked role.
1. You cannot attach tags to service-linked roles during creation. For more information about using tags in IAM, see [Tags for AWS Identity and Access Management resources](id_tags.md).
1. Review the role and then choose **Create role**.
### Creating a service-linked role (AWS 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 (AWS CLI)**
Run the following command:
```
aws iam [create-service-linked-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-service-linked-role.html) --aws-service-name SERVICE-NAME.amazonaws.com
```
### Creating a service-linked role (AWS 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 AWS 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 (AWS API)**
Use the [CreateServiceLinkedRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceLinkedRole.html) 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`.
# Create a role for a third-party identity provider
Create a role for identity federation
You can use identity providers instead of creating IAM users in your AWS account. With an identity provider (IdP), you can manage your user identities outside of AWS and give these external user identities permissions to access AWS resources in your account. For more information about federation and identity providers, see [Identity providers and federation into AWS](id_roles_providers.md).
## Creating a role for OIDC and SAML federated principals (console)
Creating a role (console)
The procedures for creating a role depends on your choice of third party providers:
+ For OpenID Connect (OIDC), see [Create a role for OpenID Connect federation (console)](id_roles_create_for-idp_oidc.md).
+ For SAML 2.0, see [Create a role for SAML 2.0 federation (console)](id_roles_create_for-idp_saml.md).
## Creating a role for federated access (AWS CLI)
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, see [Prerequisites for creating a role for OIDC](id_roles_create_for-idp_oidc.md#idp_oidc_Prerequisites).
+ For a SAML provider, see [Prerequisites for creating a role for SAML](id_roles_create_for-idp_saml.md#idp_saml_Prerequisites).
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 role and then assign a permissions policy to the role. Optionally, you can also set the [permissions boundary](access_policies_boundaries.md) for your role.
**To create a role (AWS CLI)**
1. Create a role: [aws iam create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html)
1. Attach a permissions policy to the role: [aws iam attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html)
or
Create an inline permissions policy for the role: [aws iam put-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-policy.html)
1. (Optional) Add custom attributes to the role by attaching tags: [aws iam tag-role](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-role.html)
For more information, see [Managing tags on IAM roles (AWS CLI or AWS API)](id_tags_roles.md#id_tags_roles_procs-cli-api).
1. (Optional) Set the [permissions boundary](access_policies_boundaries.md) for the role: [aws iam put-role-permissions-boundary](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-permissions-boundary.html)
A permissions boundary controls the maximum permissions that a role can have. Permissions boundaries are an advanced AWS feature.
The following example shows the first two, and most common, steps for creating an identity provider role in a simple environment. This example allows any user in the `123456789012` account to assume the role and view the `example_bucket` Amazon S3 bucket. This example also 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html).
The following example trust policy is designed for a mobile app if the user signs in using Amazon Cognito. In this example, *us-east:12345678-ffff-ffff-ffff-123456* represents the identity pool ID assigned by Amazon Cognito.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Sid": "RoleForCognito",
"Effect": "Allow",
"Principal": {"Federated": "cognito-identity.amazonaws.com"},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {"StringEquals": {"cognito-identity.amazonaws.com:aud": "us-east:12345678-ffff-ffff-ffff-123456"}}
}
}
```
------
The following permissions policy allows anyone who assumes the role to perform only the `ListBucket` action on the `example_bucket` Amazon S3 bucket.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::example_bucket"
}
}
```
------
To create this `Test-Cognito-Role` role, you must first save the previous trust policy with the name `trustpolicyforcognitofederation.json` and the previous permissions policy with the name `permspolicyforcognitofederation.json` to the `policies` folder in your local `C:` drive. You can then use the following commands to create the role and attach the inline policy.
```
# 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-Cognito-Role --assume-role-policy-document file://C:\policies\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-Cognito-Role --policy-name Perms-Policy-For-CognitoFederation --policy-document file://C:\policies\permspolicyforcognitofederation.json
```
## Creating a role for federated access (AWS API)
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, see [Prerequisites for creating a role for OIDC](id_roles_create_for-idp_oidc.md#idp_oidc_Prerequisites).
+ For a SAML provider, see [Prerequisites for creating a role for SAML](id_roles_create_for-idp_saml.md#idp_saml_Prerequisites).
**To create a role (AWS API)**
1. Create a role: [CreateRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html)
1. Attach a permissions policy to the role:[AttachRolePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_AttachRolePolicy.html)
or
Create an inline permissions policy for the role: [PutRolePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_PutRolePolicy.html)
1. (Optional) Add custom attributes to the user by attaching tags: [TagRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagRole.html)
For more information, see [Managing tags on IAM users (AWS CLI or AWS API)](id_tags_users.md#id_tags_users_procs-cli-api).
1. (Optional) Set the [permissions boundary](access_policies_boundaries.md) for the role: [PutRolePermissionsBoundary](https://docs.aws.amazon.com/IAM/latest/APIReference/API_PutRolePermissionsBoundary.html)
A permissions boundary controls the maximum permissions that a role can have. Permissions boundaries are an advanced AWS feature.
# Create a role for OpenID Connect federation (console)
Create a role for OIDC federation
You can use OpenID Connect (OIDC) federated identity providers instead of creating AWS Identity and Access Management users in your AWS account. With an identity provider (IdP), you can manage your user identities outside of AWS and give these external user identities permissions to access AWS resources in your account. For more information about federation and IdPs, see [Identity providers and federation into AWS](id_roles_providers.md).
## Prerequisites for creating a role for OIDC
Before you can create a role for OIDC federation, you must first complete the following prerequisite steps.
**To prepare to create a role for OIDC federation**
1. Sign up with one or more services offering federated OIDC identity. If you are creating an app that needs access to your AWS resources, you also configure your app with the provider information. When you do, the provider gives you an application or audience ID that is unique to your app. (Different providers use different terminology for this process. This guide uses the term *configure* for the process of identifying your app with the provider.) You can configure multiple apps with each provider, or multiple providers with a single app. View information about using the identity providers as follows:
+ [Login with Amazon Developer Center](https://login.amazon.com/)
+ [Add Facebook Login to Your App or Website](https://developers.facebook.com/docs/facebook-login/v2.1) on the Facebook developers site.
+ [Using OAuth 2.0 for Login (OpenID Connect)](https://developers.google.com/accounts/docs/OAuth2Login) on the Google developers site.
1. After you receive the required information from the IdP, create an IdP in IAM. For more information, see [Create an OpenID Connect (OIDC) identity provider in IAM](id_roles_providers_create_oidc.md).
**Important**
If you are using an OIDC IdP from Google, Facebook, or Amazon Cognito, don't create a separate IAM IdP in the AWS Management Console. These OIDC identity providers are already built into AWS and are available for you to use. Skip this step and create new roles using your IdP in the following step.
1. Prepare the policies for the role that the IdP-authenticated users will assume. As with any role, a role for a mobile app includes two policies. One is the trust policy that specifies who can assume the role. The other is the permissions policy that specifies the AWS actions and resources that the mobile app is allowed or denied access to.
For web IdPs, we recommend that you use [Amazon Cognito](https://aws.amazon.com/cognito/) to manage identities. In this case, use a trust policy similar to this example.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Principal": {"Federated": "cognito-identity.amazonaws.com"},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {"cognito-identity.amazonaws.com:aud": "us-east-2:12345678-abcd-abcd-abcd-123456"},
"ForAnyValue:StringLike": {"cognito-identity.amazonaws.com:amr": "unauthenticated"}
}
}
}
```
------
Replace `us-east-2:12345678-abcd-abcd-abcd-123456` with the identity pool ID that Amazon Cognito assigns to you.
If you manually configure an OIDC IdP, when you create the trust policy, you must use three values that ensure that only your app can assume the role:
+ For the `Action` element, use the `sts:AssumeRoleWithWebIdentity` action.
+ For the `Principal` element, use the string `{"Federated":providerUrl/providerArn}`.
+ For some common OIDC IdPs, the `providerUrl` is a URL. The following examples include methods 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 Amazon Resource Name (ARN) of the OIDC IdP that you created in [Step 2](#idpoidcstep2), such as the following example:
`"Principal":{"Federated":"arn:aws:iam::123456789012:oidc-provider/server.example.com"}`
+ For the `Condition` element, use a `StringEquals` condition to limit permissions. Test the identity pool ID for Amazon Cognito) or the app ID for other providers. The identity pool ID should match the app ID that you received when you configured the app with the IdP. This match between the IDs ensures that the request comes from your app.
**Note**
IAM roles for Amazon Cognito identity pools trust the service principal `cognito-identity.amazonaws.com` to assume the role. Roles of this type must contain at least one condition key to limit the principals who can assume the role.
Additional considerations apply to Amazon Cognito identity pools that assume [cross-account IAM roles](access_policies-cross-account-resource-access.md). The trust policies of these roles must accept the `cognito-identity.amazonaws.com` service principal and must contain the `aud` condition key to restrict role assumption to users from your intended identity pools. A policy that trusts Amazon Cognito identity pools without this condition creates a risk that a user from an unintended identity pool can assume the role. For more information, see [ Trust policies for IAM roles in Basic (Classic) authentication ](https://docs.aws.amazon.com/cognito/latest/developerguide/iam-roles.html#trust-policies) in the *Amazon Cognito Developer Guide*.
Create a condition element similar to one of the following examples, depending on the IdP that you are using:
`"Condition": {"StringEquals": {"cognito-identity.amazonaws.com:aud": "us-east:12345678-ffff-ffff-ffff-123456"}}`
`"Condition": {"StringEquals": {"www.amazon.com:app_id": "amzn1.application-oa2-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, such as the following example:
`"Condition": {"StringEquals": {"server.example.com:aud": "appid_from_oidc_idp"}}`
**Note**
The values for the principal in the trust policy for the role are specific to an IdP. A role for OIDC can specify only one principal. Therefore, if the mobile app allows users to sign in from more than one IdP, create a separate role for each IdP that you want to support. Create separate trust policies for each IdP.
If a user uses a mobile app to sign in from Login with Amazon, the following example trust policy would apply. In the example, *amzn1.application-oa2-123456* represents the app ID that Amazon assigns when you configured the app using Login with Amazon.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "RoleForLoginWithAmazon",
"Effect": "Allow",
"Principal": {"Federated": "www.amazon.com"},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {"StringEquals": {"www.amazon.com:app_id": "amzn1.application-oa2-123456"}}
}]
}
```
------
If a user uses a mobile app to sign in from Facebook, the following example trust policy would apply. In this example, *111222333444555* represents the app ID that Facebook assigns.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "RoleForFacebook",
"Effect": "Allow",
"Principal": {"Federated": "graph.facebook.com"},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {"StringEquals": {"graph.facebook.com:app_id": "111222333444555"}}
}]
}
```
------
If a user uses a mobile app to sign in from Google, the following example trust policy would apply. In this example, *666777888999000* represents the app ID that Google assigns.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "RoleForGoogle",
"Effect": "Allow",
"Principal": {"Federated": "accounts.google.com"},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {"StringEquals": {"accounts.google.com:aud": "666777888999000"}}
}]
}
```
------
If a user uses a mobile app to sign in from Amazon Cognito, the following example trust policy would apply. In this example, *us-east:12345678-ffff-ffff-ffff-123456* represents the identity pool ID that Amazon Cognito assigns.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "RoleForCognito",
"Effect": "Allow",
"Principal": {"Federated": "cognito-identity.amazonaws.com"},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {"StringEquals": {"cognito-identity.amazonaws.com:aud": "us-east:12345678-ffff-ffff-ffff-123456"}}
}]
}
```
------
## Creating a role for OIDC
After you complete the prerequisites, you can create the role in IAM. For recognized shared OpenID Connect (OIDC) identity providers (IdPs), IAM requires explicit evaluation of specific claims in JSON Web Tokens (JWTs) known as *identity-provider controls*. For more information about which OIDC IdPs have *identity-provider controls*, see [Identity-provider controls for shared OIDC providers](id_roles_providers_oidc_secure-by-default.md).
The following procedure describes how to create the role for OIDC federation in the AWS Management Console. To create a role from the AWS CLI or AWS API, see the procedures at [Create a role for a third-party identity provider](id_roles_create_for-idp.md).
**Important**
If you use Amazon Cognito, use the Amazon Cognito console to set up the roles. Otherwise, use the IAM console to create a role for OIDC federation.
**To create an IAM role for OIDC federation**
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Roles** and then choose **Create role**.
1. Choose **Web identity** as the trusted entity type and select **Next**.
1. For **Identity provider**, choose the IdP for your role:
+ If you want to create a role for an individual web IdP, choose **Login with Amazon**, **Facebook**, or **Google**.
**Note**
You must create a separate role for each IdP that you want to support.
+ If you want to create an advanced scenario role for Amazon Cognito, choose **Amazon Cognito**.
**Note**
You must manually create a role to use with Amazon Cognito only when you work on an advanced scenario. Otherwise, Amazon Cognito can create roles for you. For more information about Amazon Cognito, see [Identity pools (federated identities) external identity providers](https://docs.aws.amazon.com/cognito/latest/developerguide/external-identity-providers.html) in the *Amazon Cognito Developer Guide*.
+ If you want to create a role for GitHub Actions, you must start by adding the GitHub OIDC provider to IAM. After you've added the GitHub OIDC provider to IAM, choose **token.actions.githubusercontent.com**.
**Note**
For information about how to configure AWS to trust GitHub's OIDC provider as a federated identity, see [GitHub Docs - Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services). For information about best practices for limiting access for roles associated with the IAM IdP for GitHub, see [Configuring a role for GitHub OIDC identity provider](#idp_oidc_Create_GitHub) on this page.
+ If you want to create a role for HashiCorp Cloud Platform (HCP) Terraform, you must start by adding the Terraform OIDC provider to IAM. After you've added the Terraform OIDC provider to IAM, choose **app.terraform.io**.
**Important**
IAM roles for HashiCorp Cloud Platform (HCP) Terraform OIDC provider must evaluate the IAM condition key, `app.terraform.io:sub`, in the role trust policy. This condition key limits which HCP Terraform organizations, projects, workspaces, or run phases are able to assume the role. Without this condition key, your trust policy grants access to your role and AWS resources by identities outside of your organization, which does not align with the principle of least privilege.
If you set or modify a role trust policy for a role associated with the HCP Terraform OIDC provider in your AWS account, but do not evaluate IAM condition key `app.terraform.io:sub`, you will receive an error. Additionally, AWS STS will deny authorization requests if your role trust policy doesn't evaluate this condition key.
1. The requested information varies based on the OIDC provider you choose.
+ Enter the identifier for your application. The label of the identifier changes based on the provider you choose:
+ If you want to create a role for Login with Amazon, enter the app ID into the **Application ID** box.
+ If you want to create a role for Facebook, enter the app ID into the **Application ID** box.
+ If you want to create a role for Google, enter the audience name into the **Audience** box.
+ If you want to create a role for Amazon Cognito, enter the ID of the identity pool that you have created for your Amazon Cognito applications into the **Identity Pool ID** box.
+ If you want to create a role for GitHub Actions, enter the following details:
+ For **Audience**, choose `sts.amazonaws.com`.
+ For **GitHub organization**, enter the GitHub organization name. The GitHub organization name is required and must be alphanumeric including dashes (-). You can't use wildcard characters (\$1 and ?) in the GitHub organization name.
+ (Optional) For **GitHub repository**, enter the GitHub repository name. If you don’t specify a value, it defaults to a wildcard (`*`).
+ (Optional) For **GitHub branch**, enter the GitHub branch name. If you don’t specify a value, it defaults to a wildcard (`*`).
+ If you want to create a role for HashiCorp Cloud Platform (HCP) Terraform, enter the following details:
+ For **Audience**, choose `aws.workload.identity`.
+ For **Organization**, enter the organization name. You can specify a wildcard character (`*`) for all organizations.
+ For **Project**, enter the project name. You can specify a wildcard character (`*`) for all projects.
+ For **Workspace**, enter the workspace name. You can specify a wildcard character (`*`) for all workspaces.
+ For **Run Phase**, enter the run phase name. You can specify a wildcard character (`*`) for all run phases.
1. (Optional) For **Condition (optional)**, choose **Add Condition** 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. You can also add conditions to the trust policy after the role is created. For more information, see [Update a role trust policy](id_roles_update-role-trust-policy.md).
1. Review your OIDC information and then choose **Next**.
1. IAM includes a list of the AWS managed and customer managed policies in your account. Select the policy to use for the permissions policy, or choose **Create policy** to open a new browser tab and create a new policy from scratch. For more information, see [Creating IAM policies](access_policies_create-console.md#access_policies_create-start). After you create the policy, close that tab and return to your original tab. Select the checkbox next to the permissions policies that you want OIDC users to have. If you prefer, you can select no policies at this time, and then attach policies to the role later. By default, a role has no permissions.
1. (Optional) Set a [permissions boundary](access_policies_boundaries.md). This is an advanced feature.
Open the **Permissions boundary** section and choose **Use a permissions boundary to control the maximum role permissions**. Select the policy to use for the permissions boundary.
1. Choose **Next**.
1. For **Role name**, enter a role name. Role names must be unique within your AWS account. They are not case dependent. For example, you can't create roles named both **PRODROLE** and **prodrole**. Because other AWS resources might reference the role, you can't edit the name of the role after you create it.
1. (Optional) For **Description**, enter a description for the new role.
1. To edit the use cases and permissions for the role, choose **Edit** in the **Step 1: Select trusted entities** or **Step 2: Add permissions** sections.
1. (Optional) To add metadata to the role, attach tags as key–value pairs. For more information about using tags in IAM, see [Tags for AWS Identity and Access Management resources](id_tags.md).
1. Review the role and then choose **Create role**.
## Configuring a role for GitHub OIDC identity provider
If you use GitHub as an OpenID Connect (OIDC) identity provider (IdP), best practice is to limit the entities that can assume the role associated with the IAM IdP. When you include a condition statement in the trust policy, you can limit the role to a specific GitHub organization, repository, or branch. You can use the condition key `token.actions.githubusercontent.com:sub` with string condition operators to limit access. We recommend that you limit the condition to a specific set of repositories or branches within your GitHub organization. For information about how to configure AWS to trust GitHub's OIDC as a federated identity, see [GitHub Docs - Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services).
If you use GitHub environments in action workflows or in OIDC policies, we strongly recommend adding protection rules to the environment for additional security. Use deployment branches and tags to restrict which branches and tags can deploy to the environment. For more information on configuring environments with protection rules, see [Deployment branches and tags](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-branches-and-tags) in GitHub's *Using environments for deployment* article.
When GitHub's OIDC IdP is the trusted Principal for your role, IAM checks the role trust policy condition to verify that the condition key `token.actions.githubusercontent.com:sub` is present and that its value is not solely a wildcard character (\$1 and ?) or null. IAM performs this check when the trust policy is created or updated. If the condition key `token.actions.githubusercontent.com:sub` is not present, or the key value doesn't satisfy the mentioned value criteria, the request will fail and return an error.
**Important**
If you do not limit the condition key `token.actions.githubusercontent.com:sub` to a specific organization or repository, then GitHub Actions from organizations or repositories outside of your control are able to assume roles associated with the GitHub IAM IdP in your AWS account.
The following example trust policy limits access to the defined GitHub organization, repository, and branch. The condition key `token.actions.githubusercontent.com:sub` value in the following example is the default subject value format documented by GitHub.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::012345678910:oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
"token.actions.githubusercontent.com:sub": "repo:GitHubOrg/GitHubRepo:ref:refs/heads/GitHubBranch"
}
}
}
]
}
```
------
The following example condition limits access to the defined GitHub organization and repository, but grants access to any branch within the repository.
```
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
},
"StringLike": {
"token.actions.githubusercontent.com:sub": "repo:GitHubOrg/GitHubRepo:*"
}
}
```
The following example condition limits access to any repository or branch within the defined GitHub organization. We recommend that you limit the condition key `token.actions.githubusercontent.com:sub` to a specific value that limits access to GitHub Actions from within your GitHub organization.
```
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
},
"StringLike": {
"token.actions.githubusercontent.com:sub": "repo:GitHubOrg/*"
}
}
```
For more information about the OIDC federation keys available for condition checks in policies, see [Available keys for AWS OIDC federation](reference_policies_iam-condition-keys.md#condition-keys-wif).
# Create a role for SAML 2.0 federation (console)
Create a role for SAML 2.0 federation
You can use SAML 2.0 federation instead of creating IAM users in your AWS account. With an identity provider (IdP), you can manage your user identities outside of AWS and give these external user identities permissions to access AWS resources in your account. For more information about federation and identity providers, see [Identity providers and federation into AWS](id_roles_providers.md).
**Note**
To improve federation resiliency, we recommend that you configure your IdP and AWS federation to support multiple SAML sign-in endpoints. For details, see the AWS Security Blog article [How to use regional SAML endpoints for failover](https://aws.amazon.com/blogs//security/how-to-use-regional-saml-endpoints-for-failover).
## Prerequisites for creating a role for SAML
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 [Create a SAML identity provider in IAM](id_roles_providers_create_saml.md).
1. 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 includes two policies. One is the role trust policy that specifies who can assume the role. The other is the IAM permissions policy that specifies the AWS actions and resources that the SAML federated principal is allowed or denied access to.
When you create the trust policy for your role, you must use three values to ensure that only your application can assume the role:
+ For the `Action` element, use the `sts:AssumeRoleWithSAML` action.
+ For the `Principal` element, use the string `{"Federated":ARNofIdentityProvider}`. Replace `ARNofIdentityProvider` with the ARN of the [SAML identity provider](id_roles_providers_saml.md) that you created in [Step 1](#idpsamlstep1).
+ For the `Condition` element, use a `StringEquals` condition to test that the `saml:aud` attribute from the SAML response matches the URL your browser displays when signing into the console. This sign-in endpoint URL is your identity provider's SAML recipient attribute. You can include sign-in URLs within particular regions. AWS recommends using Regional endpoints instead of the global endpoint to improve federation resiliency. For a list of possible *region-code* values, see the **Region** column in [AWS Sign-In endpoints](https://docs.aws.amazon.com/general/latest/gr/signin-service.html).
If SAML encryption is required, the sign-in URL must include the unique identifier AWS assigns to your SAML provider. You can view the unique identifier by selecting the identity provider in the IAM console to display the details page.
`https://region-code.signin.aws.amazon.com/saml/acs/IdP-ID`
The following example trust policy is designed for a SAML federated user:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRoleWithSAML",
"Principal": {
"Federated": "arn:aws:iam::111122223333:saml-provider/PROVIDER-NAME"
},
"Condition": {
"StringEquals": {
"SAML:aud": "https://region-code.signin.aws.amazon.com/saml"
}
}
}
}
```
------
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 provider name.
## Creating a role for SAML
After you complete the prerequisite steps, you can create the role for SAML-based federation.
**To create a role for SAML-based federation**
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane of the IAM console, choose **Roles** and then choose **Create role**.
1. Choose the **SAML 2.0 federation** role type.
1. For **Select a SAML provider**, choose the provider for your role.
1. 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 or AWS CLI.
+ Choose **Allow programmatic and AWS Management Console access** to create a role that can be assumed programmatically and from the AWS Management 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 your SAML provider.
1. The procedure for defining attributes varies depending on the access type.
+ If you're creating a role for programmatic access, choose an attribute from the **Attribute** list. Then, in the **Value** box, enter 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 AWS Management Console access, the **Sign-in endpoints** section defines the URL your browser displays when signing into the console. This endpoint is your identity provider's SAML recipient attribute, which maps to the [`saml:aud`](reference_policies_iam-condition-keys.md#condition-keys-saml) context key. For more information, see [Configure SAML assertions for the authentication response](id_roles_providers_create_saml_assertions.md).
1. Choose **Regional endpoints** or **Non-regional endpoint**. We recommend using multiple Regional SAML sign-in endpoints to improve federation resiliency.
1. For **Regions**, choose the regions that your SAML provider supports for AWS sign-in.
1. For **Sign-in URLs to include unique identifiers**, select whether the sign-in endpoints include the unique identifiers AWS assigns to your SAML identity provider. This option is required for encryped SAML assertions. For more information, see [SAML 2.0 federation](id_roles_providers_saml.md).
1. To add more attribute-related conditions to the trust policy, choose **Condition (optional)**, select the additional condition, and specify a value.
**Note**
The list includes 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#condition-keys-saml). If you need a condition for a supported SAML attribute that's not in the list, you can manually add that condition. To do that, edit the trust policy after you create the role.
1. Review your SAML 2.0 trust information and then choose **Next**.
1. IAM includes a list of the AWS managed and customer managed policies in your account. Select the policy to use for the permissions policy, or choose **Create policy** to open a new browser tab and create a new policy from scratch. For more information, see [Creating IAM policies](access_policies_create-console.md#access_policies_create-start). After you create the policy, close that tab and return to your original tab. Select the checkbox next to the permissions policies that you want SAML federated users to have. If you prefer, you can select no policies at this time, and then attach policies to the role later. By default, a role has no permissions.
1. (Optional) Set a [permissions boundary](access_policies_boundaries.md). This is an advanced feature.
Open the **Permissions boundary** section and choose **Use a permissions boundary to control the maximum role permissions**. Select the policy to use for the permissions boundary.
1. Choose **Next**.
1. Choose **Next: Review**.
1. For **Role name**, enter a role name. 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 other AWS resources might reference the role, you cannot edit the name of the role after it has been created.
1. (Optional) For **Description**, enter a description for the new role.
1. Choose **Edit** in the **Step 1: Select trusted entities** or **Step 2: Add permissions** sections to edit the use cases and permissions for the role.
1. (Optional) Add metadata to the role by attaching tags as key–value pairs. For more information about using tags in IAM, see [Tags for AWS Identity and Access Management resources](id_tags.md).
1. 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. This information includes the roles that you want your SAML federated users to use. This is referred to as configuring the relying party trust between your IdP and AWS. For more information, see [Configure your SAML 2.0 IdP with relying party trust and adding claims](id_roles_providers_create_saml_relying-party.md).
# Create a role using custom trust policies
Create a role using custom trust policies
You can create a custom trust policy to delegate access and allow others to perform actions in your AWS account. For more information, see [Creating IAM policies](access_policies_create-console.md#access_policies_create-start).
For information about how to use roles to delegate permissions, see [Roles terms and concepts](id_roles.md#id_roles_terms-and-concepts).
## Creating an IAM role using a custom trust policy (console)
You can use the AWS Management Console to create a role that an IAM user can assume. For example, assume that your organization has multiple AWS accounts to isolate a development environment from a production environment. For high-level information about creating 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](id_roles_common-scenarios_aws-accounts.md#id_roles_common-scenarios_aws-accounts-example).
**To create a role using a custom trust policy (console)**
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane of the console, choose **Roles** and then choose **Create role**.
1. Choose the **Custom trust policy** role type.
1. In the **Custom trust policy** section, enter or paste the custom trust policy for the role. For more information, see [Creating IAM policies](access_policies_create-console.md#access_policies_create-start).
1. Resolve any security warnings, errors, or general warnings generated during [policy validation](access_policies_policy-validator.md), and then choose **Next**.
1. (Optional) Set a [permissions boundary](access_policies_boundaries.md). This is an advanced feature that is available for service roles, but not service-linked roles.
Open the **Permissions boundary** section and choose **Use a permissions boundary to control the maximum role permissions**. IAM includes a list of the AWS managed and customer managed policies in your account. Select the policy to use for the permissions boundary.
1. Choose **Next**.
1. 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 enter an optional suffix. Some services allow you to specify the entire name of your role.
If possible, enter a role name or role name suffix. 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 other AWS resources might reference the role, you cannot edit the name of the role after it has been created.
1. (Optional) For **Description**, enter a description for the new role.
1. (Optional) Choose **Edit** in the **Step 1: Select trusted entities** or **Step 2: Add permissions** sections to edit the custom policy and permissions for the role.
1. (Optional) Add metadata to the role by attaching tags as key–value pairs. For more information about using tags in IAM, see [Tags for AWS Identity and Access Management resources](id_tags.md).
1. Review the role and then choose **Create role**.
# Examples of policies for delegating access
The following examples show how you can allow or grant an AWS account access to the resources in another AWS account. To learn how to create an IAM policy using these example JSON policy documents, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).
**Topics**
+ [
## Using roles to delegate access to the resources of another AWS account resources
](#example-delegate-xaccount-rolesapi)
+ [
## Using a policy to delegate access to services
](#id_roles_create_policy-examples-access-to-services)
+ [
## Using a resource-based policy to delegate access to an Amazon S3 bucket in another account
](#example-delegate-xaccount-S3)
+ [
## Using a resource-based policy to delegate access to an Amazon SQS queue in another account
](#example-delegate-xaccount-SQS)
+ [
## Cannot delegate access when the account is denied access
](#example-delegate-xaccount-SQS-denied)
## Using roles to delegate access to the resources of another AWS account resources
For a tutorial that shows how to use IAM roles to grant users in one account access to AWS resources that are in another account, see [IAM tutorial: Delegate access across AWS accounts using IAM roles](tutorial_cross-account-with-roles.md).
**Important**
You can include the ARN for a specific role or user in the `Principal` element of a role trust policy. When you save the policy, AWS transforms the ARN to a unique principal ID. 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. It is 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). 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.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"elasticmapreduce.amazonaws.com",
"datapipeline.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
## 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingBucketPolicies.html)) 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 *amzn-s3-demo-bucket*, and account B's account number is 111122223333. It does not specify any individual users or groups in account B, only the account itself.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Sid": "AccountBAccess1",
"Effect": "Allow",
"Principal": {"AWS": "111122223333"},
"Action": "s3:*",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
}
}
```
------
Alternatively, account A can use Amazon S3 [Access Control Lists (ACLs)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/S3_ACLs_UsingACLs.html) 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingAuthAccess.html) in the *Amazon Simple Storage Service User Guide*.
The administrator of account B might create the following policy sample. The policy allows read access to a group or user in account B. The preceding policy grants access to account B. However, 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 preceding cross-account policy. 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.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "s3:List*",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
}
}
```
------
## 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.
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.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Principal": {"AWS": "111122223333"},
"Action": [
"sqs:SendMessage",
"sqs:ReceiveMessage"
],
"Resource": ["arn:aws: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).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sqs:*",
"Resource": "arn:aws: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. However 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. 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
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. The deny propagates to the users under that account whether or not the users have existing policies granting them access.
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. It overrides the IAM user policy granting access to the user in account B. (For detailed information how permissions are evaluated, see [Policy evaluation logic](reference_policies_evaluation-logic.md).)
Account A's bucket policy might look like the following policy. In this example, account A's S3 bucket is named *amzn-s3-demo-bucket*, and account B's account number is 1111-2222-3333. Account A uses Amazon S3 to implement this policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Sid": "AccountBDeny",
"Effect": "Deny",
"Principal": {"AWS": "111122223333"},
"Action": "s3:*",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
}
```
------
This explicit deny overrides any policies in account B that provide permission to access the S3 bucket in account A.