Controlling access with IAM policies
IAM provides multiple policy types to control access to the outbound identity federation feature. You can use identity-based policies to control which IAM principals can request tokens and enforce specific token properties such as audience, lifetimes, signing algorithms, subject selection, and Scope values. Service Control Policies (SCPs) enable you to enforce organization-wide restrictions on token generation across all accounts in your AWS Organizations. Resource Control Policies (RCPs) control access at the resource level. You can also use VPC endpoint policies to restrict which principals can access the AWS STS GetWebIdentityToken API through your VPC endpoints, adding network-level controls to your security posture. This section explains how to implement fine-grained access controls using these policy types and condition keys.
The permissions required to call GetWebIdentityToken depend on the properties included in the request:
-
Every token request requires
sts:GetWebIdentityToken. Grant this permission through an identity-based policy attached to an IAM user or role. -
A request that includes tags also requires
sts:TagGetWebIdentityToken. -
A request that includes Scope also requires
sts:SetWebIdentityTokenScope. This permission does not replacests:GetWebIdentityToken. A request that omits Scope does not requirests:SetWebIdentityTokenScope.
Selecting a SubjectMode does not require a separate action permission. To restrict which mode a principal can select, apply the sts:SubjectMode condition key to the policy statement that allows sts:GetWebIdentityToken.
-
Use the sts:IdentityTokenAudience condition key to limit which external services can receive tokens.
-
Use the sts:DurationSeconds condition key to enforce maximum token lifetimes.
-
Use the sts:SigningAlgorithm condition key to require specific cryptographic algorithms.
-
Use the
sts:SubjectModecondition key to restrict which identity AWS STS places insub.AWSIdentityselects the ARN of the requesting IAM principal.OriginIdentityselects the TIP Subject carried by the calling session. For the shared context model and trusted identity sources, see trusted identity propagation (TIP). When the request omitsSubjectMode, AWS STS usesAWSIdentityas the effective mode and evaluates thests:SubjectModecondition key with the valueAWSIdentity. -
Use the multivalued
sts:IdentityTokenScopecondition key to restrict the individual values supplied in Scope. AWS STS represents each distinct space-delimited Scope value as a separate condition-key value. Use a multivalued condition operator when the policy must evaluate multiple requested values. -
Use the aws:RequestTag condition key compare the tag key-value pair that was passed in the request with the tag pair that you specify in the policy.
-
Use the aws:TagKeys condition key to compare the tag keys in a request with the keys that you specify in the policy.
Refer to IAM and AWS STS condition keys to learn more about the condition keys available in IAM policies.
This sample identity policy combines multiple condition keys:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowTokenGenerationWithRestrictions", "Effect": "Allow", "Action": "sts:GetWebIdentityToken", "Resource": "*", "Condition": { "ForAllValues:StringEquals": { "sts:IdentityTokenAudience": [ "https://api1.example.com", "https://api2.example.com" ] }, "Null": { "sts:IdentityTokenAudience": "false" }, "NumericLessThanEquals": { "sts:DurationSeconds": 300 }, "StringEquals": { "sts:SigningAlgorithm": "ES384" } } } ] }
ForAllValues:StringEquals requires every audience in the request to match an approved value. A request that includes an additional unapproved audience does not match this Allow statement. Because ForAllValues:StringEquals is also true when the key is absent, include a Null condition set to false to require sts:IdentityTokenAudience to be present and nonempty. For more information, see Set operators for multivalued context keys.
Control the subject identity
sts:SubjectMode is a single-valued condition key. Use it in a policy condition to control which identity a caller can select for the standard sub claim:
-
AWSIdentityselects the ARN of the IAM principal that requested the token. -
OriginIdentityselects the TIP Subject carried by the calling session.
The following policy allows GetWebIdentityToken only when the request selects OriginIdentity and the audience matches the external service. When the request omits SubjectMode, AWS STS uses AWSIdentity as the effective mode. Therefore, a request that omits SubjectMode does not match this Allow statement.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowTokenWithOriginIdentityForExternalService", "Effect": "Allow", "Action": "sts:GetWebIdentityToken", "Resource": "*", "Condition": { "StringEquals": { "sts:SubjectMode": "OriginIdentity" }, "ForAllValues:StringEquals": { "sts:IdentityTokenAudience": "https://api.example.com" } } } ] }
This policy authorizes the subject mode, but it does not create or attach TIP context. The credentials used to call AWS STS must meet the OriginIdentity requirements. Otherwise, a request that selects OriginIdentity fails even when the IAM policy allows that mode. For the resulting claim behavior, see Understanding token claims.
Control Scope values
Scope is an optional request value that represents what the caller requests from the external service. AWS STS copies an accepted Scope value into the token, but does not interpret it or grant permissions based on it. The external service determines what each value means and whether the identity in sub can use it.
When a request includes Scope, AWS STS performs an additional authorization check for sts:SetWebIdentityTokenScope. This is not a separate API operation. The principal needs both sts:GetWebIdentityToken and sts:SetWebIdentityTokenScope. A request that omits Scope does not require or invoke the sts:SetWebIdentityTokenScope authorization check.
Scope can be specified only when SubjectMode is OriginIdentity and the request specifies exactly one audience. IAM permissions cannot make a request that violates these requirements valid.
Although Scope is one space-delimited request string, AWS STS represents each distinct Scope value separately in the multivalued sts:IdentityTokenScope condition key. Scope values are case-sensitive when you use case-sensitive string operators. Use a multivalued condition operator to evaluate them.
The following policy allows a token request with SubjectMode set to OriginIdentity for one audience and restricts Scope to the read and write values. ForAllValues:StringEquals requires every requested Scope value to match an allowed value.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowTokenWithOriginIdentityForExternalService", "Effect": "Allow", "Action": "sts:GetWebIdentityToken", "Resource": "*", "Condition": { "StringEquals": { "sts:SubjectMode": "OriginIdentity" }, "ForAllValues:StringEquals": { "sts:IdentityTokenAudience": "https://api.example.com" } } }, { "Sid": "AllowApprovedScopeValues", "Effect": "Allow", "Action": "sts:SetWebIdentityTokenScope", "Resource": "*", "Condition": { "StringEquals": { "sts:SubjectMode": "OriginIdentity" }, "ForAllValues:StringEquals": { "sts:IdentityTokenScope": [ "read", "write" ] } } } ] }
The AllowApprovedScopeValues statement matches Scope values such as read and write read. It does not match read delete because delete is not in the allowed set. If the request includes tags, add the existing sts:TagGetWebIdentityToken permission as appropriate.
The permissions on this page control the outbound GetWebIdentityToken request; they do not attach TIP context to the calling session. To control TIP context attachment, including use of sts:SetContext, see Control TIP for IAM federation with IAM policies.
Best practices
Follow these recommendations to securely federate your AWS identities to external services.
-
Use short token lifetimes: Request tokens with the shortest lifetime that meets your operational needs.
-
Grant least-privilege permissions: Grant
sts:GetWebIdentityTokenonly to IAM principals that require it. Grantsts:TagGetWebIdentityTokenandsts:SetWebIdentityTokenScopeonly when callers need the corresponding optional request properties. -
Restrict token properties: Use IAM condition keys to limit signing algorithms, audiences, token lifetimes, permitted
SubjectModevalues, and Scope values. When you permit Scope, usests:IdentityTokenScopeto restrict every requested value. -
Preserve default subject compatibility: If an external service expects
subto contain an IAM principal ARN, omitSubjectModeor restrict it toAWSIdentity. -
Validate tokens and claims in external services: Validate the token signature and relevant claims, including issuer (
iss), subject (sub), audience (aud), expiration (exp), and the AWS identity and session-context claims your authorization model uses. If the token includesscope, independently determine what each value permits. WhenSubjectModeisOriginIdentity, validatesubtogether withissand eitherorigin_identity.issuerororigin_identity.federated_provider_arn. In this mode,principal_idunder thehttps://sts.amazonaws.com/namespace identifies the IAM principal that requested the token. Validateprincipal_idwhen your authorization model also depends on that principal. -
Plan for SAML signing-key rotation: For a TIP session established through SAML federation,
origin_identity.issuerchanges when the identity provider rotates its signing certificate. Update approved issuer values before rotation, or useorigin_identity.federated_provider_arnwhen the external service needs a stable identifier for the configured SAML provider.