Manage Amazon STS in an Amazon Web Services Region - Amazon Identity and Access Management
Managing Amazon STS endpoint session tokens in the China (Beijing) RegionActivating and deactivating Amazon STS in an Amazon Web Services RegionWriting code to use Amazon STS Regions
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).

Manage Amazon STS in an Amazon Web Services Region

A Regional endpoint is the URL of the entry point within a particular region for an Amazon web service. Amazon recommends using Regional Amazon Security Token Service (Amazon STS) endpoints instead of the global endpoint to reduce latency, build in redundancy, and increase session token validity. Although the global (legacy) Amazon STS endpoint https://sts.amazonaws.com is highly available, it’s hosted in a single Amazon Region, US East (N. Virginia), and like other endpoints, it doesn’t provide automatic failover to endpoints in other Regions.

  • Reduce latency – By making your Amazon STS calls to an endpoint that is geographically closer to your services and applications, you can access Amazon 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 Amazon 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 Amazon Well-Architected Framework.

  • Increase session token validity – Session tokens from Regional Amazon STS endpoints are valid in all Amazon Web Services Regions. Session tokens from the global STS endpoint are valid only in Amazon Web Services Regions that are enabled by default. If you intend to enable a new Region for your account, you can use session tokens from Regional Amazon STS endpoints. If you choose to use the global endpoint, you must change the Region compatibility of Amazon STS session tokens for the global endpoint. Doing so ensures that tokens are valid in all Amazon Web Services Regions.

For a list of Amazon STS Regions and their endpoints, see Amazon STS Regions and endpoints.

Managing Amazon STS endpoint session tokens in the China (Beijing) Region

If workloads or callers in your account intend to sign Amazon requests using the Signature Version 4A (SigV4A) algorithm, or you plan to adopt a specific Amazon Web Services services feature that requires it, you need to configure the Amazon STS endpoint in the China (Beijing) Region to vend session tokens that support SigV4A. By default, the Amazon STS endpoint in the China (Beijing) Region vends session tokens that support only the Signature Version 4 (SigV4) algorithm. Session tokens that support the SigV4A algorithm are larger than session tokens that support the SigV4 algorithm and match the size of session tokens issued by the Amazon STS endpoint in the China (Ningxia) Region, which already supports the use of SigV4A. Changing this setting might affect existing systems where you temporarily store tokens.

You can change this setting using the Amazon Web Services Management Console, Amazon CLI, or Amazon API.

To change the Region compatibility of session tokens for the China (Beijing) Region STS endpoint (console)

  1. Sign in as 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.

  2. Open the IAM console. In the navigation pane, choose Account settings.

  3. Under Security Token Service (STS) section Session Tokens from the STS endpoints. The Amazon Web Services China (Beijing) Region endpoint indicates Support only SigV4 based signatures on Amazon Web Services requests. Choose Change.

  4. In the Change region compatibility dialog box, select Both the SigV4 and SigV4A algorithms. Then choose Save changes.

    Note

    Session tokens compatible with Signature Version 4A (SigV4A) based signatures include more characters than tokens compatible with Signature Version 4 (SigV4) based signatures. Changing this setting might affect existing systems where you temporarily store tokens.

To change the Region compatibility of session tokens for the China (Beijing) Region STS endpoint (Amazon CLI)

Set the session token version. Version 1 tokens are compatible with only SigV4 based signatures. Version 2 tokens are compatible with both SigV4 and SigV4A based signatures. 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 China (Beijing) Region STS endpoint (Amazon API)

Set the session token version. Version 1 tokens are compatible with only SigV4 based signatures. Version 2 tokens are compatible with both SigV4 and SigV4A based signatures. However, version 2 tokens include more characters and might affect systems where you temporarily store tokens.

Activating and deactivating Amazon STS in an Amazon Web Services Region

When you activate STS endpoints for a Region, Amazon STS can issue temporary credentials to users and roles in your account that make an Amazon 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 Amazon STS Regional endpoint https://sts.us-west-2.amazonaws.com.cn. 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-west-2 Region. Users from account A (or any other account) can call the us-west-2 Amazon STS 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 Amazon STS in a Region that is enabled by default (console)

  1. Sign in as a root user or a user with permissions to perform IAM administration tasks.

  2. Open the IAM console and in the navigation pane choose Account settings.

  3. 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.

  4. In the dialog box that opens, choose Activate or Deactivate.

For Regions that must be enabled, we activate Amazon STS automatically when you enable the Region. After you enable a Region, Amazon STS is always active for the Region and you cannot deactivate it. To learn about enabling Regions that are disabled by default, see Specifying which Amazon Web Services Regions your account can use in the Amazon Account Management Reference Guide.

Writing code to use Amazon STS Regions

After you activate a Region, you can direct Amazon STS API calls to that Region. The following Java code snippet demonstrates how to configure an AWSSecurityTokenService object to make requests to the Europe (Milan) (eu-south-1) Region.

EndpointConfiguration regionEndpointConfig = new EndpointConfiguration("https://sts.eu-south-1.amazonaws.com", "eu-south-1");
AWSSecurityTokenService stsRegionalClient = AWSSecurityTokenServiceClientBuilder.standard()
.withCredentials(credentials)
.withEndpointConfiguration(regionEndpointConfig)
.build();

Amazon STS recommends that you make calls to a Regional endpoint. To learn how to manually enable a Region, see Specify which Amazon Web Services Regions your account can use in the Amazon Account Management Reference Guide.

In the example, the first line instantiates an EndpointConfiguration object called regionEndpointConfig, passing the URL of the endpoint and the Amazon Web Services Region as the parameters.

To learn how to set Amazon STS regional endpoints using an environment variable for Amazon SDKs, see Amazon STS Regionalized endpoints in the Amazon SDKs and Tools Reference Guide.

For all other language and programming environment combinations, refer to the documentation for the relevant SDK.