A secret policy is a resource-based policy attached to a Key Management Service (KMS) secret. It controls which Alibaba Cloud accounts, Resource Access Management (RAM) users, and RAM roles can manage or use the secret. Every KMS secret has exactly one secret policy.
Use secret policies to:
Grant access to a single secret across multiple RAM users and roles within your account.
Share a secret with RAM users and roles in other Alibaba Cloud accounts.
How secret policies and RAM policies work together
Secret policies (resource-based) and RAM policies (identity-based) are complementary layers of access control.
When a request arrives via the Alibaba Cloud CLI, Alibaba Cloud Management Console, or an API call, the system evaluates both policy types before granting access:
The evaluation rules differ depending on whether the requester belongs to the same account as the secret:
| Scenario | Access requirement |
|---|---|
| Same-account access (RAM user or role) | Allow in Result A or Result B, with no explicit deny in either |
| Cross-account access (RAM user or role from another account) | Allow in both Result A and Result B |
The "current Alibaba Cloud account" of a secret is the account used to create it. To check the creator, open the Secrets page in the KMS console and view Created By on the secret details page. Alternatively, call the DescribeSecret API and read the Creator field in the response.
What this means for configuration
| Goal | What to configure |
|---|---|
| Grant same-account RAM users or roles access | A secret policy in KMS or a RAM policy — either is sufficient |
| Grant cross-account RAM users or roles access | Both a secret policy in KMS and a RAM policy |
For cross-account access, the owner of the external RAM user or role must also grant that user or role the necessary permissions in RAM. See Grant permissions to a RAM user, Grant permissions to a RAM role, and Use RAM to manage access to KMS resources.
Role assignments by account type
Within the current Alibaba Cloud account, RAM users and RAM roles can be assigned as administrators or users of the secret. RAM users and RAM roles from other accounts can only be assigned as users.
Limits and usage notes
| Topic | Detail |
|---|---|
| Supported secrets | Secret policies apply only to secrets stored in KMS instances. |
| Endpoint scope | Secret policies apply only when secrets are accessed through a KMS endpoint. If you access secrets through a KMS instance endpoint, the permission policies of the associated application access points (AAPs) apply instead. |
| Cross-account quota | Granting access to a RAM user or role from another Alibaba Cloud account consumes the KMS instance's Access Management Quota, counted per external account. If you revoke the cross-account access and no other resources in that instance are shared with the same account, the quota is released after approximately 5 minutes. |
| Size and format | A secret policy cannot exceed 32,768 bytes and must be valid JSON. |
To create or update a secret policy, see Manage and use generic secrets and Configure a secret policy.
Secret policy structure
A secret policy is a JSON document with the following fields:
Version
Set to 1. This is the only supported value.
Statement
An array of one or more statements. Each statement contains the following parameters.
Sid
Optional. A unique identifier for the statement. Up to 128 characters, using letters, digits, and the special characters _ / + = . @ -.
Effect
Required. Valid values: Allow and Deny.
Principal
Required. Specifies who the policy applies to. Supported principals:
The current Alibaba Cloud account
RAM users and RAM roles in the current Alibaba Cloud account
RAM users and RAM roles in other Alibaba Cloud accounts
Action
Required. The KMS operations to allow or deny. Values must start with kms:. Permissions outside the following scope have no effect:
"Action": [
"kms:List*",
"kms:Describe*",
"kms:PutSecretValue",
"kms:Update*",
"kms:DeleteSecret",
"kms:RestoreSecret",
"kms:RotateSecret",
"kms:TagResource",
"kms:UntagResource",
"kms:GetSecretValue"
]Resource
Required. Set to *, which represents the current secret.
Condition
Optional. Restricts when the policy takes effect. The format is:
"Condition": {"condition operator": {"condition key": "condition value"}}For supported condition operators, see Policy elements.
For supported condition keys and values, see Policy condition keys.