Menu
AWS Identity and Access Management
User Guide

Creating a Role to Delegate Permissions to an AWS Service

Many AWS services require that you use roles to control what that service can access. A role that a service assumes to perform actions on your behalf is called a service role. When a role serves a specialized purpose for a service, it is categorized as a service role for EC2 instances (for example), or a service-linked role. See the AWS documentation for each service to see if it uses roles and to learn how to assign a role for the service to use.

When you create a role to delegate permissions to an AWS service, you must choose the type of role that the AWS service requires. For services that require a service-linked role, AWS includes a role with predefined permissions that provide the needed access. This makes setting up a service easier because you don’t have to manually add the necessary permissions. For information about which services support service-linked roles, see AWS Services That Work with IAM and look for the services that have Yes in the Service-Linked Role column.

For most other services, in order to delegate permissions to an AWS service, you must select an AWS service role. This service role must include all the permissions required for the service to access the AWS resources that it needs. Service roles vary from service to service, but many allow you to choose your permissions, as long as you meet the documented requirements for that service. See the AWS documentation for each service to see what type of role it uses (if any) and how to assign that role for the service to use.

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

Creating a Role for an AWS Service (Console)

You can use the AWS Management Console to create a service-linked role or a service role, depending on the requirements of your service.

To create a service-linked role for an AWS service

  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. Expand the AWS service-linked role section, and then select the service that you want to allow to assume this role.

  4. For Role name, type a suffix to add to the service-linked role 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 PRODROLE and prodrole. Because various entities might reference the role, you cannot edit the name of the role after it has been created.

  5. (Optional) For Role description, type a description for the new role.

  6. Review the role and then choose Create role.

To create a role for an AWS service

  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. Expand the AWS Service Roles section, and then select the service that you want to allow to assume this role.

  4. For Role name, type a role name to help you identify the purpose of this role. Role names must be unique within your AWS account. They are not distinguished by case. For example, you cannot create roles named both PRODROLE and prodrole. Because various entities might reference the role, you cannot edit the name of the role after it has been created.

  5. (Optional) For Role description, type a description for the new role.

  6. Review the role and then choose Create role.

Creating a Role for a Service (AWS CLI)

You can use the AWS Command Line Interface (CLI) to create a service-linked role or a service role, depending on the requirements of your service.

CLI for Service-Linked Roles

To create a service-linked role in code that uses the API, use the create-service-linked-role command. In the command, you must specify a service and a suffix for the role name.

This CLI command creates a service-linked role with the trust policy and inline policies that the service needs. Some services allow you to embed an inline policy for a service-linked role, but only in the service that depends on the role. See the AWS documentation for your service to see whether it supports this feature.

CLI for Service Roles

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 Controlling Access to Amazon EC2 Resources in the Amazon EC2 User Guide for Linux Instances.

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

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://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://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)

You can use the AWS API to create a service-linked role or a service role, depending on the requirements of your service.

API for Service-Linked Roles

To create a service-linked role in code that uses the API, use the CreateServiceLinkedRole API call. In the request, specify a service and a suffix for the role name.

This API call creates a service-linked role with the trust policy and inline policies that the service needs. Some services allow you to embed an inline policy for a service-linked role, but only in the service that depends on the role. See the AWS documentation for your service to see whether it supports this feature.

API for Service Roles

To create a service 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 Controlling Access to Amazon EC2 Resources in the Amazon EC2 User Guide for Linux Instances.