ballerinax/aws.auth Ballerina library

Overview

The auth submodule of the ballerinax/aws package provides AWS authentication: credential resolution across all standardized AWS credential sources (with automatic refresh) and AWS Signature Version 4 (SigV4) request signing. It is the authentication foundation used by the ballerinax/aws.* connectors, and can be used directly to call AWS services that do not have a dedicated connector yet.

Region and endpoint utilities live in the package's root module, ballerinax/aws.

Credential sources

The AuthConfig union covers all standardized AWS credential sources:

Quickstart

Step 1: Import the module

import ballerinax/aws.auth;

Step 2: Create a credential provider

Create a CredentialProvider once, at initialization. On AWS infrastructure the default provider chain resolves credentials automatically:

auth:CredentialProvider credProvider = check new (auth:DEFAULT_CREDENTIALS);

Other credential sources use the same API with a different configuration — for example, STS assume-role composed over any base identity:

auth:CredentialProvider credProvider = check new ({
    roleArn: "arn:aws:iam::123456789012:role/reporting-read-only",
    sourceCredentials: auth:DEFAULT_CREDENTIALS
});

Step 3: Resolve credentials

Fetch credentials per request; expiring temporary credentials (STS, SSO, instance profile) are renewed transparently:

auth:Credentials credentials = check credProvider.getCredentials();

Release the provider's resources when it is no longer needed:

check credProvider.close();

Step 4: Sign a request

Sign requests to any AWS service — including services without a dedicated Ballerina connector. getSignedHeaders returns the headers to attach to the outbound request:

map<string> signedHeaders = check auth:getSignedHeaders({
    method: "POST",
    host: "sns.us-east-1.amazonaws.com",
    headers: {"content-type": "application/x-www-form-urlencoded"},
    payload: "Action=CreateTopic&Name=orders".toBytes()
}, credentials, "us-east-1", "sns");