All Products
Search

This Product

    Key Management Service:Configure a key policy

    Document Center

    Key Management Service:Configure a key policy

    Last Updated:Sep 09, 2026

    To control who can manage and who can use a key, add or remove RAM users and RAM roles in the key policy to designate key administrators and key users. This topic describes how to configure a key policy.

    Configure a key policy in the KMS console

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Keys.

    2. On the Customer Master Keys tab, find the target key and click the key ID or Details in the Actions column.

    3. On the details page, scroll to the Key Policy section, click Configure Key Policy, configure the key policy, and then click OK.

      1. Graphical editing: In this mode, assign authorized principals (RAM users or RAM roles) to predefined roles by using Default policy permissions (Action).

        • Administrator: Principals assigned to this role can perform management operations on the key but cannot perform cryptographic operations. You can assign RAM users and RAM roles within the current Alibaba Cloud account.

        • User: Principals assigned to this role can only use the key for cryptographic operations. You can assign RAM users and RAM roles within the current Alibaba Cloud account.

        • Cross-account User:

          Important

          • Granting permissions to a RAM user or RAM role under another Alibaba Cloud account consumes the Access Management Quota of your KMS instance. Quota consumption is calculated by the number of Alibaba Cloud accounts. After you revoke the authorization, the quota is returned after approximately 5 minutes.

          • You must also configure the corresponding key permissions for the RAM user or role in the RAM console before the principal can use the key. For more information, see Custom policies, Manage RAM user permissions, and Manage permissions for a RAM role.

          • This can be a RAM user or RAM role under another Alibaba Cloud account. Cross-account principals can only use the key for cryptographic operations.

          • Click Add ARN of Cross-account User and enter the ARN of the authorized principal. You can obtain the ARN from the user or role details page in the RAM console.

            • RAM user: Format: acs:ram::<Other Alibaba Cloud account ID>:user/<ramuser>. Example: acs:ram::119285303511****:user/testpolicyuser.

            • RAM role: Format: acs:ram::<Other Alibaba Cloud account ID>:role/<ramrole>. Example: acs:ram::119285303511****:role/testpolicyrole.

      2. Syntax Editor: Directly modify or add permission statements in the syntax editor. The following example shows a sample configuration.

        • Scenario: This example configures a key policy for a key that belongs to Alibaba Cloud account 119285303511****.

          • The current Alibaba Cloud account (119285303511****) has full access to manage and use the key. We recommend that you do not modify this statement.

          • Allow the RAM user (key_ramuser1) under the current Alibaba Cloud account (119285303511****) to manage the key.

          • Allow the RAM user (key_ramuser2) under the current Alibaba Cloud account (119285303511****) and the RAM user (key_ramuser3) under another Alibaba Cloud account (190325303126****) to use the key.

        • Syntax example:

          {
    "Statement": [
        {
            "Action": [
                "kms:*"
            ],
            "Effect": "Allow",
            "Principal": {
                "RAM": [
                    "acs:ram::119285303511****:*"
                ]
            },
            "Resource": [
                "*"
            ],
            "Sid": "kms default key policy"
        },
        {
            "Action": [
                "kms:List*",
                "kms:Describe*",
                "kms:Create*",
                "kms:Enable*",
                "kms:Disable*",
                "kms:Get*",
                "kms:Set*",
                "kms:Update*",
                "kms:Delete*",
                "kms:Cancel*",
                "kms:TagResource",
                "kms:UntagResource",
                "kms:ImportKeyMaterial",
                "kms:ScheduleKeyDeletion"
            ],
            "Effect": "Allow",
            "Principal": {
                "RAM": [
                    "acs:ram::119285303511****:user/key_ramuser1"
                ]
            },
            "Resource": [
                "*"
            ]
        },
        {
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:GenerateDataKey",
                "kms:GenerateAndExportDataKey",
                "kms:AsymmetricEncrypt",
                "kms:AsymmetricDecrypt",
                "kms:DescribeKey",
                "kms:DescribeKeyVersion",
                "kms:ListKeyVersions",
                "kms:ListAliasesByKeyId",
                "kms:TagResource"
            ],
            "Effect": "Allow",
            "Principal": {
                "RAM": [
                    "acs:ram::119285303511****:user/key_ramuser2",
                    "acs:ram::190325303126****:user/key_ramuser3"
                ]
            },
            "Resource": [
                "*"
            ]
        }
    ],
    "Version": "1"
}
          Note

          In the preceding example, the Resource field can only be set to ["*"], which indicates that the policy applies to the current key.

    Limits

    • Key policies are supported only for Customer Master Keys.

    • A key policy must be in JSON format and cannot exceed 32,768 bytes in length.

    • The following actions can be specified in a key policy:

      Warning

      Actions not in this list do not take effect.

       "Action": [
                "kms:List*",
                "kms:Describe*",
                "kms:Create*",
                "kms:Enable*",
                "kms:Disable*",
                "kms:Get*",
                "kms:Set*",
                "kms:Update*",
                "kms:Delete*",
                "kms:Cancel*",
                "kms:TagResource",
                "kms:UntagResource",
                "kms:ImportKeyMaterial",
                "kms:ScheduleKeyDeletion"
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:GenerateDataKey",
                "kms:GenerateAndExportDataKey",
                "kms:AsymmetricEncrypt",
                "kms:AsymmetricDecrypt",
                "kms:DescribeKey",
                "kms:DescribeKeyVersion",
                "kms:ListKeyVersions",
                "kms:ListAliasesByKeyId",
                "kms:TagResource"
            ]

    • Cross-account key authorization: To authorize a RAM user or RAM role under another Alibaba Cloud account to use a key under your account, you must configure permissions in both accounts:

      1. Configure the key policy in the KMS console to grant the usage permission to the target account. Add a policy statement for Cross-account User.

      2. The target account must configure the corresponding key permissions for its RAM user or role in the RAM console.

    Default policy permissions (Action)

    Administrator

    Principals assigned to this role can perform management operations on the key but cannot perform cryptographic operations.

      "Action": [
                "kms:List*",
                "kms:Describe*",
                "kms:Create*",
                "kms:Enable*",
                "kms:Disable*",
                "kms:Get*",
                "kms:Set*",
                "kms:Update*",
                "kms:Delete*",
                "kms:Cancel*",
                "kms:TagResource",
                "kms:UntagResource",
                "kms:ImportKeyMaterial",
                "kms:ScheduleKeyDeletion"
            ]

    Key user/cross-account key user

    Principals assigned to this role can only use the key for cryptographic operations.

     "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:GenerateDataKey",
                "kms:GenerateAndExportDataKey",
                "kms:AsymmetricEncrypt",
                "kms:AsymmetricDecrypt",
                "kms:DescribeKey",
                "kms:DescribeKeyVersion",
                "kms:ListKeyVersions",
                "kms:ListAliasesByKeyId",
                "kms:TagResource"
            ]

    FAQ

    • What is the relationship between a key policy and a RAM permission policy?

      A key policy and a RAM permission policy control access to KMS keys from different dimensions. After you add a RAM user or RAM role to a key policy, you must also configure a RAM permission policy to manage the KMS operation permissions that are already configured for the RAM user or RAM role in the RAM console.

      Note

      For information about permission evaluation priorities, see Permission evaluation priority.

      • Key Policy: A resource-level policy that is attached to a specific key. It declares which identities (RAM users, RAM roles, or Alibaba Cloud accounts) can manage or use the key.

      • RAM permission policy: An identity-level policy that is attached to a RAM user or RAM role. It declares which KMS actions the identity can perform.