Skip to content
ReleasesGitHub

Using Multiple AWS STS Credential Providers in a Single Access Policy

This page explains how Aembit routes requests to multiple AWS Security Token Service (STS) Credential Providers within a single Access Policy: Access Policies define, enforce, and audit access between Client and Server Workloads by cryptographically verifying workload identity and contextual factors rather than relying on static secrets.Learn more.

Unlike when using multiple JWT-based Credential Providers that use username or HTTP header mapping, AWS STS Credential Providers use Access Key ID selectors for Credential Provider matching. Each AWS STS Credential Provider that you configure in an Access Policy must have a unique Access Key ID that your application uses as a placeholder in requests. How that selector reaches Aembit depends on the integration path. Agent Proxy reads it from the intercepted request. The Aembit GitHub Action, the Edge SDKs, and the Edge API send it as a parameter of the credential request.

In complex AWS environments, applications often need to assume different IAM roles to access AWS services securely. Traditionally, this required creating separate access policies for each role, increasing operational overhead.

You can add multiple AWS STS Credential Provider: Credential Providers obtain the specific access credentials—such as API keys, OAuth tokens, or temporary cloud credentials—that Client Workloads need to authenticate to Server Workloads.Learn more to one Access Policy. This enables a single Client Workload: Client Workloads represent software applications, scripts, or automated processes that initiate access requests to Server Workloads, operating autonomously without direct user interaction.Learn more identity to seamlessly access multiple AWS resources, each with its own IAM role, by selecting the appropriate Credential Provider based on the AWS Access Key ID.

Benefits

Section titled “Benefits”
  • Simplified Policy Management - Manage multiple AWS roles within a single policy, reducing configuration complexity.
  • Scalability - Efficiently supports multiple Credential Providers (for example, 10+) per Access Policy.
  • Seamless Application Experience - Applications can access different AWS resources without code changes or multiple workload identities.

How it works

Section titled “How it works”

After you configure multiple AWS STS Credential Providers in an Access Policy (each with a unique Access Key ID selector), Aembit handles requests as follows:

  1. Selector delivery - The Client Workload’s integration path delivers the Access Key ID selector to Aembit Cloud as part of the credential request. See Selector paths for where each path takes the selector from.

  2. Credential Provider matching - Aembit Cloud matches the Access Key ID to the corresponding Credential Provider configured in the Access Policy.

  3. Credential issuance - Aembit Cloud assumes the IAM role via the selected Credential Provider and returns temporary AWS credentials. Agent Proxy injects them into the application’s request. The GitHub Action and the Edge SDKs hand them to your workflow or code directly.

Selector paths

Section titled “Selector paths”
Integration pathWhere the selector comes from
Agent ProxyThe Access Key ID in the AWS SigV4 Authorization header
Aembit GitHub ActionThe aws-access-key-id input on the Aembit/get-credentials step
Edge APIThe connectionMetadata.accessKeyId field in the request body
Edge SDKThe accessKeyId connection metadata on the credential request

Behind Agent Proxy, your application sets the selector as its AWS Access Key ID and needs no other change. Agent Proxy extracts it from the AWS SigV4 Authorization header. Without Agent Proxy, your workflow or code names the selector when it requests the credential. For each path, see:

The same Access Policy serves every path, so a workload behind Agent Proxy and a GitHub workflow can select the same Credential Providers with the same selector values.

Example scenario

Section titled “Example scenario”

Suppose your application needs to:

  • Write logs to an S3 bucket (using STS-RoleA)
  • Read data from DynamoDB (using STS-RoleB)

You can configure:

  • STS-RoleA: Assumes an IAM role for S3 access, mapped to selector AKIADUMMYFORROLEA
  • STS-RoleB: Assumes an IAM role for DynamoDB access, mapped to selector AKIADUMMYFORROLEB

Your application uses the appropriate placeholder Access Key ID to select the desired Credential Provider for each request.

High-level workflow

Section titled “High-level workflow”

The following diagram shows the Agent Proxy path. Agent Proxy extracts the selector from the application’s request, and Aembit Cloud selects the matching Credential Provider:

Sequence diagram showing how the Agent Proxy routes AWS requests through Aembit Cloud to select the appropriate Credential Provider based on Access Key ID

Access authorization events

Section titled “Access authorization events”

The following are example access authorization events with the Event Type access.credential showing the use of different AWS STS Credential Providers within an Access Policy when handling requests:

Notice the differences between the two Credential Providers:

  • The serverWorkload name reflects different AWS resources (S3 SW vs DynamoDB SW)
  • The accessPolicy ID remains the same, indicating the same Access Policy governs both requests
  • The credentialProvider section shows different id and name values (STS-RoleA vs STS-RoleB)
{
  "meta": {
    "clientIP": "18.111.222.123",
    "timestamp": "2025-11-25T11:58:58.989522Z",
    "eventType": "access.credential",
    "eventId": "521bf87e-91d8-4e9b-90c5-7a6d4d6118ce",
    "resourceSetId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "contextId": "47fa4467-0712-4c1e-b44e-d4dbddc7844a",
    "severity": "Info"
  },
  "outcome": {
    "result": "Authorized"
  },
  "clientWorkload": {
    "id": "973fb193-828b-406e-a6be-b64db2c94fd6",
    "name": "Test Ubuntu STS CW",
    "result": "Identified"
  },
  "serverWorkload": {
    "id": "f1ebd1d-ebf4-462d-8e45-a4eeea68e480",
    "name": "S3 SW",
    "result": "Identified"
  },
  "accessPolicy": {
    "id": "da30b2f9-999a-40d2-94fe-6a0c50b837cf",
    "result": "Identified"
  },
  "trustProviders": [],
  "accessConditions": [],
  "credentialProvider": {
    "type": "aws-sts-oidc",
    "id": "b8804a83-ab97-4dc6-8bc6-2cec9f33c2b5",
    "name": "STS-RoleA",
    "result": "Retrieved"
  }
}

Key fields explained

Section titled “Key fields explained”
  • meta: General metadata about the event, including client IP, timestamp, event type, and unique IDs.
  • outcome: The result of the access attempt (for example, “Authorized”).
  • clientWorkload/serverWorkload: Identifiers and names for the Client Workload and Server Workload: Server Workloads represent target services, APIs, databases, or applications that receive and respond to access requests from Client Workloads.Learn more involved.
  • accessPolicy: The ID of the Access Policy that authorized the request.
  • trustProviders: Trust Provider: Trust Providers validate Client Workload identities through workload attestation, verifying identity claims from the workload's runtime environment rather than relying on pre-shared secrets.Learn more used to verify the Client Workload identity.
  • accessConditions: Access Condition: Access Conditions add dynamic, context-aware constraints to authorization by evaluating circumstances like time, location, or security posture to determine whether to grant access.Learn more evaluated for this request.
  • credentialProvider: Details about the Credential Provider used, including its type, unique ID, and name.

Error handling

Section titled “Error handling”

The following rules apply when handling requests with multiple AWS STS Credential Providers:

  • Behind Agent Proxy, an Access Key ID that matches no configured Credential Provider fails the request with a 403 Forbidden error.
  • On the Edge API path, an Access Key ID that matches no configured Credential Provider returns 404 Not Found with credentialType set to Unknown.
  • On the Edge API path, a request that sends no Access Key ID at all returns 400 Bad Request when the Access Policy holds more than one Credential Provider.
  • If Agent Proxy can’t extract the Access Key ID (for example, a malformed request), credentials aren’t injected and the request fails.
  • Access Key ID selector values must use uppercase characters only. Lowercase selectors won’t match.
Section titled “Related topics”