KMS supports RAM-based authentication for OpenAPI access through both shared and dedicated gateways. This topic covers four credential types: AccessKey, Security Token Service (STS) token, RamRoleArn, and ECS instance RAM role.
Prefer temporary credentials — STS tokens, RamRoleArn, or ECS instance RAM roles — over long-term AccessKey pairs. Temporary credentials expire automatically and reduce the risk of key leakage.
Choose a credential type
| Credential type | Who it's for | Lifetime | Recommended? |
|---|---|---|---|
| AccessKey | RAM users that need long-term programmatic access | Permanent (until rotated or deleted) | Use only when temporary credentials aren't feasible |
| STS token | Applications that need scoped, time-limited access | Minutes to hours, then auto-expires | Yes |
| RamRoleArn | RAM users or cloud services assuming a role for a task | Temporary, expires on role release | Yes |
| ECS instance RAM role | Applications running on ECS that call KMS | Temporary STS tokens, auto-rotated | Yes, for ECS workloads |
AccessKey
An AccessKey pair grants long-term programmatic access. Because Alibaba Cloud account permissions can't be restricted, never create an AccessKey for your Alibaba Cloud account — if the key is compromised, the entire account is at risk. Instead, create a RAM user with API access mode enabled, generate an AccessKey pair for that RAM user, and grant only the permissions required for KMS operations.
For background, see Create an AccessKey pair.
Log on to the RAM console using an Alibaba Cloud account, a RAM administrator with the AliyunRAMFullAccess policy, or a RAM user authorized to manage AccessKey pairs.
In the left-side navigation pane, choose Identities > Users, and click the target RAM user.
On the Authentication tab, click Create AccessKey and follow the prompts.
Grant the RAM user access to KMS. See Grant KMS access below.
STS token
Security Token Service (STS) issues temporary access credentials to RAM users or RAM roles. The credentials carry only the permissions specified in the policy and automatically expire after the validity period.
Log on to the RAM console using an Alibaba Cloud account or a RAM user with administrative rights.
Create a RAM user (for user-based access) or create a RAM role (for role-based access).
Grant AliyunSTSAssumeRoleAccess permission: grant it to the RAM user or grant it to the RAM role.
Grant the RAM user or RAM role access to KMS. See Grant KMS access below.
Use the RAM user or RAM role to call the AssumeRole API of STS to obtain temporary access credentials.
RamRoleArn
RamRoleArn lets a RAM user or cloud service assume a RAM role to get temporary permissions without using a long-term AccessKey pair. When the task completes, the role's permissions are automatically revoked.
RamRoleArn is the ARN of the RAM role, in the format acs:ram::$accountID:role/$roleName.
Log on to the RAM console using an Alibaba Cloud account or a RAM user with administrative rights.
Grant the RAM role access to KMS. See Grant KMS access below.
View the RamRoleArn of the RAM role.
ECS instance RAM role
An ECS instance RAM role is a service role attached to an ECS instance, with ECS as the trusted entity. Applications on the instance can retrieve temporary STS tokens without storing an AccessKey pair, then use those tokens to call KMS OpenAPI operations.
Log on to the RAM console and create an instance RAM role with the following settings:
Principal Type: Cloud Service
Principal Name: Elastic Compute Service / ECS
Grant the instance RAM role access to KMS. See Grant KMS access below.
Log on to the ECS console and attach the instance RAM role to the target ECS instance.
Grant KMS access
For all credential types, grant KMS access using one of the following methods:
Identity-based policies: Attach a KMS system policy or a custom policy to the RAM user or RAM role. For available system policies, see System policies for KMS.
Resource-based policies: Set access permissions directly on KMS keys or secrets to control which Alibaba Cloud accounts, RAM users, and RAM roles can manage or use them. For details, see Key policies for key-level access control and Secret policies for secret-level access control.
What's next
For additional credential types and advanced configuration options, see Manage Access Credentials.