Using IAM roles
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 a groups or to the user 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.
Comparing 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 a web identity 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 a web identity 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 Modifying a role. 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 View the maximum session duration setting
for a role later in this page.
Notes
-
The maximum session duration setting does not limit sessions that are assumed by AWS services.
-
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 Modifying a role trust policy (console).
Topics
- View the maximum session duration setting for a role
- Granting a user permissions to switch roles
- Granting a user permissions to pass a role to an AWS service
- Switching to a role (console)
- Switching to an IAM role (AWS CLI)
- Switching to an IAM role (Tools for Windows PowerShell)
- Switching to an IAM role (AWS API)
- Using an IAM role to grant permissions to applications running on Amazon EC2 instances
- Revoking IAM role temporary security credentials
View the maximum session duration setting for a role
You can specify the maximum session duration for a role using the AWS Management Console or by using
the AWS CLI or AWS API. When you use an AWS CLI or API operation to assume a role, you can
specify a value for the DurationSeconds
parameter. You can use this parameter to
specify the duration of the role session, from 900 seconds (15 minutes) up to the maximum
session duration setting for the role. Before you specify the parameter, you should view this
setting for your role. If you specify a value for the DurationSeconds
parameter
that is higher than the maximum setting, the operation fails.
To view a role's maximum session duration (console)
-
In the navigation pane of the IAM console, choose Roles.
-
Choose the name of the role that you want to view.
-
Next to Maximum session duration, view the maximum session length that is granted for the role. This is the maximum session duration that you can specify in your AWS CLI, or API operation.
To view a role's maximum session duration setting (AWS CLI)
-
If you don't know the name of the role that you want to assume, run the following command to list the roles in your account:
-
To view the role's maximum session duration, run the following command. Then view the maximum session duration parameter.
To view a role's maximum session duration setting (AWS API)
-
If you don't know the name of the role that you want to assume, call the following operation to list the roles in your account:
-
To view the role's maximum session duration, run the following operation. Then view the maximum session duration parameter.