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 .