AWS Identity and Access Management
User Guide

Using IAM Roles

Before an IAM 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 one of an IAM user's groups or to the user itself to grant the necessary permissions. This section describes how to grant users permission to use a role, and then how the user can switch to a role using the AWS Management Console, the Tools for Windows PowerShell, the AWS Command Line Interface (AWS CLI) and the AssumeRole API.

Important

If you create a role programmatically instead of in the IAM console, then 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 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.

Comparing methods for using roles

Method Who can assume the role Method to specify credential lifetime Credential lifetime (min | max | default)
AWS Management Console IAM user (by switching roles) None 1h | 1h | 1h
assume-role CLI or AssumeRole API operation IAM 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 IAM 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.

² The maximum session duration is a setting that you can apply to a role from the console, the AWS CLI, or the API. This setting specifies the maximum session duration for the role when it is assumed from the CLI or API. This setting can have a value from 1 hour to 12 hours. For details about 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. 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.

View the Maximum Session Duration Setting for a Role

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 CLI/API 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 CLI/API session duration, view the maximum session length 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.