Amazon STS Regionalized endpoints - Amazon SDKs and Tools
Compatibility with Amazon SDKs
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).

Amazon STS Regionalized endpoints

By default, Amazon Security Token Service (Amazon STS) is available as a global service, and all Amazon STS requests go to a single endpoint at https://sts.amazonaws.com. Global requests map to the US East (N. Virginia) Region. Amazon recommends using Regional Amazon STS endpoints instead of the global endpoint. For more information on Amazon STS endpoints, Endpoints in the Amazon Security Token Service API Reference.

Configure this functionality by using the following:

sts_regional_endpoints - shared Amazon config file setting
AWS_STS_REGIONAL_ENDPOINTS - environment variable

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

Default value: legacy

Note

All new SDK major versions releasing after July 2022 will default to regional. 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 Amazon STS endpoint, sts.amazonaws.com, for the following Amazon Regions: ap-northeast-1, ap-south-1, ap-southeast-1, ap-southeast-2, aws-global, ca-central-1, eu-central-1, eu-north-1, eu-west-1, eu-west-2, eu-west-3, sa-east-1, us-east-1, us-east-2, us-west-1, and us-west-2. All other Regions automatically use their respective Regional endpoint.

  • regional – The SDK or tool always uses the Amazon STS endpoint for the currently configured Region. For example, if the client is configured to use us-west-2, all calls to Amazon STS are made to the Regional endpoint sts.us-west-2.amazonaws.com, instead of the global sts.amazonaws.com endpoint. To send a request to the global endpoint while this setting is enabled, you can set the Region to aws-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

Compatibility with Amazon SDKs

The following SDKs support the features and settings described in this topic. Any partial exceptions are noted. Any JVM system property settings are supported by the Amazon SDK for Java and the Amazon SDK for Kotlin only.

SDK Supported Notes or more information
Amazon CLI v2 Partial Default value is regional.
SDK for C++ Partial Environment variable and config file setting not supported. SDK performs with regional setting.
SDK for Go V2 (1.x) Yes
SDK for Go 1.x (V1) Yes To use shared config file settings, you must turn on loading from the config file; see Sessions.
SDK for Java 2.x Yes
SDK for Java 1.x Yes
SDK for JavaScript 3.x Yes
SDK for JavaScript 2.x Yes
SDK for Kotlin No
SDK for .NET 3.x Yes
SDK for PHP 3.x Yes
SDK for Python (Boto3) Yes
SDK for Ruby 3.x Yes
SDK for Rust Yes
Tools for PowerShell Yes