Amazon STS Regional endpoints - Amazon SDKs and Tools
Support by Amazon SDKs and tools
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 Regional endpoints

Note

For help in understanding the layout of settings pages, or in interpreting the Support by Amazon SDKs and tools table that follows, see Understanding the settings pages of this guide.

Amazon Security Token Service (Amazon STS) is available both as a global and Regional service. Some of Amazon 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 Amazon STS global endpoint are automatically served in the same Region where the request originates. In opt-in Regions, requests to the Amazon STS global endpoint are served by a single Amazon Web Services Region, US East (N. Virginia). For more information on Amazon STS endpoints, see Endpoints in the Amazon Security Token Service API Reference or Manage Amazon STS in an Amazon Web Services Region in the Amazon Identity and Access Management User Guide.

It is an Amazon best practice to use Regional endpoints whenever possible and to configure your Amazon Web Services 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

Amazon has made changes to the Amazon Security Token Service (Amazon STS) global endpoint (https://sts.amazonaws.com) in Regions enabled by default to enhance its resiliency and performance. Amazon STS requests to the global endpoint are automatically served in the same Amazon Web Services Region as your workloads. These changes will not be deployed to opt-in Regions. We recommend that you use the appropriate Amazon STS regional endpoints. For more information, see Amazon STS global endpoint changes in the Amazon 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 Amazon config file setting
AWS_STS_REGIONAL_ENDPOINTS - environment variable

This setting specifies how the SDK or tool determines the Amazon Web Services 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.

  • 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

Support by Amazon SDKs and tools

Note

It is an Amazon best practice to use Regional endpoints whenever possible and to configure your Amazon Web Services 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 configured Amazon Web Services Region used by your application.

  • us-east-1 (Regional): Uses the us-east-1 Region endpoint but with longer session tokens than typical global requests.

SDK

Supports setting

Default setting value

Default service client target STS Endpoint

Service client fallback behavior

 Notes or more information
Amazon CLI v2 No N/A Regional endpoint Global endpoint
Amazon CLI v1 Yes legacy Global endpoint Global endpoint
SDK for C++ No N/A Regional endpoint us-east-1 (Regional)
SDK for Go V2 (1.x) No N/A Regional endpoint Request failure
SDK for Go 1.x (V1) Yes legacy Global endpoint Global endpoint To use shared config file settings, you must turn on loading from the config file; see Sessions.
SDK for Java 2.x No N/A Regional endpoint Request failure

If no Region is configured, the AssumeRole and AssumeRoleWithWebIdentity will use the global STS endpoint.
SDK for Java 1.x Yes legacy Global endpoint Global endpoint
SDK for JavaScript 3.x No N/A Regional endpoint Request failure
SDK for JavaScript 2.x Yes legacy Global endpoint Global endpoint
SDK for Kotlin No N/A Regional endpoint Global endpoint
SDK for .NET 4.x No N/A Regional endpoint us-east-1 (Regional)
SDK for .NET 3.x Yes legacy Global endpoint Global endpoint
SDK for PHP 3.x Yes legacy Global endpoint Request failure
SDK for Python (Boto3) Yes legacy Global endpoint Global endpoint
SDK for Ruby 3.x Yes regional Regional endpoint Request failure
SDK for Rust No N/A Regional endpoint Request failure
SDK for Swift No N/A Regional endpoint Request failure
Tools for PowerShell Yes legacy Global endpoint Global endpoint