Sign In to the Console
AWS Identity and Access Management
User Guide

AWS Documentation » AWS Identity and Access Management » User Guide » Identities (Users, Groups, and Roles) » Temporary Security Credentials » Managing AWS STS in an AWS Region

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 add code to your application that switches your AWS STS API calls to a different Region. This ensures that if the first Region stops responding, your application continues to operate. This redundancy is not automatic; you must build the functionality into your code.

  • 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 STS endpoints. If you choose to use the global endpoint, you must change the Region compatibility of 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 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)

  1. Sign in as a root user or an IAM 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. If necessary, expand the Security Token Service (STS) section. In the first table next to Global endpoint, the Region compatibility of session tokens column indicates Valid only in AWS Regions enabled by default. Choose Change.

  4. In the Change region compatibility of session tokens for global endpoint dialog box, select Valid in all AWS Regions. Then choose Save changes.

    Note

    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.

To change the Region compatibility of session tokens for the global endpoint (AWS CLI)

Set the security 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 security 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. You must activate the Region 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 example, imagine a user in account A wants to send an sts:AssumeRole API request to the STS Regional endpoint https://sts.us-west-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-west-2 Region. Users from account A (or any other account) can call the us-west-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)

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

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

  3. If necessary, expand the Security Token Service (STS) list, find the Region that you want to activate, and then choose Activate or Deactivate. Some Regions are not enabled by default, such as the Asia Pacific Hong Kong Region. In that case, when you manually enable the Region, STS is activated automatically. From that point forward, AWS STS is always active for these Regions and it cannot be deactivated. To learn how to manually 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 AWSSecurityTokenServiceClient object to make requests to the EU (Ireland) (eu-west-1) Region with the setEndpoint method. 

AWSSecurityTokenServiceClient stsClient = new AWSSecurityTokenServiceClient();
stsClient.setRegion("eu-west-1");
stsClient.setEndpoint("sts.eu-west-1.amazonaws.com");

AWS STS recommends that you use both the setRegion and setEndpoint methods to make calls to a Regional endpoint. You can use the setRegion method alone for manually enabled Regions, such as Asia Pacific (Hong Kong). In this case, the calls are directed to the STS Regional endpoint. To learn how to manually enable a Region, see Managing AWS Regions in the AWS General Reference. If you use the setRegion method alone for Regions enabled by default, the calls are directed to the global endpoint of https://sts.amazonaws.com.

In the example, the first line instantiates an AWSSecurityTokenServiceClient object called stsClient. The second line configures the stsClient object by calling its setEndpoint method and passing the URL of the endpoint as the only parameter. All API calls that use this stsClient object are now directed to the specified endpoint.

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

Region 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 Can Be Activated/Deactivated
--Global-- sts.amazonaws.com Yes No
US East (Ohio) sts.us-east-2.amazonaws.com Yes Yes
US East (N. Virginia) sts.us-east-1.amazonaws.com Yes No
US West (N. California) sts.us-west-1.amazonaws.com Yes Yes
US West (Oregon) sts.us-west-2.amazonaws.com Yes Yes
Canada (Central) sts.ca-central-1.amazonaws.com Yes Yes
Asia Pacific (Tokyo) sts.ap-northeast-1.amazonaws.com Yes Yes
Asia Pacific (Seoul) sts.ap-northeast-2.amazonaws.com Yes Yes
Asia Pacific (Mumbai) sts.ap-south-1.amazonaws.com Yes Yes
Asia Pacific (Singapore) sts.ap-southeast-1.amazonaws.com Yes Yes
Asia Pacific (Sydney) sts.ap-southeast-2.amazonaws.com Yes Yes
Asia Pacific (Hong Kong) sts.ap-east-1.amazonaws.com Not until the Region is enabled No
Middle East (Bahrain) sts.me-south-1.amazonaws.com Not until the Region is enabled No
EU (Frankfurt) sts.eu-central-1.amazonaws.com Yes Yes
EU (Ireland) sts.eu-west-1.amazonaws.com Yes Yes
EU (London) sts.eu-west-2.amazonaws.com Yes Yes
EU (Paris) sts.eu-west-3.amazonaws.com Yes Yes
EU (Stockholm) sts.eu-north-1.amazonaws.com Yes Yes
South America (São Paulo) sts.sa-east-1.amazonaws.com Yes Yes

Note

Calls to Regional endpoints, such as us-east-2.amazonaws.com, are logged in AWS CloudTrail the same as any call to a Regional service. Calls to the global endpoint, sts.amazonaws.com, are logged as calls to a global service. For more information, see Logging IAM and AWS STS API Calls with AWS CloudTrail.