Menu
AWS Identity and Access Management
User Guide

Creating a Role to Delegate Permissions to an AWS Service

You create a role for an AWS service when you want to grant permissions to a service like Amazon EC2, AWS Data Pipeline, Amazon Elastic Transcoder, or AWS OpsWorks. These services can access AWS resources, so you create a role to determine what the service is allowed to do with those resources. In many scenarios, you can select an AWS managed policy that contains predefined permissions. However, if you have requirements that are not covered by an AWS managed policy, you can create a custom managed policy or start with a copy of an AWS managed policy.

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

Creating a Role for an AWS Service (AWS Management Console)

You can use the AWS Management Console to create an IAM role for a service.

To create a role for an AWS service using the AWS Console

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

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

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

    Because various entities might reference the role, you cannot change the name of the role after it has been created.

    Important

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

  4. Expand the AWS Service Roles section, and then select the service that you want to allow to assume this role.

  5. Select the check box for a managed policy that grants the permissions that you want the service to have. If the policy does not yet exist, then you can skip this step, create the policy later, and then attach it to the role.

  6. Click Next Step to review the role. Then click Create Role.

Creating a Role for a Service (AWS Command Line Interface)

Creating a role from the AWS CLI involves multiple steps. When you use the console to create a role, many of the steps are done for you, but with the AWS CLI you must explicitly perform each step yourself. You must create the policy and assign an access policy to the role. If the service you are working with is Amazon EC2, then you must also create an instance profile and add the role to it.

To create a role for an AWS service from the AWS CLI, use the following commands:

If you are going to use the role with Amazon EC2 or another AWS service that uses Amazon EC2, you must store the role in an instance profile. An instance profile is a container for a role that can be attached to an Amazon EC2 instance when launched. An instance profile can contain only one role, and that limit cannot be increased. If you create the role using the AWS Management Console, the instance profile is created for you with the same name as the role. For more information about instance profiles, see Using Instance Profiles. For information about how to launch an EC2 instance with a role, see Using IAM roles with Amazon EC2 instances in the Amazon EC2 User Guide for Linux Instances.

To create an instance profile and add a role to it from the AWS CLI, use the following commands:

The following example shows all four steps. The example assumes that you are running on a client computer running Windows and have already configured your command line interface with your account credentials and region. For more information, see Configuring the AWS Command Line Interface.

The sample trust policy referenced in the first command contains the following JSON code to enable the Amazon EC2 service to assume the role.

Copy
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Principal": {"Service": "ec2.amazonaws.com"}, "Action": "sts:AssumeRole" } }

The sample access policy referenced in the second command allows the role to perform only the ListBucket action on an S3 bucket named example_bucket.

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

The AWS CLI commands to run for this example are the following:

Copy
# Create the role and attach the trust policy that enables EC2 to assume this role. aws iam create-role --role-name Test-Role-for-EC2 --assume-role-policy-document file://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, or the --iam-instance-profile parameter if you use the aws ec2 run-instances CLI command.

Creating a Role for a Service (Tools for Windows PowerShell)

Creating a role using the Tools for Windows PowerShell involves multiple steps. When you use the console to create a role, many of the steps are done for you, but with the Windows PowerShell cmdlets you must explicitly perform each step yourself. You must create the policy and assign an access policy to the role. If the service you are working with is Amazon EC2, then you must also create an instance profile and add the role to it.

To create a role for an AWS service using the Tools for Windows PowerShell, use the following commands:

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. An instance profile can contain only one role, and that limit cannot be increased. If you create the role in the AWS Management Console, the instance profile is created for you with the same name as the role. For more information about instance profiles, see Using Instance Profiles. For information about how to launch an EC2 instance with a role, see Using IAM roles with Amazon EC2 instances in the Amazon EC2 User Guide for Linux Instances.

The following example shows all four steps. The example assumes that you are running on a client computer running Windows, and have already configured your command line interface with your account credentials and region. For more information, see Using AWS Credentials in the AWS Tools for Windows PowerShell User Guide.

The sample trust policy referenced in the first command contains the following JSON code to enable the Amazon EC2 service to assume the role.

Copy
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Principal": {"Service": "ec2.amazonaws.com"}, "Action": "sts:AssumeRole" } }

The sample access policy referenced in the second command allows the role to perform only the ListBucket action on an S3 bucket named example_bucket.

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

The Tools for Windows PowerShell commands to run for this example are the following:

Copy
# Create the role and attach the trust policy that enables EC2 to assume this role. New-IAMRole -RoleName Test-Role-for-EC2 -AssumeRolePolicyDocument (Get-Content -raw C:\policies\trustpolicyforec2.json) # Create an permissions policy (in this example an inline policy) for the role to specify what it is allowed to do. Write-IAMRolePolicy -RoleName Test-Role-for-EC2 -PolicyName Permissions-Policy-For-Ec2 -PolicyDocument (Get-Content -raw c:\policies\permissionspolicyforec2.json) # The following two lines are only needed when the role is for the EC2 service # Create the instance profile required by EC2 to contain the role New-IAMInstanceProfile -InstanceProfileName EC2-ListBucket-S3 # Finally, add the role to the instance profile Add-IAMRoleToInstanceProfile -InstanceProfileName EC2-ListBucket-S3 -RoleName Test-Role-for-EC2

When you launch the EC2 instance, specify the instance profile name in the Configure Instance Details page if you use the AWS console, or the -InstanceProfile_Name or -InstanceProfile_Arn parameter if you use the New-EC2Instance Windows PowerShell cmdlet.

Creating a Role for a Service (AWS API)

To create a role in code that uses the API, use the following commands.

  • Create a role: CreateRole

    For the role's trust policy, you can specify a file location.

  • Attach a managed access policy to the role: AttachRolePolicy

    or

    Create an inline access policy for the role: PutRolePolicy

If you are going to use the role with Amazon EC2 or another AWS service that uses Amazon EC2, you must store the role in an instance profile. An instance profile is a container for a role. Each instance profile can contain only one role, and that limit cannot be increased. If you create the role in the AWS Management Console, the instance profile is created for you with the same name as the role. For more information about instance profiles, see Using Instance Profiles. For information about how to launch an Amazon EC2 instance with a role, see Using IAM roles with Amazon EC2 instances in the Amazon EC2 User Guide for Linux Instances.