Using IAM roles - AWS Identity and Access Management
View the maximum session duration setting for a role

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 | 1hr | 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 rotate 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

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)

  1. In the navigation pane of the IAM console, choose Roles.

  2. Choose the name of the role that you want to view.

  3. 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)

  1. 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:

  2. 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)

  1. 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:

  2. To view the role's maximum session duration, run the following operation. Then view the maximum session duration parameter.