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

A secret policy is a resource-based policy for Key Management Service (KMS) secrets. Secret policies are used to control access to KMS secrets and determine which Alibaba Cloud accounts, Resource Access Management (RAM) users, and RAM roles have permissions to manage or use KMS secrets. Every KMS secret must have exactly one secret policy. This topic describes the details of secret policies.

Relationship between secret policies and RAM policies

Secret policies allow you to specify Resource Access Management (RAM) users and RAM roles within the current Alibaba Cloud account to which a secret belongs as administrators or users of the secret. RAM users and RAM roles within other Alibaba Cloud accounts can be specified only as users.

You can also configure identity-based policies in RAM. The policies determine which Alibaba Cloud accounts, RAM users, and RAM roles can manage or use specific secrets. For more information, see Grant permissions to a RAM user, Grant permissions to a RAM role, and Use RAM to manage access to KMS resources.

When an Alibaba Cloud account, a RAM user, or a RAM role sends a request to access KMS resources by using Alibaba Cloud CLI, in the Alibaba Cloud Management Console, or by calling API operations, the system determines whether to allow the request based on a policy-based evaluation process. The following figure shows the process.

The system determines the final result based on the following principles:

If Allow is returned but Explicit Deny is not returned in Result A or Result B, RAM users or RAM roles of the current Alibaba Cloud account can manage or use the secret.
Note
The current Alibaba Cloud account of a secret is the Alibaba Cloud account that is used to create the secret. You can view the creator of a secret by using one of the following methods:
- Log on to the KMS console. On the Secrets page, go to the secret details page and view the value of Created By.
- Call the DescribeSecret operation and view the value of Creator in the response.
If Allow is returned in both Result A and Result B, RAM users or RAM roles of other Alibaba Cloud accounts can use the secret.

Take note of the following information:

If you want to allow RAM users or RAM roles of the current Alibaba Cloud account to manage or use a secret, you need to only configure a secret policy in KMS or a policy in RAM to allow the RAM users or RAM roles to manage or use the secret.
If you want to allow RAM users and RAM roles of other Alibaba Cloud accounts to use a secret, you must configure both a secret policy in KMS and a policy in RAM to allow the RAM users or RAM roles to use the secret.

Usage notes

Only secrets in KMS instances support secret policies. You can configure a secret policy when you create a secret or modify the secret policy after the secret is created. For more information, see Manage and use generic secrets and Configure a secret policy.
If you grant RAM users or RAM roles of other Alibaba Cloud accounts permissions to access a KMS instance, Access Management Quota of the KMS instance is consumed. The consumed quota is calculated based on the number of Alibaba Cloud accounts. If you revoke the permissions and no resources of the KMS instance are shared to other Alibaba Cloud accounts, wait approximately 5 minutes and then query the quota. The consumed quota is restored.
Secret policies apply only if secrets are accessed by using an endpoint of KMS. If you use the endpoint of a KMS instance to access secrets, the permission policies configured in application access points (AAPs) that are associated with the KMS instance apply.
The content of a secret policy cannot exceed 32,768 bytes in length and must be in the JSON format.

Secret policy description

A secret policy contains the following content:

Version: the version of the secret policy. Set the value to 1.
Statement: the statement of the secret policy. Each secret policy contains one or more statements. Each statement contains the following parameters.
- Sid
  Optional. The statement identifier of a custom statement. The value can be up to 128 characters in length and can contain letters, digits, and the following special characters: _ / + = . @ -
- Effect
  Required. Specifies whether the permissions in a policy statement are allowed or denied. Valid values: Allow and Deny.
- Principal
  Required. The authorization principal of the policy. The following principals are supported:
  - The current Alibaba Cloud account.
  - RAM users and RAM roles of the current Alibaba Cloud account.
  - RAM users and RAM roles of other Alibaba Cloud accounts.
    Important
    If you grant a RAM user or RAM role of other Alibaba Cloud accounts permissions to use a secret, you must use the Alibaba Cloud account of the RAM user or RAM role to grant the RAM user or RAM role permissions to use the secret in RAM.
    For more information, see Use RAM to manage access to KMS resources, Grant permissions to a RAM user, and Grant permissions to a RAM role.
- Action
  Required. The API operation that you want to allow or deny. The value must start with kms:. The following content describes the permission scope. If you specify permissions outside the scope, the permissions do not take effect.
  Permissions
```
"Action": [
                "kms:List*",
                "kms:Describe*",
                "kms:PutSecretValue",
                "kms:Update*",
                "kms:DeleteSecret",
                "kms:RestoreSecret",
                "kms:RotateSecret",
                "kms:TagResource",
                "kms:UntagResource"
                "kms:GetSecretValue"
            ]
```
- Resource
  Required. Set the value to an asterisk (*), which specifies the current secret.
- Condition
  Optional. Specify the conditions that are required for a policy to take effect. The Condition element is considered a condition block, which contains one or more conditions. Each condition consists of conditional operators, condition keys, and condition values. For more information, see Policy elements.
  Format: "Condition": {"condition operator": {"condition key": "condition value"}}.
  - condition operator: For more information, see Policy elements.
  - condition key and condition value: the condition keys and values supported by key policies. For more information, see Condition keys.

Sample secret policy

Configure a secret policy for a secret within the 119285303511**** Alibaba Cloud account. Example:

Grant the current Alibaba Cloud account full permissions to manage and use the secret.
Grant the RAM user named secret_ramuser1 within the current Alibaba Cloud account permissions to manage the secret.
Grant the RAM user named secret_ramuser2 within the current Alibaba Cloud account and the RAM user secret_ramuser3 within the 190325303126**** Alibaba Cloud account permissions to use the secret.

{
    "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"
}