= “us-east-2”
os.environ[“AWS_STS_REGIONAL_ENDPOINTS”] = “regional”
You can use the metadata attribute sts_client.meta.endpoint_url to inspect and validate how an STS client is configured. The output should look similar to the following:
>>> sts_client = boto3.client(“sts”)
>>> sts_client.meta.endpoint_url
‘https://sts.us-east-2.amazonaws.com’
For a list of AWS SDKs that support environment variable settings for Regional AWS STS endpoints, see Compatibility with AWS SDKs.
Option 3 — Construct an endpoint URL
You can also manually construct an endpoint URL for a specific Regional AWS STS endpoint.
The following example shows how you can configure the STS client with AWS SDK for Python (Boto3) to use a Regional AWS STS endpoint by setting a specific endpoint URL:
import boto3
sts_client = boto3.client(‘sts’, region_name=’us-east-2′, endpoint_url=’https://sts.us-east-2.amazonaws.com’)
Use a VPC endpoint with AWS STS
You can create a private connection to AWS STS from the resources that you deployed in your Amazon VPCs. AWS STS integrates with AWS PrivateLink by using interface VPC endpoints. The network traffic on AWS PrivateLink stays on the global AWS network backbone and doesn’t traverse the public internet. When you configure a VPC endpoint for AWS STS, the traffic for the Regional AWS STS endpoint traverses to that endpoint.
By default, the DNS in your VPC will update the entry for the Regional AWS STS endpoint to resolve to the private IP address of the VPC endpoint for AWS STS in your VPC. The following output from an Amazon Elastic Compute Cloud (Amazon EC2) instance shows the DNS name for the AWS STS endpoint resolving to the private IP address of the VPC endpoint for AWS STS:
[ec2-user@ip-10-120-136-166 ~]$ nslookup sts.us-east-2.amazonaws.com
Server: 10.120.0.2
Address: 10.120.0.2#53
Non-authoritative answer:
Name: sts.us-east-2.amazonaws.com
Address: 10.120.138.148
After you create an interface VPC endpoint for AWS STS in your Region, set the value for the respective Regional AWS STS endpoint by using environment variables to access AWS STS in the same Region.
The output of the following log shows that an AWS STS call was made to the Regional AWS STS endpoint:
POST
/
content-type:application/x-www-form-urlencoded; charset=utf-8
host:sts.us-east-2.amazonaws.com
Log AWS STS requests
You can use AWS CloudTrail events to get information about the request and endpoint that was used for AWS STS. This information can help you identify AWS STS request patterns and validate if you are still using the global (legacy) STS endpoint.
An event in CloudTrail is the record of an activity in an AWS account. CloudTrail events provide a history of both API and non-API account activity made through the AWS Management Console, AWS SDKs, command line tools, and other AWS services.
Log locations
Requests to Regional AWS STS endpoints sts..amazonaws.com are logged in CloudTrail within their respective Region.
Requests to the global (legacy) STS endpoint sts.amazonaws.com are logged within the US East (N. Virginia) Region (us-east-1).
Log fields
Requests to Regional AWS STS endpoints and global endpoint are logged in the tlsDetails field in CloudTrail. You can use this field to determine if the request was made to a Regional or global (legacy) endpoint.
Requests made from a VPC endpoint are logged in the vpcEndpointId field in CloudTrail.
The following example shows a CloudTrail event for an STS request to a Regional AWS STS endpoint with a VPC endpoint.
“eventType”: “AwsApiCall”,
“managementEvent”: true,
“recipientAccountId”: “123456789012”,
“vpcEndpointId”: “vpce-021345abcdef6789”,
“eventCategory”: “Management”,
“tlsDetails”: {
“tlsVersion”: “TLSv1.2”,
“cipherSuite”: “ECDHE-RSA-AES128-GCM-SHA256”,
“clientProvidedHostHeader”: “sts.us-east-2.amazonaws.com”
}
The following example shows a CloudTrail event for an STS request to the global (legacy) AWS STS endpoint.
“eventType”: “AwsApiCall”,
“managementEvent”: true,
“recipientAccountId”: “123456789012”,
“eventCategory”: “Management”,
“tlsDetails”: {
“tlsVersion”: “TLSv1.2”,
“cipherSuite”: “ECDHE-RSA-AES128-GCM-SHA256”,
“clientProvidedHostHeader”: “sts.amazonaws.com”
}
To interactively search and analyze your AWS STS log data, use AWS CloudWatch Logs Insights or Amazon Athena.
CloudWatch Logs Insights
The following example shows how to run a CloudWatch Logs Insights query to look for API calls made to the global (legacy) AWS STS endpoint. Before you can query CloudTrail events, you must configure a CloudTrail trail to send events to CloudWatch Logs.
filter eventSource=”sts.amazonaws.com” and tlsDetails.clientProvidedHostHeader=”sts.amazonaws.com”
| fields eventTime, recipientAccountId, eventName, tlsDetails.clientProvidedHostHeader, sourceIPAddress, userIdentity.arn, @message
| sort eventTime desc
The query output shows event details for an AWS STS call made to the global (legacy) AWS STS endpoint https://sts.amazonaws.com.
Figure 3: Use a CloudWatch Log Insights query to look for STS API calls
Amazon Athena
The following example shows how to query CloudTrail events with Amazon Athena and search for API calls made to the global (legacy) AWS STS endpoint.
SELECT
eventtime,
recipientaccountid,
eventname,
tlsdetails.clientProvidedHostHeader,
sourceipaddress,
eventid,
useridentity.arn
FROM “cloudtrail_logs”
WHERE
eventsource = ‘sts.amazonaws.com’ AND
tlsdetails.clientProvidedHostHeader = ‘sts.amazonaws.com’
ORDER BY eventtime DESC
The query output shows STS calls made to the global (legacy) AWS STS endpoint https://sts.amazonaws.com.
Figure 4: Use Athena to search for STS API calls and identify STS endpoints
Conclusion
In this post, you learned how to use Regional AWS STS endpoints to help improve resiliency, reduce latency, and increase session token usage for the operating Regions in your AWS environment.
AWS recommends that you check the configuration and usage of AWS STS endpoints in your environment, validate AWS STS activity in your CloudTrail logs, and confirm that Regional AWS STS endpoints are used.
If you have questions, post them in the Security Identity and Compliance re:Post topic or reach out to AWS Support.
Want more AWS Security news? Follow us on X.
Darius Januskis
Darius is a Senior Solutions Architect at AWS helping global financial services customers in their journey to the cloud. He is a passionate technology enthusiast who enjoys working with customers and helping them build well-architected solutions. His core interests include security, DevOps, automation, and serverless technologies.”]
