Set a secret policy for a KMS secret using the Secrets Manager console or OpenAPI - Key Management Service

By default, only the Alibaba Cloud account that created a secret (the secret owner) can manage or access it. A Secret Policy lets you extend access to other principals — RAM users and RAM roles — within your account or from another Alibaba Cloud account. Use a Secret Policy to:

Grant specific RAM users or roles the ability to manage a secret (rotate, update, delete) without exposing its value.
Grant other RAM users or roles read-only access to retrieve the secret value.
Allow RAM users or roles from another Alibaba Cloud account to access a secret in your account (cross-account access).

Prerequisites

Before you begin, ensure that you have:

A secret in a Key Management Service (KMS) instance — Secret Policies are not supported for secrets outside a KMS instance
RAM users or roles to grant access to, either within your account or from another Alibaba Cloud account
(For cross-account access) The ARN of the target RAM user or role from the other account

Configure a secret policy in the KMS console

Log on to the Key Management Service console. Select a region from the top menu bar. In the navigation pane on the left, click Resource > Secrets.
On the Secrets tab, locate your target secret, and click the secret ID or Details in the Actions column.
In the Secret Policy area at the bottom of the details page, click Configure Secret Policy, complete the configuration, and then click OK.

KMS provides two editing modes:

Visual editor

Use the Visual Editor to assign predefined permission sets to principals without writing JSON. Select a principal type and choose the RAM users or roles to grant access to.

Principal type	What they can do	Who can be selected
Administrator	Manage the secret (list, describe, put, rotate, update, delete, tag). Cannot retrieve the secret value.	RAM users and RAM roles in your account
User	Retrieve the secret value (`GetSecretValue`) and list or describe the secret.	RAM users and RAM roles in your account
Cross-account User	Retrieve the secret value (`GetSecretValue`) and list or describe the secret.	RAM users and RAM roles from another Alibaba Cloud account

To add a cross-account user:

Click Add ARN of Cross-account User.
Enter the ARN of the target RAM user or role. To find the ARN, log on to the RAM console and go to the user or role details page.
- RAM user ARN format: acs:ram::<anotherAccountUserId>:user/<ramuser> — for example, acs:ram::119285303511****:user/testpolicyuser
- RAM role ARN format: acs:ram::<ID of another Alibaba Cloud account>:role/<ramrole> — for example, acs:ram::119285303511****:role/testpolicyrole

Important

Granting permissions to a RAM user or role from another Alibaba Cloud account consumes the Access Management quota of your KMS instance. The quota is calculated by the number of Alibaba Cloud accounts granted access. After you revoke cross-account permissions, KMS releases the quota within about 5 minutes.

Syntax editor

Use the Syntax Editor to write or modify the JSON policy directly. This gives you full control over each statement — useful when the Visual Editor's predefined permission sets do not meet your requirements.

Policy example

This example configures a Secret Policy for a secret owned by Alibaba Cloud account 119285303511****:

Statement 1: Grants the owning account (119285303511****) full access (kms:*). Do not modify this statement — by default, the secret owner has all permissions, and this rule cannot be changed.
Statement 2: Grants RAM user secret_ramuser1 (in the same account) administrative access to manage the secret.
Statement 3: Grants RAM user secret_ramuser2 (same account) and RAM user secret_ramuser3 (from account 190325303126****) access to retrieve the secret value.

{
    "Statement": [
        {
            "Action": [
                "kms:*"
            ],
            "Effect": "Allow",
            "Principal": {
                "RAM": [
                    "acs:ram::119285303511****:*"
                ]
            },
            "Resource": [
                "*"
            ],
            "Sid": "kms default secret policy"
        },
        {
            "Action": [
                "kms:List*",
                "kms:Describe*",
                "kms:PutSecretValue",
                "kms:Update*",
                "kms:DeleteSecret",
                "kms:RestoreSecret",
                "kms:RotateSecret",
                "kms:TagResource",
                "kms:UntagResource"
            ],
            "Effect": "Allow",
            "Principal": {
                "RAM": [
                    "acs:ram::119285303511****:user/secret_ramuser1"
                ]
            },
            "Resource": [
                "*"
            ]
        },
        {
            "Action": [
                "kms:List*",
                "kms:Describe*",
                "kms:GetSecretValue"
            ],
            "Effect": "Allow",
            "Principal": {
                "RAM": [
                    "acs:ram::119285303511****:user/secret_ramuser2",
                    "acs:ram::190325303126****:user/secret_ramuser3"
                ]
            },
            "Resource": [
                "*"
            ]
        }
    ],
    "Version": "1"
}

Set up cross-account access

Cross-account access requires permission changes in both accounts. Configuring only one account is not sufficient.

Step 1: Grant access in the secret owner's account

In the KMS console, configure the Secret Policy for your secret and add a Cross-account User principal with the ARN of the target RAM user or role from the other account. See Configure a secret policy in the KMS console above.

Step 2: Grant access in the target account

The owner of the target account must grant the corresponding permissions to their RAM user or role in the RAM console. For instructions, see Custom permission policies for KMS, Grant permissions to a RAM user, and Grant permissions to a RAM role.

Limitations

Limitation	Details
Scope	Secret Policies can only be configured for secrets in a KMS instance
Format	Must be valid JSON
Size	Cannot exceed 32,768 bytes
Supported actions	Only the actions listed below are supported. Actions not on this list have no effect even if specified.

Supported actions:

kms:List*
kms:Describe*
kms:PutSecretValue
kms:Update*
kms:DeleteSecret
kms:RestoreSecret
kms:RotateSecret
kms:TagResource
kms:UntagResource
kms:GetSecretValue

Warning

If you specify an action not on this list, it will have no effect.

Default policy permissions

The Visual Editor assigns one of two predefined permission sets depending on the principal type.

Administrator

Grants permission to manage the secret but not to retrieve its value. An administrator can rotate, update, and delete the secret, and manage its tags — but cannot call GetSecretValue.

"Action": [
    "kms:List*",
    "kms:Describe*",
    "kms:PutSecretValue",
    "kms:Update*",
    "kms:DeleteSecret",
    "kms:RestoreSecret",
    "kms:RotateSecret",
    "kms:TagResource",
    "kms:UntagResource"
]

User or cross-account user

Grants permission to retrieve the secret value and to list or describe the secret. A user with this permission set cannot modify, rotate, or delete the secret.

"Action": [
    "kms:List*",
    "kms:Describe*",
    "kms:GetSecretValue"
]