AWS STS Regional endpoints - AWS SDKs and Tools (original) (raw)

AWS Security Token Service (AWS STS) is available both as a global and Regional service. Some of AWS SDKs and CLIs use the global service endpoint (https://sts.amazonaws.com) by default, while some use the Regional service endpoints (https://sts.`{region_identifier}`.`{partition_domain}`). In Regions that are enabled by default, requests to the AWS STS global endpoint are automatically served in the same Region where the request originates. In opt-in Regions, requests to the AWS STS global endpoint are served by a single AWS Region, US East (N. Virginia). For more information on AWS STS endpoints, see Endpoints in the_AWS Security Token Service API Reference_ or Manage AWS STS in an AWS Region in the AWS Identity and Access Management User Guide.

It is an AWS best practice to use Regional endpoints whenever possible and to configure your AWS Region. Customers in partitions other than commercial must use Regional endpoints. Not all SDKs and tools support this setting, but all have defined behavior around global and Regional endpoints. See the following section for more information.

Note

AWS has made changes to the AWS Security Token Service (AWS STS) global endpoint (https://sts.amazonaws.com) in Regions enabled by default to enhance its resiliency and performance. AWS STS requests to the global endpoint are automatically served in the same AWS Region as your workloads. These changes will not be deployed to opt-in Regions. We recommend that you use the appropriate AWS STS regional endpoints. For more information, see AWS STS global endpoint changes in the AWS Identity and Access Management User Guide.

For SDKs and tools that support this setting, customers can configure the functionality by using the following:

sts_regional_endpoints - shared AWS config file setting

AWS_STS_REGIONAL_ENDPOINTS - environment variable

This setting specifies how the SDK or tool determines the AWS service endpoint that it uses to talk to the AWS Security Token Service (AWS STS).

Default value: legacy

Note

All new SDK major versions releasing after July 2022 will default toregional. New SDK major versions might remove this setting and use regional behavior. To reduce future impact regarding this change, we recommend you start using regional in your application when possible.

Valid values: (Recommended value: regional)

• legacy – Uses the global AWS STS endpoint,sts.amazonaws.com.
• regional – The SDK or tool always uses the AWS STS endpoint for the currently configured Region. For example, if the client is configured to useus-west-2, all calls to AWS STS are made to the Regional endpoint sts.us-west-2.amazonaws.com, instead of the globalsts.amazonaws.com endpoint. To send a request to the global endpoint while this setting is enabled, you can set the Region toaws-global.

Example of setting these values in the config file:

[default]
sts_regional_endpoints = regional

Linux/macOS example of setting environment variables via command line:

export AWS_STS_REGIONAL_ENDPOINTS=regional

Windows example of setting environment variables via command line:

setx AWS_STS_REGIONAL_ENDPOINTS regional

Support by AWS SDKs and tools

Note

It is an AWS best practice to use Regional endpoints whenever possible and to configure your AWS Region.

The table that follows summarizes, for your SDK or tool:

• Supports setting: Whether the shared config file variable and environment variable for STS Regional endpoints are supported.
• Default setting value: The default value of the setting if it is supported.
• Default service client target STS Endpoint: What default endpoint is used by the client even if the setting to change it is not available.
• Service client fallback behavior: What the SDK does when it is supposed to use a Regional endpoint but no Region has been configured. This is the behavior regardless of if it is using a Regional endpoint because of a default or because regional has been selected by the setting.

The table also uses the following values:

• Global endpoint:https://sts.amazonaws.com.
• Regional endpoint: Based on the configuredAWS Region used by your application.
• us-east-1 (Regional): Uses theus-east-1 Region endpoint but with longer session tokens than typical global requests.