STS (Security Token Service)

The StsClient class in the multicloudj library provides a portable interface for interacting with cloud provider security token services such as AWS STS, GCP IAM Credentials, or any other compatible implementation. It allows you to obtain temporary credentials, access tokens, and caller identity information in a cloud-neutral way.

---

Overview

The StsClient is built on top of provider-specific implementations of AbstractSts. Each provider registers its implementation and is selected dynamically at runtime.

To use STS, you must first create a client using the builder() method.

---

Creating a Client

StsClient stsClient = StsClient.builder("aws")
    .withRegion("us-west-2")
    .build();

Optionally, you can set a custom endpoint:

URI endpoint = URI.create("https://sts.custom-endpoint.com");
StsClient stsClient = StsClient.builder("aws")
    .withRegion("us-west-2")
    .withEndpoint(endpoint)
    .build();

---

Getting Caller Identity

Retrieve the caller identity associated with the current credentials:

CallerIdentity identity = stsClient.getCallerIdentity();
System.out.println("Caller: " + identity.getArn());

---

Getting an Access Token

Use this when you need an OAuth2-style token (provider support may vary):

GetAccessTokenRequest request = new GetAccessTokenRequest();
StsCredentials token = stsClient.getAccessToken(request);
System.out.println("Access Token: " + token.getAccessToken());

---

Assuming a Role

To assume a different identity (e.g., for cross-account access):

AssumedRoleRequest request = new AssumedRoleRequest();
request.setRoleArn("arn:aws:iam::123456789012:role/example-role");
request.setSessionName("example-session");
StsCredentials credentials = stsClient.getAssumeRoleCredentials(request);
System.out.println("Temporary Credentials: " + credentials.getAccessKeyId());

---

Error Handling

All errors are translated to SubstrateSdkException subclasses by the underlying driver. The client will automatically map exceptions to meaningful runtime errors based on the provider:

try {
    CallerIdentity identity = stsClient.getCallerIdentity();
} catch (SubstrateSdkException e) {
    // Handle known errors: AccessDenied, Timeout, etc.
    e.printStackTrace();
}