assume-role

Returns a set of temporary security credentials that you can use to access Amazon Web Services resources that you might not normally have access to.

Refer to AWS help for descriptions of global parameters.

Synopsis

assume-role
 --role-arn <value>
 --role-session-name <value>
 [--duration-seconds <value>]

Options

--role-arn (string)

The Amazon Resource Name (ARN) of the role to assume.

--role-session-name (string)

An identifier for the assumed role session.

Use the role session name to uniquely identify a session when the same role is assumed by different principals or for different reasons. In cross-account scenarios, the role session name is visible to, and can be logged by the account that owns the role. The role session name is also used in the ARN of the assumed role principal. This means that subsequent cross-account API requests that use the temporary security credentials will expose the role session name to the external account in their CloudTrail logs.

The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric characters with no spaces. You can also include underscores or any of the following characters: =, ,, ., @, -.

--duration-seconds (integer)

The duration, in seconds, of the role session. The value specified can range from 900 seconds (15 minutes) up to the maximum session duration set for the role. The maximum session duration setting can have a value from 1 hour to 12 hours. If you specify a value higher than this setting or the administrator setting (whichever is lower), the operation fails. For example, if you specify a session duration of 12 hours, but your administrator set the maximum session duration to 6 hours, your operation fails.

Role chaining limits your Amazon Web Services CLI or Amazon Web Services API role session to a maximum of one hour. When you use the AssumeRole API operation to assume a role, you can specify the duration of your role session with the DurationSeconds parameter. You can specify a parameter value of up to 43,200 seconds (12 hours), depending on the maximum session duration setting for your role. However, if you assume a role using role chaining and provide a DurationSeconds parameter value greater than one hour, the operation fails. To learn how to view the maximum value for your role, refer to View the Maximum Session Duration Setting for a Role in the IAM User Guide.

By default, the value is set to 3600 seconds.

Examples

To assume a role

aws --endpoint-url https://sts.<base-domain-name> sts assume-role --role-arn arn:aws:iam::123456789012:role/ExampleRole1 --role-session-name session-example

Output:

{
    "AssumedRoleUser": {
        "AssumedRoleId": "AROA3XFRBF535PLBIFPI4:session-example",
        "Arn": "arn:aws:sts::123456789012:assumed-role/ExampleRole1/session-example"
    },
    "Credentials": {
        "SecretAccessKey": "9drTJvcXLB89EXAMPLELB8923FB892xMFI",
        "SessionToken": "AQoXdzELDDY////EXAMPLE/////Kcgo5OytwU=",
        "Expiration": "2016-03-15T00:05:07Z",
        "AccessKeyId": "ASIAJEXAMPLEXEG2JICEA"
    }
}

For more information, refer to Assuming a Role in the AWS CLI User Guide.

Output

Credentials -> (structure)

The temporary security credentials, which include an access key ID, a secret access key, and a security (or session) token.

Note

The size of the security token that STS API operations return is not fixed. We strongly recommend that you make no assumptions about the maximum size.

AccessKeyId -> (string)

The access key ID that identifies the temporary security credentials.

SecretAccessKey -> (string)

The secret access key that can be used to sign requests.

SessionToken -> (string)

The token that users must pass to the service API to use the temporary credentials.

Expiration -> (timestamp)

The date on which the current credentials expire.

AssumedRoleUser -> (structure)

The Amazon Resource Name (ARN) and the assumed role ID, which are identifiers that you can use to refer to the resulting temporary security credentials. For example, you can reference these credentials as a principal in a resource-based policy by using the ARN or assumed role ID. The ARN and ID include the RoleSessionName that you specified when you called AssumeRole.

AssumedRoleId -> (string)

A unique identifier that contains the role ID and the role session name of the role that is being assumed. The role ID is generated by Amazon Web Services when the role is created.

Arn -> (string)

The ARN of the temporary security credentials that are returned from the AssumeRole action. For more information about ARNs and how to use them in policies, refer to IAM Identifiers in the IAM User Guide.