Details of secret policies - Key Management Service - Alibaba Cloud Documentation Center

A secret policy is a resource-based policy that controls which Alibaba Cloud accounts, RAM users, and RAM roles can manage or use a KMS secret. Each secret in a KMS instance must have exactly one secret policy. This topic describes secret policies in detail.

Relationship between secret policies and RAM policies

Policy description

Secret policies and RAM policies control access to KMS secrets from different dimensions. After you add RAM users or RAM roles to a secret policy, you can also configure RAM policies to manage the KMS secret operation permissions for those RAM users or RAM roles.

Secret policy: A resource-based policy attached to a specific secret. It specifies which identities (RAM users, RAM roles, or Alibaba Cloud accounts) can manage or use the secret. For more information, see Configure a secret policy.
RAM policy: An identity-based policy attached to a RAM user or RAM role. It specifies which KMS operations the identity can perform. For more information, see Manage RAM user permissions, Manage permissions for a RAM role, and Custom policies.

Permission evaluation priority

RAM users or RAM roles under the current account (secret creator account)
- Evaluation principle: "Any Allow is sufficient" (OR logic). Access is allowed if either of the following conditions is met and there is no Explicit Deny.
  Note
  For more information about Explicit Deny and Implicit Deny, see How RAM evaluates policies.
  - The KMS secret policy explicitly allows the user or role.
  - The RAM policy explicitly allows the user or role.
- Detailed rules:
  KMS secret policy (resource-based)
  RAM policy (identity-based)
  Evaluation result
  Allow
  Not configured
  Allow
  Not configured
  Allow
  Allow
  Allow
  Allow
  Allow
  Allow
  Deny
  Deny
  Deny
  Allow
  Deny
  Not configured
  Not configured
  Deny
RAM users or RAM roles under a different account (cross-account)
- Evaluation principle: "Both must allow" (AND logic). Access is allowed only when both of the following conditions are met.
  - The KMS secret policy explicitly allows the external user or role (or external account).
  - The RAM policy explicitly allows the external user or role to call KMS operations.
- Detailed rules:
  KMS secret policy (resource-based)
  RAM policy (identity-based)
  Evaluation result
  Allow
  Deny
  Deny
  Deny
  Allow
  Deny
  Allow
  Allow
  Allow
  Not configured
  Not configured
  Deny

Usage notes

Secret policies apply only to secrets within a KMS instance. You can configure a secret policy during secret creation or modify it afterward. For more information, see Manage and use secrets and Configure a secret policy.
Authorizing RAM users or roles from other Alibaba Cloud accounts consumes the Access Management Quota of the KMS instance. The quota is calculated based on the number of Alibaba Cloud accounts. If you revoke cross-account authorization and the instance no longer shares resources with that account, wait approximately 5 minutes for the consumed quota to decrease accordingly.
A secret policy only applies to access control when you access a secret through the KMS service endpoint. If you access a secret through a KMS instance endpoint, access depends on the permission policy configured in the Application Access Point (AAP).
A secret policy must be in JSON format and cannot exceed 32,768 bytes in size.

Secret policy structure

A complete secret policy contains the following elements:

Version: The version of the secret policy. Only version 1 is supported.
Statement: A secret policy contains one or more statements. Each statement includes the following parameters:
- Sid
  Optional. A custom statement identifier. The identifier can be up to 128 characters in length and can contain uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), and the following special characters: _ / + = . @ -
- Effect
  Required. Specifies whether to allow or deny the actions in the statement. Valid values: Allow and Deny.
- Principal
  Required. The identity to which the policy applies. You can specify one of the following:
  - The current Alibaba Cloud account (the account that owns the secret).
  - RAM users or RAM roles under the current Alibaba Cloud account.
  - RAM users or RAM roles under a different Alibaba Cloud account.
    Important
    After you authorize RAM users or roles from another Alibaba Cloud account, you must also use that Alibaba Cloud account to grant the RAM users or roles permission to use the secret in RAM. Otherwise, the RAM identities cannot use the secret.
    For more information, see Custom policy reference for KMS, Manage RAM user permissions, and Manage permissions for a RAM role.
- Action
  Required. The API operations to allow or deny. The value must start with "kms:". Only the following operations are valid. Operations outside this list will not take effect.
  Permission list
```
"Action": [
                "kms:List*",
                "kms:Describe*",
                "kms:PutSecretValue",
                "kms:Update*",
                "kms:DeleteSecret",
                "kms:RestoreSecret",
                "kms:RotateSecret",
                "kms:TagResource",
                "kms:UntagResource"
                "kms:GetSecretValue"
            ]
```
- Resource
  Required. The target resource to which the policy applies. The Resource value can only be *, which indicates the current KMS secret.
- Condition
  Optional. The conditions under which the policy takes effect. A condition element, also called a condition block, consists of one or more condition clauses. Each clause contains a condition operator, a condition key, and a condition value. For more information, see Permission policy elements.
  The format is "Condition": {"condition operator": {"condition key": "condition value"}}.
  - condition operator: For more information, see Condition operator types.
  - condition key and condition value: For the condition keys and valid values supported by key policies, see Policy condition keys.

FAQ

How do I view the secret creator?

Console: Log on to the KMS console. On the Secrets page, open the secret details page and view the Created By field.
OpenAPI: Call the DescribeSecret operation. The Creator field in the response indicates the secret creator.

KMS secret policy (resource-based)	RAM policy (identity-based)	Evaluation result
Allow	Not configured	Allow
Not configured	Allow	Allow
Allow	Allow	Allow
Allow	Deny	Deny
Deny	Allow	Deny
Not configured	Not configured	Deny