Managing AWS STS in an AWS Region
By default, the AWS Security Token Service (AWS STS) is available as a global service, and all AWS STS requests
go to a single endpoint at https://sts.amazonaws.com
. AWS recommends using
Regional AWS STS endpoints instead of the global endpoint to reduce latency, build in
redundancy, and increase session token validity.
-
Reduce latency – By making your AWS STS calls to an endpoint that is geographically closer to your services and applications, you can access AWS STS services with lower latency and better response times.
-
Build in redundancy – You can limit the effects of a failure within a workload to a limited number of components with a predictable scope of impact containment. Using regional AWS STS endpoints lets you align the scope of your components with the scope of your session tokens. For more information about this reliability pillar, see Use fault isolation to protect your workload in the AWS Well-Architected Framework.
-
Increase session token validity – Session tokens from Regional AWS STS endpoints are valid in all AWS Regions. Session tokens from the global STS endpoint are valid only in AWS Regions that are enabled by default. If you intend to enable a new Region for your account, you can use session tokens from Regional AWS STS endpoints. If you choose to use the global endpoint, you must change the Region compatibility of AWS STS session tokens for the global endpoint. Doing so ensures that tokens are valid in all AWS Regions.
Managing global endpoint session tokens
Most AWS Regions are enabled for operations in all AWS services by default. Those Regions are automatically activated for use with AWS STS. Some Regions, such as Asia Pacific (Hong Kong), must be manually enabled. To learn more about enabling and disabling AWS Regions, see Managing AWS Regions in the AWS General Reference. When you enable these AWS Regions, they are automatically activated for use with AWS STS. You cannot activate the AWS STS endpoint for a Region that is disabled. Tokens that are valid in all AWS Regions include more characters than tokens that are valid in Regions that are enabled by default. Changing this setting might affect existing systems where you temporarily store tokens.
You can change this setting using the AWS Management Console, AWS CLI, or AWS API.
To change the Region compatibility of session tokens for the global endpoint (console)
-
Sign in as a root user or a user with permissions to perform IAM administration tasks. To change the compatibility of session tokens, you must have a policy that allows the
iam:SetSecurityTokenServicePreferences
action. -
Open the IAM console
. In the navigation pane, choose Account settings. -
Under Security Token Service (STS) section Session Tokens from the STS endpoints. The Global endpoint indicates
Valid only in AWS Regions enabled by default
. Choose Change. -
In the Change region compatibility dialog box, select All AWS Regions. Then choose Save changes.
Note
Tokens that are valid in all AWS Region include more characters than tokens that are valid in Regions that are enabled by default. Changing this setting might affect existing systems where you temporarily store tokens.
To change the Region compatibility of session tokens for the global endpoint (AWS CLI)
Set the session token version. Version 1 tokens are valid only in AWS Regions that are available by default. These tokens do not work in manually enabled Regions, such as Asia Pacific (Hong Kong). Version 2 tokens are valid in all Regions. However, version 2 tokens include more characters and might affect systems where you temporarily store tokens.
To change the Region compatibility of session tokens for the global endpoint (AWS API)
Set the session token version. Version 1 tokens are valid only in AWS Regions that are available by default. These tokens do not work in manually enabled Regions, such as Asia Pacific (Hong Kong). Version 2 tokens are valid in all Regions. However, version 2 tokens include more characters and might affect systems where you temporarily store tokens.
Activating and deactivating AWS STS in an AWS Region
When you activate STS endpoints for a Region, AWS STS can issue temporary credentials to users and roles in your account that make an AWS STS request. Those credentials can then be used in any Region that is enabled by default or is manually enabled. For Regions that are enabled by default, you must activate the Regional STS endpoint in the account where the temporary credentials are generated. It does not matter whether a user is signed into the same account or a different account when they make the request. For Regions that are manually enabled, you must activate the Region in both the account making the request and the account where the temporary credentials are generated.
For example, imagine a user in account A wants to send an sts:AssumeRole
API request to the AWS STS Regional endpoint
https://sts.us-east-2.amazonaws.com
. The request is for
temporary credentials for the role named Developer
in account B. Because the
request is to create credentials for an entity in account B, account B must activate the
us-east-2
Region. Users from account A (or any other
account) can call the us-east-2
endpoint to request credentials
for account B whether or not the Region is activated in their accounts.
Note
Active Regions are available to everyone that uses temporary credentials in that
account. To control which IAM users or roles can access the Region, use the
aws:RequestedRegion
condition key in your permissions policies.
To activate or deactivate AWS STS in a Region that is enabled by default (console)
-
Sign in as a root user or a user with permissions to perform IAM administration tasks.
-
Open the IAM console
and in the navigation pane choose Account settings . -
In the Security Token Service (STS) section Endpoints, find the Region that you want to configure, and then choose Active or Inactive in the STS status column.
-
In the dialog box that opens, choose Activate or Deactivate.
For Regions that must be enabled, we activate AWS STS automatically when you enable the Region. After you enable a Region, AWS STS is always active for the Region and you cannot deactivate it. To learn how to enable a Region, see Managing AWS Regions in the AWS General Reference.
Writing code to use AWS STS Regions
After you activate a Region, you can direct AWS STS API calls to that Region. The
following Java code snippet demonstrates how to configure an
AWSSecurityTokenService
object to make requests to the Europe (Ireland)
(eu-west-1) Region.
EndpointConfiguration regionEndpointConfig = new EndpointConfiguration("https://sts.eu-west-1.amazonaws.com", "eu-west-1"); AWSSecurityTokenService stsRegionalClient = AWSSecurityTokenServiceClientBuilder.standard() .withCredentials(credentials) .withEndpointConfiguration(regionEndpointConfig) .build();
AWS STS recommends that you make calls to a Regional endpoint. To learn how to manually enable a Region, see Managing AWS Regions in the AWS General Reference.
In the example, the first line instantiates an EndpointConfiguration
object
called regionEndpointConfig
, passing the URL of the endpoint and the
AWS Region as the parameters.
To learn how to set AWS STS regional endpoints using an environment variable for AWS SDKs, see AWS STS Regionalized endpoints in the AWS SDKs and Tools Reference Guide.
For all other language and programming environment combinations, refer to the documentation for the relevant SDK
Regions and endpoints
The following table lists the Regions and their endpoints. It indicates which ones are activated by default and which ones you can activate or deactivate.
Region name | Endpoint | Active by default | Manually activate/deactivate |
---|---|---|---|
--Global-- | sts.amazonaws.com | ||
US East (Ohio) | sts.us-east-2.amazonaws.com | ||
US East (N. Virginia) | sts.us-east-1.amazonaws.com | ||
US West (N. California) | sts.us-west-1.amazonaws.com | ||
US West (Oregon) | sts.us-west-2.amazonaws.com | ||
Africa (Cape Town) | sts.af-south-1.amazonaws.com | ||
Asia Pacific (Hong Kong) | sts.ap-east-1.amazonaws.com | ||
Asia Pacific (Hyderabad) | sts.ap-south-2.amazonaws.com | ||
Asia Pacific (Jakarta) | sts.ap-southeast-3.amazonaws.com | ||
Asia Pacific (Melbourne) | sts.ap-southeast-4.amazonaws.com | ||
Asia Pacific (Mumbai) | sts.ap-south-1.amazonaws.com | ||
Asia Pacific (Osaka) | sts.ap-northeast-3.amazonaws.com | ||
Asia Pacific (Seoul) | sts.ap-northeast-2.amazonaws.com | ||
Asia Pacific (Singapore) | sts.ap-southeast-1.amazonaws.com | ||
Asia Pacific (Sydney) | sts.ap-southeast-2.amazonaws.com | ||
Asia Pacific (Tokyo) | sts.ap-northeast-1.amazonaws.com | ||
Canada (Central) | sts.ca-central-1.amazonaws.com | ||
China (Beijing) | sts.cn-north-1.amazonaws.com.cn | ||
China (Ningxia) | sts.cn-northwest-1.amazonaws.com.cn | ||
Europe (Frankfurt) | sts.eu-central-1.amazonaws.com | ||
Europe (Ireland) | sts.eu-west-1.amazonaws.com | ||
Europe (London) | sts.eu-west-2.amazonaws.com | ||
Europe (Milan) | sts.eu-south-1.amazonaws.com | ||
Europe (Paris) | sts.eu-west-3.amazonaws.com | ||
Europe (Spain) | sts.eu-south-2.amazonaws.com | ||
Europe (Stockholm) | sts.eu-north-1.amazonaws.com | ||
Europe (Zurich) | sts.eu-central-2.amazonaws.com | ||
Israel (Tel Aviv) | sts.il-central-1.amazonaws.com | ||
Middle East (Bahrain) | sts.me-south-1.amazonaws.com | ||
Middle East (UAE) | sts.me-central-1.amazonaws.com | ||
South America (São Paulo) | sts.sa-east-1.amazonaws.com |
¹You must enable the Region to use it. This automatically activates AWS STS. You cannot manually activate or deactivate AWS STS in these Regions.
²To use AWS in China, you need an account and credentials specific to AWS in China.
AWS CloudTrail and Regional endpoints
Calls to regional and global endpoints are logged in the tlsDetails
field
in AWS CloudTrail. Calls to regional endpoints, such as
us-east-2.amazonaws.com
, are logged in CloudTrail to their
appropriate region. Calls to the global endpoint, sts.amazonaws.com
, are
logged as calls to a global service. Events for global AWS STS endpoints are logged to
us-east-1.
Note
tlsDetails
can only be viewed for services that support this field. See
Services
that support TLS details in CloudTrail in the AWS CloudTrail User
Guide
For more information, see Logging IAM and AWS STS API calls with AWS CloudTrail.