AWS Identity and Access Management
Using IAM (API Version 2010-05-08)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

IAM Roles (Delegation and Federation)

Sometimes you want to delegate access to users, applications, or services that don't normally have access to your AWS resources. For example, you might want to grant a user in your AWS account access to resources they don't usually have, or grant a user in one AWS account access to resources in another account. Or you might want to allow a mobile app to use AWS resources, but not want to store AWS keys within the app (where they can be difficult to rotate and where users can potentially extract them). Sometimes you want to give users who already have identities outside of AWS, such as through your corporate directory, access to AWS resources, that is, create federated identities. Or, you might want to grant access to your account to a third party, for example, so that they can perform an audit on your resources.

For these scenarios, you can delegate access to AWS resources using an IAM role. This section introduces roles and the different ways you can use them, when and how to choose among approaches, and how to create, manage, switch to (or assume), and delete roles.

Roles - Terms and Concepts

Before we dig into scenarios for using roles, here are some basic terms that are useful to know before you start.

Role

A role is essentially a set of permissions that grant access to actions and resources in AWS. These permissions are attached to the role, not to an IAM user or group. Roles can be used by an IAM user in the same AWS account as the role or a different account, an AWS service such as Amazon EC2, or an identity provider (IdP) that is compatible with SAML 2.0 or OpenID Connect.

Policy

You define the permissions for a role in an IAM policy, which is a JSON document written in the IAM Policy Language.

When you create the role, you create two separate policies for it: The trust policy, which specifies who is allowed to assume the role (the trusted entity, or principal - see next term), and the permissions policy, which defines what actions and resources the principal is allowed to use.

Principal

A principal is an entity in AWS which can perform action and access resources. A principal can be an AWS account (the "root" user), an IAM user, group, or role. You can use a policy to grant permissions to a principal by attaching the policy to the principal, or by referencing the principal in a policy that is attached to a resource. If you reference an AWS account, it generally means any principal defined in that account.

Cross-Account Access: Roles Versus Resource-Based Policies

Granting access to resources in one account to a trusted principal in a different account is often referred to as cross-account access. Roles are the primary way to grant cross-account access. However, some AWS services enable you to attach a policy directly to a resource (instead of using a role as a proxy). These polices are called resource-based policies, and you can use them to grant another principals in another AWS account access to the resource. The following services support resource-based policies for the specified resources: Amazon S3 buckets, Amazon SNS topics, and Amazon SQS queues. For more information, see How Roles Differ from Resource-Based Policies.

There are two ways to use roles, in the IAM console, or programmatically in the AWS CLI or API:

  • IAM users in your account can switch to a role while they are working in the IAM console to temporarily use the permissions of the role. The user gives up their original permissions and takes on the permissions assigned to the role. When the user exits the role, their original permissions are reinstated.

  • An application or AWS service (like Amazon EC2) can assume a role by requesting temporary security credentials with which to make programmatic requests to AWS. You might use roles programmatically, for example, so that you don't have to share or maintain long-term security credentials (for example, by creating an IAM user) for each entity that requires access to a resource.

Use Cases: Roles for Users, Applications, and Services

The simplest way to use roles is to grant your IAM users permissions to switch to roles that you create within your own or another AWS account. They can switch roles easily using the IAM console to use permissions that you don't ordinarily want them to have, and then exit the role to surrender those permissions. This can help prevent accidental access to or modification of sensitive resources.

For more complex uses of roles, such as granting access to applications and services, or federated users, you to call the AssumeRole API function. The function returns a set of temporary credentials that the application can use in subsequent function calls. Actions attempted with the temporary credentials have the permissions granted by the role. An application doesn't have to "exit" the role the way a user in the console does, rather the code simply stops using the temporary credentials and resumes making calls with the original credentials.

Federated users sign in using credentials provided by an identity provider (IdP). AWS then provides the IdP with temporary credentials associated with a role to pass on to the user for including in subsequent AWS resource requests. Those credentials provide the permissions granted to the assigned role.

This section discusses the following scenarios:

  • Switch to a role as an IAM user in one AWS account to access resources in another account that you own

  • Provide access for AWS services to AWS resources

  • Provide access for externally authenticated users (identity federation)

  • Provide access to third parties

Switching to a role as an IAM user between accounts you own

You can grant your IAM users permission to switch roles within your AWS account or to roles defined in other AWS accounts you own.

Note

If the "other" account to which you want to grant access to your resources is owned by a different organization not in your control, see the section Providing access to third parties later in this topic.

For example, you might have Amazon EC2 instances that are critical to your organization. Instead of directly granting your users permission to terminate the instances, you can create a role with those privileges and allow administrators to switch to the role when they need to terminate an instance. This adds the following layers of protection to the instances:

  • You must explicitly grant your users permission to assume the role.

  • Your users must actively switch to the role using the AWS console.

  • You can add multi-factor authentication (MFA) protection to the role so that only users who sign in with an MFA device can assume the role.

We recommend using this approach to enforce the principle of least access, that is, restricting the use of elevated permissions to only those times when they are needed for specific tasks. With roles you can help prevent accidental changes to sensitive environments, especially if you combine them with auditing to help ensure that roles are only used when needed.

To create a role for this purpose, specify the account IDs that contain the users as principals in the role's trust policy. You can then grant specific users in those accounts permissions to use the role.

A user in one account can switch to a role in the same or a different account. While using the role, the user can perform the actions and access the resources permitted by the role, but their original user permissions are inactive. When the user exits the role, the original user permissions take effect again.

For example, you might have multiple AWS accounts to isolate a development environment from a production environment. Users from one account might occasionally need to access resources in the other account, such as when you are promoting an update from the development environment to the production environment. Although users who work in both accounts could have separate identities (and passwords) in each account, managing credentials for multiple accounts makes identity management difficult.

Suppose that your organization has two AWS accounts: Production and Development. The Production account is where live applications are managed, and the Development account is a sandbox where developers and testers can freely test applications. In the following figure, all users are managed in the Development account, but some developers require limited access to the Production account. The Development account has two groups: Testers and Developers, and each group has its own policy.

Use a role to delegate permissions to a user in a different account

Use a role to delegate permissions to a user in a different account

  1. An administrator in the Production account uses IAM to create the UpdateAPP role. In the role, the administrator defines a trust policy that specifies the Development account as a Principal, meaning that authorized users from the Development account can use the UpdateAPP role. The administrator also defines a permissions policy for the role that specifies users of the role have read and write permissions for the productionapp bucket.

    The administrator then shares the ARN of the role with anyone who needs to assume the role. The role ARN might look like arn:aws:iam::123456789012:role/UpdateAPP, where the role is named UpdateAPP and the role was created in account number 123456789012.

    Note

    The administrator can optionally configure the role so that users who assume the role must first be authenticated using multi-factor authentication (MFA). For more information, see Configuring MFA-Protected API Access.

  2. In the Development account, an administrator grants members of the Developer group permission to switch to the role. This is done by granting the Developer group permission to call the AWS Security Token Service (AWS STS) AssumeRole API for the UpdateAPP role. Any IAM user that belongs to the Developer group in the Development account can now switch to the UpdateAPP role in the Production account. Other users who are not in the Developer group do not have permission to switch to the role, and therefore cannot access the Amazon S3 bucket in the Production account.

  3. The user requests switches to the role:

    • AWS console: The user selects the Switch Role option in the Identity menu. The user specifies the account ID (or alias) and role name. The user can alternatively click on a link sent in email by the administrator. The link takes the user to the Switch Role page with the details already filled in.

    • API/CLI: A user in the Developer group of the Development account calls the AssumeRole function to obtain the UpdateAPP role credentials. The user specifies the ARN of the UpdateAPP role as part of the call. If a user in the Testers group makes the same request, the request fails because Testers do not have permission to call AssumeRole by using the UpdateAPP role ARN.

  4. Temporary credentials are returned:

    • AWS console: AWS STS verifies the request against the role's trust policy to ensure that the request is from a trusted entity (which it is: the Development account). After verification, AWS STS returns temporary security credentials to the AWS console.

    • API/CLI: AWS STS verifies the request against the role's trust policy to ensure that the request is from a trusted entity (which it is: the Development account). After verification, AWS STS returns temporary security credentials to the application.

  5. The temporary credentials are used to access the AWS resource:

    • AWS console: The AWS console uses the temporary credentials on the behalf of the user on all subsequent console actions, in this case, to read and write to the productionapp bucket. The console cannot access any other resource in the Production account. When the user exits the role, the user's permissions revert to the original permissions held before switching to the role.

    • API/CLI: The application uses the temporary security credentials to update the productionapp bucket. With the temporary security credentials, the application can only read and write to the productionapp bucket and cannot access any other resource in the Production account. The application does not have to exit the role, but instead stops using the temporary credentials and reverts to using the original credentials in subsequent API calls.

Providing access to an AWS service

Some AWS services use roles to control what the service can access. Each service is different in terms of how it uses roles and how the roles are assigned to the service. When an AWS service, such as an Amazon EC2 instance that runs your application, needs to make requests to an AWS resource, such as an Amazon S3 bucket or a DynamoDB table, the service must have security credentials that grant permissions to the resource. Do not embed or pass IAM user credentials directly into an instance, because distributing and rotating long-term credentials to multiple instances is challenging to manage and a potential security risk. A better strategy is to create a role that is assigned to the Amazon EC2 instance when it is launched. AWS automatically provides temporary security credentials for the Amazon EC2 instance to use on behalf of its applications. For more information, see Using IAM Roles to Delegate Permissions to Applications that Run on Amazon EC2.

See the documentation for a specific service to see if it uses roles and how to assign a role for the service to use.

Providing access to externally authenticated users (identity federation)

Your users might already have identities outside of AWS, such as in your corporate directory. If those users need to work with AWS resources (or work with applications that access those resources) then those users also need AWS security credentials. You can use an IAM role to specify permissions for users whose identity is federated from your organization or a third-party identity provider (IdP). For more information, see Using Your Company's Own Authentication System to Grant Access to AWS Resources and Creating Temporary Security Credentials to Enable Access for Federated Users in the Using Temporary Security Credentials guide.

  • If your organization supports SAML 2.0 (Security Assertion Markup Language 2.0), you can create trust between your organization as an identity provider (IdP) and AWS as the service provider. You can then use SAML to provide your users with federated single-sign on (SSO) to the AWS Management Console or federated access to call AWS APIs. For more information, see Creating Temporary Security Credentials for SAML Federation in the Using Temporary Security Credentials guide.

  • If you create a mobile or web-based app that accesses AWS resources, the app needs security credentials in order to make programmatic requests to AWS. But you shouldn't embed long-term security credentials in the app, because they are accessible to the app's users and can be difficult to rotate. Instead, you can let users sign in to your app using Login with Amazon, Amazon Cognito, Facebook, or Google, and then use their authentication information to assume a role and get temporary security credentials. We recommend that you use Amazon Cognito with the AWS SDKs for mobile development. For more information, see the following:

Providing access to third parties

When third parties require access to your organization's AWS resources, you can use roles to delegate access to them. For example, a third party might provide a service for managing your AWS resources. With IAM roles, you can grant these third parties access to your AWS resources without sharing your AWS security credentials. Instead, they can assume a role that you created to access your AWS resources.

Third parties must provide you the following information for you to create a role that they can assume:

  • The third party's AWS account ID that contains the IAM users that can use your role. You specify their AWS account ID as the principal when you define the trust policy for the role.

  • An external ID that the third party can use to associate you with your role. You specify the ID that is provided by the third party as a condition when you define the trust policy for the role. For more information about the external ID, see About the External ID.

  • The permissions that the third party requires to work with your AWS resources. You specify these permissions when defining the role's permission policy. This policy defines what actions they can take and what resources they can access.

After you create the role, you must share the role's Amazon Resource Name (ARN) with the third party. They require your role's ARN in order to use the role.

Important

When you grant third parties access to your AWS resources, they can access any resource that you give them permissions to and their use of your resources is billed to you. Ensure that you limit their use of your resources appropriately.