View a markdown version of this page

GetScopedCredentials - AWS Security Token Service

GetScopedCredentials

Returns a set of temporary security credentials that are scoped down from the caller's existing temporary security credentials. GetScopedCredentials preserves the caller's identity while narrowing the permissions and optionally shortening the session lifetime.

For a comparison of GetScopedCredentials with the other API operations that produce temporary security credentials, see Requesting Temporary Security Credentials and Compare AWS STS credentials in the IAM User Guide.

Credential requirements

You can only call GetScopedCredentials with temporary security credentials, for example, credentials from an assumed role or a federated session. You cannot call it with IAM user credentials or root credentials. If you want to scope down IAM user credentials, first call GetSessionToken to get temporary security credentials, and then call GetScopedCredentials with those credentials.

Note

The GetScopedCredentials API is not available on the AWS STS Global endpoint.

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

DurationSeconds

The duration, in seconds, of the resulting scoped down credentials. The value can range from 1 second to 129,600 seconds (36 hours).

If you do not specify this value, the scoped down credentials will inherit the calling session's expiration time.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 129600.

Required: No

MinimumSessionTokenSize

The minimum size, in bytes, of the session token that STS issues for the request. STS increases the session token to at least this size, regardless of its actual content. The value must not exceed 4,096 bytes. When set to 0 or not specified, the session token size is unchanged.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 4096.

Required: No

Policy

An IAM policy in JSON format that you want to use as a scope down policy.

A request must provide at least one of Policy or DurationSeconds. Both parameters are optional individually, but you must specify at least one of them.

The resulting session's permissions are the intersection of the calling session's existing permissions and this scope down policy. You cannot use this scope down policy to grant more permissions than the calling session already has.

The plaintext of the scope down policy cannot exceed 2,048 characters. The JSON policy characters can be any ASCII character from the space character to the end of the valid character list (\u0020 through \u00FF). It can also include the tab (\u0009), linefeed (\u000A), and carriage return (\u000D) characters.

Note

An internal conversion compresses the inline scope down policy into a packed binary format that has a separate limit. If the packed policy exceeds this limit, the request fails with PackedPolicyTooLarge.

If the document is not valid IAM policy JSON, the request fails with MalformedPolicyDocument.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: [\u0009\u000A\u000D\u0020-\u00FF]+

Required: No

ScopedSessionDescription

A caller-supplied description of the scoped session. The value cannot exceed 256 characters. This description is logged to AWS CloudTrail for the request, so you can use it to record the purpose of the scoped session.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 256.

Pattern: [\u0009\u000A\u000D\u0020-\u007E\u00A1-\u00FF]*

Required: No

Response Elements

The following elements are returned by the service.

Credentials

The temporary security credentials for the scoped down session, which include an access key ID, a secret access key, and a security token.

Note

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

Type: Credentials object

ScopedPoliciesCount

GetScopedCredentials can be called recursively and ScopedPoliciesCount specifies the number of scope down policies applied to the session. Each recursive call adds another scope down policy layer. A maximum of 3 scope down policy layers are allowed per session. If a session already has 3 GetScopedCredentials scope-down policies, a subsequent GetScopedCredentials call that supplies a Policy (attempting to append a fourth scope-down policy) is denied.

Type: Integer

Valid Range: Minimum value of 0.

SessionInfo

Metadata about the resulting scoped session, including its identifier and ARN. Because the identity does not change, the identifiers reflect the same principal and session name as the calling session.

Type: ScopedSession object

SessionTokenSize

The size, in bytes, of the session token returned in the Credentials for this response.

Type: Integer

Valid Range: Minimum value of 0.

SessionTokenUtilization

The percentage (0-100) of the maximum allowed session token size that the returned session token consumes.

Type: Integer

Valid Range: Minimum value of 0.

SourceIdentity

The source identity of the calling session, carried forward unchanged. This operation never sets or modifies the source identity; it reflects the value established when the source identity was first set. For more information, see Monitor and control actions taken with assumed roles in the IAM User Guide.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 256.

Pattern: [\w+=,.@-]*

Errors

For information about the errors that are common to all actions, see Common Error Types.

InsufficientSessionLifetime

The request was rejected because the requested DurationSeconds is greater than the remaining lifetime of the calling session. GetScopedCredentials cannot extend a session beyond its original expiration. Request a duration that is less than or equal to the calling session's remaining lifetime, or omit DurationSeconds to inherit it.

HTTP Status Code: 400

InvalidSubjectCredentials

The request was rejected because the session used to call GetScopedCredentials is not a valid session. The calling session's credentials could not be validated or resolved.

HTTP Status Code: 400

MalformedPolicyDocument

The request was rejected because the policy document was malformed. The error message describes the specific error.

HTTP Status Code: 400

PackedPolicyTooLarge

The request was rejected because the session token exceeded the maximum allowed size. The error message reports the session token size and the maximum allowed size, both in bytes. Session policies and session tags add to the session token size. For more information, see Passing Session Tags in AWS STS in the IAM User Guide.

You might receive this error even though you meet the individual session policy and session tag limits. Monitor SessionTokenUtilization to track how close the session token is to the maximum allowed size. For more information, see IAM and AWS STS Entity Character Limits in the IAM User Guide.

HTTP Status Code: 400

Examples

Example

This example illustrates one usage of GetScopedCredentials.

Sample Request

https://sts.us-east-1.amazonaws.com/ ?Version=2011-06-15 &Action=GetScopedCredentials &DurationSeconds=3600 &Policy=JSON-IAM-POLICY &AUTHPARAMS

Sample Response

<GetScopedCredentialsResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/"> <GetScopedCredentialsResult> <Credentials> <AccessKeyId>ASIAIOSFODNN7EXAMPLE</AccessKeyId> <SecretAccessKey>wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY</SecretAccessKey> <SessionToken> AQoDYXdzEPT//////////wEXAMPLEtc764bNrC9SAPBSM22wDOk4x4HIZ8j4FZTwdQW LWsKWHGBuFqwAeMicRXmxfpSPfIeoIYRqTflfKD8YUuwthAx7mSEI/qkPpKPi/kMcGd QrmGdeehM4IC1NtBmUpp2wUE8phUZampKsburEDy0KPkyQDYwT7WZ0wq5VSXDvp75YU 9HFvlRd8Tx6q6fE8YQcHNVXAkiY9q6d+xo0rKwT38xVqr7ZD0u0iPPkUL64lIZbqBAz +scqKmlzm8FDrypNC9Yjc8fPOLn9FX9KSYvKTr4rvx3iSIlTJabIQwj2ICCR/oLxBA== </SessionToken> <Expiration>2019-11-09T13:34:41Z</Expiration> </Credentials> <ScopedPoliciesCount>1</ScopedPoliciesCount> <SessionInfo> <ScopedSessionId>AROAEXAMPLEID:example-session</ScopedSessionId> <Arn>arn:aws:sts::123456789012:assumed-role/example-role/example-session</Arn> </SessionInfo> <SourceIdentity>example-source-identity</SourceIdentity> </GetScopedCredentialsResult> <ResponseMetadata> <RequestId>c6104cbe-af31-11e0-8154-cbc7ccf896c7</RequestId> </ResponseMetadata> </GetScopedCredentialsResponse>

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: