Methods to assume a role - AWS Identity and Access Management

Methods to assume a role

Before a user, application, or service can use a role that you created, you must grant permissions to switch to the role. You can use any policy attached to groups or users to grant the necessary permissions. This section describes how to grant users permission to use a role. It also explains how the user can switch to a role from the AWS Management Console, the Tools for Windows PowerShell, the AWS Command Line Interface (AWS CLI) and the AssumeRole API.

Important

When you create a role programmatically instead of in the IAM console, you have an option to add a Path of up to 512 characters in addition to the RoleName, which can be up to 64 characters long. However, if you intend to use a role with the Switch Role feature in the AWS Management Console, then the combined Path and RoleName cannot exceed 64 characters.

You can switch roles from the AWS Management Console. You can assume a role by calling an AWS CLI or API operation or by using a custom URL. The method that you use determines who can assume the role and how long the role session can last. When using AssumeRole* API operations, the IAM role that you assume is the resource. The user or role that calls AssumeRole* API operations is the principal.

The following table compares methods for using roles.

Method of assuming the role Who can assume the role Method to specify credential lifetime Credential lifetime (min | max | default)
AWS Management Console User (by switching roles) Maximum session duration on the Role Summary page 15m | Maximum session duration setting² | 1hr
assume-role CLI or AssumeRole API operation User or role¹ duration-seconds CLI or DurationSeconds API parameter 15m | Maximum session duration setting² | 1hr
assume-role-with-saml CLI or AssumeRoleWithSAML API operation Any user authenticated using SAML duration-seconds CLI or DurationSeconds API parameter 15m | Maximum session duration setting² | 1hr
assume-role-with-web-identity CLI or AssumeRoleWithWebIdentity API operation Any user authenticated using an OIDC provider duration-seconds CLI or DurationSeconds API parameter 15m | Maximum session duration setting² | 1hr
Console URL constructed with AssumeRole User or role SessionDuration HTML parameter in the URL 15m | 12hr | 1hr
Console URL constructed with AssumeRoleWithSAML Any user authenticated using SAML SessionDuration HTML parameter in the URL 15m | 12hr | 1hr
Console URL constructed with AssumeRoleWithWebIdentity Any user authenticated using an OIDC provider SessionDuration HTML parameter in the URL 15m | 12hr | 1hr

¹ Using the credentials for one role to assume a different role is called role chaining. When you use role chaining, your new credentials are limited to a maximum duration of one hour. When you use roles to grant permissions to applications that run on EC2 instances, those applications are not subject to this limitation.

² This setting can have a value from 1 hour to 12 hours. For details about modifying the maximum session duration setting, see IAM role management. This setting determines the maximum session duration that you can request when you get the role credentials. For example, when you use the AssumeRole* API operations to assume a role, you can specify a session length using the DurationSeconds parameter. Use this parameter to specify the length of the role session from 900 seconds (15 minutes) up to the maximum session duration setting for the role. IAM users who switch roles in the console are granted the maximum session duration, or the remaining time in their user session, whichever is less. Assume that you set a maximum duration of 5 hours on a role. An IAM user that has been signed into the console for 10 hours (out of the default maximum of 12) switches to the role. The available role session duration is 2 hours. To learn how to view the maximum value for your role, see Update the maximum session duration for a role later in this page.

Notes

  • The maximum session duration setting does not limit sessions that are assumed by AWS services.

  • Amazon EC2 IAM role credentials are not subject to maximum session durations configured in the role.

  • To allow users to assume the current role again within a role session, specify the role ARN or AWS account ARN as a principal in the role trust policy. AWS services that provide compute resources such as Amazon EC2, Amazon ECS, Amazon EKS, and Lambda provide temporary credentials and automatically update these credentials. This ensures that you always have a valid set of credentials. For these services, it's not necessary to assume the current role again to obtain temporary credentials. However, if you intend to pass session tags or a session policy, you need to assume the current role again. To learn how to modify a role trust policy to add the principal role ARN or AWS account ARN, see Update a role trust policy .

Topics