Obtain an STS token

Workflow

The agent obtains and uses an STS token in three stages:

1. Complete inbound authentication. The agent calls one of the Agent Identity service's GetWorkloadAccessToken* operations through the Agent Identity SDK to obtain a Workload Access Token. The most common form of inbound authentication uses a JSON Web Token (JWT) issued by an external identity provider.

2. Exchange the Workload Access Token for an STS token. The SDK calls the Agent Identity service's AssumeRoleForWorkloadIdentity operation, presenting the Workload Access Token to assume the runtime RAM role associated with the Workload Identity. Agent Identity returns temporary security credentials — an STS token containing an AccessKeyId, an AccessKeySecret, and a SecurityToken.

3. Call Alibaba Cloud OpenAPI. The agent uses the STS token to call Alibaba Cloud OpenAPI on behalf of the runtime RAM role, securely accessing services such as ECS, OSS, and VPC.

Prerequisites

Before the agent can obtain an STS token, set up Workload Identity and grant the runtime role the permissions it needs:

• The operator account that performs the setup must have the AliyunAgentIdentityFullAccess permission policy attached.

• Create a Workload Identity in the Agent Identity console, or by using the Agent Identity CLI. When you use the CLI, a runtime RAM role is created with the same name, in the form agentidentityrole-${workloadIdentityName}.

• In the RAM console, attach a permission policy to the runtime RAM role that grants access to the Alibaba Cloud services the agent needs to call. For example, attach AliyunVPCFullAccess (a system policy) so the agent can manage VPCs.

Use the SDK to obtain a token

After the prerequisites are in place, the agent obtains STS tokens through a decorator. Annotate any function that calls Alibaba Cloud OpenAPI with @requires_sts_token. When the function is invoked, the Agent Identity SDK transparently completes inbound authentication, retrieves a Workload Access Token, exchanges it for an STS token, and injects the token into the function parameter you name.

The following Python example shows an agent calling the Alibaba Cloud VPC API to create a VPC:

from typing import Optional

from agent_identity_python_sdk.core.decorators import get_region, requires_sts_token
from agent_identity_python_sdk.model import STSCredential

from alibabacloud_vpc20160428.client import Client as Vpc20160428Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_vpc20160428 import models as vpc_20160428_models

@requires_sts_token(
    inject_param_name="sts_credential"
)
def create_vpc(
    name: str,
    region_id: str,
    cidr_block: str,
    sts_credential: Optional[STSCredential] = None,
):
    # Initialize the Alibaba Cloud OpenAPI client with the STS credential.
    config = open_api_models.Config(
        access_key_id=sts_credential.access_key_id,
        access_key_secret=sts_credential.access_key_secret,
        security_token=sts_credential.security_token,
    )
    config.endpoint = f'vpc.{region_id}.aliyuncs.com'
    client = Vpc20160428Client(config)

    # Call the OpenAPI to create a VPC.
    request = vpc_20160428_models.CreateVpcRequest(
        region_id=region_id,
        cidr_block=cidr_block,
        vpc_name=name,
        description='This is a test VPC.'
    )
    response = client.create_vpc(request)

For the complete runnable sample, see fetch-sts-token sample.

FAQ

{
  ...
  "userIdentity": {
    "type": "assumed-role",
    ...
    "sessionContext": {
      "externalIdentityContext": {
        "agentidentityWorkloadIdentityArn": "acs:agentidentity:cn-beijing:<account_id>:workloadidentitydirectory/default/workloadidentity/<workload-identity-name>",
        "agentidentityInboundJwtClaimIss": "https://<oauth.yourcompany.com>",
        "agentidentityInboundJwtClaimSub": "iiCsOvhjNZX/hK0x1jl9****"
      }
    }
  }
  ...
  "eventName": "CreateVpc"
}