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.
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
PolicyorDurationSeconds. 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.
NoteAn 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.
NoteThe 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
-
GetScopedCredentialscan be called recursively andScopedPoliciesCountspecifies 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 3GetScopedCredentialsscope-down policies, a subsequentGetScopedCredentialscall that supplies aPolicy(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
DurationSecondsis greater than the remaining lifetime of the calling session.GetScopedCredentialscannot extend a session beyond its original expiration. Request a duration that is less than or equal to the calling session's remaining lifetime, or omitDurationSecondsto inherit it.HTTP Status Code: 400
- InvalidSubjectCredentials
-
The request was rejected because the session used to call
GetScopedCredentialsis 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
SessionTokenUtilizationto 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: