
assume-role
***********


DESCRIPTION
===========

The "assume-role" action returns a set of temporary security
credentials that you can use to access resources that are defined in
the role's policy. The returned credentials consist of an Access Key
ID, a Secret Access Key, and a security token.

**Important:** Only IAM users can assume a role. If you use AWS
account credentials to call AssumeRole, access is denied.

The credentials are valid for the duration that you specified when
calling "assume-role" , which can be from 15 minutes to 1 hour.

When you assume a role, you have the privileges that are defined in
the role. You can further restrict the privileges by passing a policy
when calling "assume-role" .

To assume a role, you must be an IAM user from a trusted entity and
have permission to call "assume-role" . Trusted entites are defined
when the IAM role is created. Permission to call "assume-role" is
defined in your or your group's IAM policy.


SYNOPSIS
========

   aws sts assume-role
     --role-arn <value>
     --role-session-name <value>
     [--policy <value>]
     [--duration-seconds <value>]
     [--external-id <value>]


REQUIRED PARAMETERS
===================

"--role-arn"  (string)
   The Amazon Resource Name (ARN) of the role that the caller is
   assuming.

"--role-session-name"  (string)
   An identifier for the assumed role session. The session name is
   included as part of the "AssumedRoleUser" .


OPTIONAL PARAMETERS
===================

"--policy"  (string)
   A supplemental policy that can be associated with the temporary
   security credentials. The caller can restrict the permissions that
   are available on the role's temporary security credentials to
   maintain the least amount of privileges. When a service call is
   made with the temporary security credentials, both the role's
   permission policy and supplemental policy are checked. For more
   information about how permissions work in the context of temporary
   credentials, see *Controlling Permissions in Temporary Credentials
   < http://docs.amazonwebservices.com/IAM/latest/UserGuide/TokenPermi
   ssions.html>* _ .

"--duration-seconds"  (integer)
   The duration, in seconds, of the role session. The value can range
   from 900 seconds (15 minutes) to 3600 seconds (1 hour). By default,
   the value is set to 3600 seconds (1 hour).

"--external-id"  (string)
   A unique identifier that is generated by a third party for each of
   their customers. For each role that the third party can assume,
   they should instruct their customers to create a role with the
   external ID that was generated by the third party. Each time the
   third party assumes the role, they must pass the customer's correct
   external ID. The external ID is useful in order to help third
   parties bind a role to the customer who created it. For more
   information about the external ID, see About the External ID in
   *Using Temporary Security Credentials* .
