Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Control access to Amazon STS with VPC endpoint policies

When you create an interface VPC endpoint for Amazon Security Token Service (Amazon STS), you can attach an endpoint policy. The policy controls which principals can use the endpoint and which Amazon STS actions they can perform. If you don't attach a policy, the endpoint uses the default policy that allows unrestricted access to all Amazon STS actions for all principals.

VPC endpoint policies don't grant permissions on their own. They act as an additional boundary that works alongside other policies. Both the endpoint policy and the caller's applicable policies must allow a request for it to succeed.

For more information about VPC endpoint policies, see Control access to VPC endpoints using endpoint policies in the Amazon VPC User Guide.

Default VPC endpoint policy

If you don't attach a custom policy when you create the endpoint, Amazon attaches the following default policy. This policy allows unrestricted access to the endpoint.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": "*",
            "Action": "*",
            "Resource": "*"
        }
    ]
}

To limit access to the endpoint, attach a custom endpoint policy.

Important considerations for Amazon STS VPC endpoint policies

Amazon STS handles requests from two fundamentally different types of callers. Your VPC endpoint policy must account for both types to avoid unintentionally blocking legitimate requests.

How Amazon STS evaluates VPC endpoint policies for federated callers

When a federated caller invokes AssumeRoleWithSAML or AssumeRoleWithWebIdentity through a VPC endpoint, the following applies:

We recommend using aws:ResourceOrgID or aws:ResourceAccount when writing VPC endpoint policy statements that must apply to federated callers, because these callers do not have principal-based condition keys available.

Condition keys available for Amazon STS VPC endpoint policies

The following table shows commonly used condition keys and their availability in the request context for each caller type when making requests through an Amazon STS VPC endpoint. Additional condition keys are available beyond those listed here.

Example: Allow all Amazon STS actions for your organization

The following endpoint policy restricts your Amazon STS VPC endpoint to your organization while supporting federated access. It allows all Amazon STS actions for authenticated principals in your organization and separately permits federated callers to assume roles within your organization. Federated callers (AssumeRoleWithSAML and AssumeRoleWithWebIdentity) require a separate statement because they don't have an aws:PrincipalOrgID in the request context.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowOrganizationPrincipals",
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": "sts:*",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:PrincipalOrgID": "o-exampleorgid"
                }
            }
        },
        {
            "Sid": "AllowFederatedAssumeRole",
            "Effect": "Allow",
            "Principal": "*",
            "Action": [
                "sts:AssumeRoleWithSAML",
                "sts:AssumeRoleWithWebIdentity"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceOrgID": "o-exampleorgid"
                }
            }
        }
    ]
}

The first statement uses "Principal": {"AWS": "*"} with aws:PrincipalOrgID to allow authenticated Amazon principals from your organization. The second statement uses "Principal": "*" to match federated callers and restricts the target role to your organization using aws:ResourceOrgID. The role's trust policy remains the primary control for which federated identities can assume which roles.

For more information about implementing network perimeter controls, see Building a data perimeter on Amazon and the data perimeter policy examples on the GitHub website.

Example: Allow all Amazon STS actions for specific accounts

The following endpoint policy allows all Amazon STS actions for principals in specific accounts. Use this policy when your accounts are not part of an organization. Federated callers are allowed in a separate statement because they don't have an aws:PrincipalAccount in the request context.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowSpecificAccountPrincipals",
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": "sts:*",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:PrincipalAccount": [
                        "111122223333",
                        "444455556666"
                    ]
                }
            }
        },
        {
            "Sid": "AllowFederatedAssumeRole",
            "Effect": "Allow",
            "Principal": "*",
            "Action": [
                "sts:AssumeRoleWithSAML",
                "sts:AssumeRoleWithWebIdentity"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": [
                        "111122223333",
                        "444455556666"
                    ]
                }
            }
        }
    ]
}

The first statement uses "Principal": {"AWS": "*"} with aws:PrincipalAccount to allow authenticated Amazon principals from the specified accounts. The second statement uses "Principal": "*" to match federated callers and restricts the target role to the same accounts using aws:ResourceAccount. The role's trust policy remains the primary control for which federated identities can assume which roles.

Example: Restrict to specific Amazon STS actions

The following endpoint policy allows only AssumeRole for authenticated principals and AssumeRoleWithSAML for federated callers, both scoped to roles in your organization.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowAssumeRoleByOrgPrincipals",
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": "sts:AssumeRole",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:PrincipalOrgID": "o-exampleorgid"
                }
            }
        },
        {
            "Sid": "AllowSAMLFederation",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "sts:AssumeRoleWithSAML",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceOrgID": "o-exampleorgid"
                }
            }
        }
    ]
}

This policy blocks other Amazon STS actions such as GetCallerIdentity, GetSessionToken, and AssumeRoleWithWebIdentity through this endpoint. Adjust the Action elements to match your requirements.

Example: Deny non-organization access while allowing federation

The following endpoint policy uses an explicit deny to block authenticated principals outside your organization, while preserving access for federated callers. This approach starts with a broad allow and adds a targeted deny statement.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowAll",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "*",
            "Resource": "*"
        },
        {
            "Sid": "DenyNonOrgPrincipals",
            "Effect": "Deny",
            "Principal": {
                "AWS": "*"
            },
            "Action": "sts:*",
            "Resource": "*",
            "Condition": {
                "StringNotEquals": {
                    "aws:PrincipalOrgID": "o-exampleorgid"
                }
            }
        }
    ]
}

The deny statement uses "Principal": {"AWS": "*"}, which scopes it to authenticated Amazon principals only. Federated callers (SAML and OIDC) are not Amazon principals and are not matched by this Principal element, so the deny does not apply to them. This approach avoids the need for complex Null or Bool conditions to carve out exceptions for federated callers.