Use a KMS instance across accounts - Key Management Service

In an enterprise environment, managing cryptographic keys separately across different accounts increases costs and complicates security policy enforcement. The cross-account sharing feature of Key Management Service (KMS) lets you securely share a single KMS instance with multiple member accounts within your organization. This streamlines key management, centralizes security control, and optimizes costs.

How it works

KMS instance sharing is built on Alibaba Cloud's Resource Directory and Resource Sharing services. The workflow is as follows:

Set up an organization: Use Resource Directory to organize all relevant Alibaba Cloud accounts into a single organization for unified management.
Share resources: The resource owner creates a resource share using the Resource Sharing service, adds the KMS instance as a shared resource, and specifies other members in the Resource Directory as principals.
Grant permissions:
- Permission policy: When creating the share, the resource owner attaches a predefined permission policy (AliyunRSDefaultPermissionKMSInstance). The Resource Sharing service then applies this policy to the specified principals.
- Sharing model: Two modes, Independent Ownership and Joint Ownership, define permissions for using resources (keys and secrets) within the KMS instance.
- RAM user: To grant permissions for specific operations, such as kms:Encrypt and kms:Decrypt, the principal must configure a resource access management (RAM) policy for its RAM identities (RAM users or roles).

Use case example: Department A in an enterprise purchases a KMS instance. If department B also needs to use a KMS instance, the enterprise can centralize its Alibaba Cloud accounts using Resource Directory and then share department A's KMS instance using the Resource Sharing service. The architecture is shown below:

Usage notes

Instance requirements:
You can only share enabled software key management instances and hardware key management instances.
Account and organization requirements:
- The instance owner and the principals must belong to the same verified enterprise.
- The instance owner and the principals must belong to the same resource directory.

Choose a sharing mode

Feature	Independent ownership	Joint ownership
Use cases	Required when you have cross-account secrets with the same name or need to isolate permissions.	Ideal for internal collaboration where a central team (such as IT or security) needs to manage and audit all keys and secrets.
Core characteristic	Independent data ownership: The resource owner cannot manage or use the keys and secrets created by the principal.	Shared data ownership: The resource owner can manage and use the keys and secrets created by the principal.
Cross-account resources with the same name	Allowed. The principal and the resource owner can create secrets with the same name within the instance.	Not allowed. All key and secret names within the instance must be unique.
Mode change	Cannot be changed to joint ownership.	Can be changed to independent ownership.

For more information about the permission differences between the two modes, see Appendix: Feature permissions in different sharing modes.

Procedure

Configure sharing (instance owner)

Step 1: Prepare a resource directory and enable intra-organization sharing

Enable Resource Directory:

Log on to the console
Use the management account to log on to the Resource Management console.
Enable Resource Directory
In the navigation pane on the left, select Resource Directory > Enable Resource Directory. Click Enable Resource Directory. For detailed instructions, see Enable a resource directory.
Create a folder
In the navigation pane on the left, select Resource Directory > Management.In the upper-right corner of the page that appears, click Resource Organization View. In the resource directory tree on the left, click the target folder. On the Member tab, click Create Folder. Enter a Folder Name and click OK. For detailed instructions, see Create a folder.

Configure members

On the Member tab, click Create Member or Invite Member, and follow the instructions in Create a member, Invite an Alibaba Cloud account to join a resource directory, and Move a member to configure information such as the account name, account ID, and billing account.

Invite members

Parameter	Description
Account ID or Logon Email Address	Account ID: To obtain the ID, see How do I view the ID of an Alibaba Cloud account? Logon email: The email address used to register the account. If no logon email is associated with the account, enter the account ID instead. You can enter multiple account IDs separated by commas (,) to invite them in batches.
Remarks	Enter a remark for the invitation to help the invitee verify the invitation's authenticity and expedite approval.
Tag	Bind tags to the member for easier tag-based management.
Parent Folder	The folder to which the account belongs. By default, the invited account is placed in the root folder. Click Modify to move the member to a different folder as needed. You can also change this after the invitation is accepted.

Create member

Parameter	Description
Alibaba Cloud Account Name	The Alibaba Cloud account name is the unique identifier for the member and must be unique within the resource directory. The name must be 2 to 50 characters long and can contain letters, numbers, and the special characters `_.-`. It must start and end with a letter or a number and cannot contain consecutive special characters `_.-`.
Display Name	The display name must be 2 to 50 characters long and can contain Chinese characters, letters, digits, and the special characters `_.-`.
Billing Account	Set the account responsible for paying the new member's fees. Use Management Account for Settlement of New Member: Designates the management account of the Resource Directory as the billing account. Use Existing Member for Settlement of New Member: Designates an existing member of the Resource Directory as the billing account. In the Select an existing member panel, choose a member from the directory tree. Note A member cannot be selected if it cannot make payments. For more information, see Overview. Use New Member Itself for Settlement: Designates the current member as its own billing account.
Tag	Bind tags to the member for easier tag-based management.
Parent Folder	By default, the created member is placed in the root folder. Click Modify to move the member to a different folder as needed. You can also change this after the member is created.

Enable resource sharing
After you enable resource sharing, a resource owner, which can be a management account or a member, can share resources with the entire Resource Directory, its folders, or specific members. For more information, see Enable resource sharing in a resource directory.
1. Use the management account of the Resource Directory to log on to the Resource Sharing console. In the navigation pane on the left, select Resource Sharing > Settings.
2. Click Enable, and then click OK in the Resource Sharing Service-Linked Role dialog box.
  Note
  The system automatically creates a service-linked role named AliyunServiceRoleForResourceSharing to retrieve organization information from Resource Directory. For more information, see Service-linked role for Resource Sharing.

Step 2: Configure the shared KMS instance

This section guides the resource owner on how to share a KMS instance with one or more principals.

Log on to the console
As the instance owner, log on to the Key Management Service console. Select a region in the top menu bar, and in the navigation pane on the left, click Instances.
Select a sharing mode
On the Instances page, find the target KMS instance and click Share Resources in the Actions column. In the RD Multi-account Sharing Settings panel, select a sharing mode.

Configure resource shares

In the Add to Resource Share panel, select an existing resource share or create a new one.

Comparison	Create (Recommended)	Select an existing resource share
Use cases	Use this when sharing for the first time or when you need to isolate permissions.	Use this to add the current instance to an existing resource share and reuse its principals and permissions.
Features	Permission isolation: Contains only the current KMS instance with independent permissions. Scope of control: Only newly added accounts can use the shared instance.	Permission sharing: All existing principals of the resource share will automatically gain access to the new instance, consuming the instance's access management quota. Any permission changes to this resource share will affect all resources within it. Scope of control: Both the original principals and newly added accounts can use the shared instance. Warning This may lead to unintended permission escalation and quota consumption. Proceed with caution.

Configure sharing parameters
Specify the following configurations for the selected method and click OK.
Create (Recommended)
- Resource Share Name
  The name can be up to 50 characters in length and can contain Chinese characters, letters, digits, and the following special characters: ., _, and -.
- Principals
  Specify the accounts that can use this KMS instance.
  Important
  We recommend adding by Folder or Alibaba Cloud Account for fine-grained control. Each addition consumes the instance's Access Management Quota.
  If you add or remove principals from an existing resource share, the change affects all resources within that share.
  Add the following three types of principals:
  - Alibaba Cloud Account: Share resources only with specified Alibaba Cloud accounts (IDs).
  - Resource Directory Organization: Share resources with all member accounts in the entire resource directory, including members added later.
  - Folder (Organizational Unit): Enter the folder ID to share resources with all members in the folder, including members added later. The folder ID format is fd-xxxxxxxx. To view folder information, see View the basic information of a folder.
- Add Permissions
  Configure permissions for the principal. For details, see the Permission Library in the Resource Sharing console.
  - AliyunRSDefaultPermissionKMSInstance (Recommended): Two versions (v1, v2) are available. New shares default to using version v2. To check the version, see View permission details.
  - AliyunRSPermissionKMSInstanceReadWrite (Deprecated): This permission is still functional for existing resource shares but is not recommended for new ones.
Select an existing resource share
- Select Resource Share
  The system synchronizes all resource shares in the current account. For more information, see Create a resource share.
- Shared Resources
  This list automatically displays the existing resources in the selected resource share (read-only). After this operation, the current KMS instance will be added to this share.
- Principals
  Specify the accounts that can use this KMS instance.
  Important
  We recommend adding by Folder or Alibaba Cloud Account for fine-grained control. Each addition consumes the instance's Access Management Quota.
  If you add or remove principals from an existing resource share, the change affects all resources within that share.
  Add the following three types of principals:
  - Alibaba Cloud Account: Share resources only with specified Alibaba Cloud accounts (IDs).
  - Resource Directory Organization: Share resources with all member accounts in the entire resource directory, including members added later.
  - Folder (Organizational Unit): Enter the folder ID to share resources with all members in the folder, including members added later. The folder ID format is fd-xxxxxxxx. To view folder information, see View the basic information of a folder.
- Add Permissions
  Configure permissions for the principal. For details, see the Permission Library in the Resource Sharing console.
  - AliyunRSDefaultPermissionKMSInstance (Recommended): Two versions (v1, v2) are available. New shares default to using version v2. To check the version, see View permission details.
  - AliyunRSPermissionKMSInstanceReadWrite (Deprecated): If you previously used this permission, continue to use it.

Use the shared instance (principal)

As the principal, you must first verify that the instance has been shared successfully. You can then create and use keys or secrets within the shared instance.

Log on to the console
The principal logs on to the Key Management Service console. On the Instances page, find a KMS instance with a Being Shared tag.
Create keys and secrets
On the Keys or Secrets tab, click Create Key or Create Secret. Select the shared Instance for KMS Instance. For other settings, see Create a key and Create a secret.
Grant permissions to RAM users:
Configure RAM policies for your RAM users or roles to grant permissions for specific KMS API calls, such as kms:Encrypt and kms:Decrypt. For instructions, see Use RAM for access control.
Use keys and secrets
After successfully creating keys and secrets, you can use them in other Alibaba Cloud services or self-managed applications. For details, see the following documents:
- Server-side encryption for cloud products: Overview of KMS integration for cloud products and Cloud products that support KMS integration.
- Integrate secrets with cloud services: Integrate cloud products with KMS secrets.
- Integrate KMS with self-managed applications (for keys and secrets): Self-built application integration with KMS.

Manage and maintain the share

Modify the principals of a resource share

From the KMS console
1. As the instance owner, log on to the Key Management Service console. In the top menu bar, select a region. In the navigation pane on the left, click Instances.
2. On the Instances page, click the Software Key Management tab or the Hardware Key Management tab based on the KMS instance type.
3. Find the KMS instance that you want to manage and click Share Resources in the Actions column.
4. In the RD Multi-account Share Settings panel, select a Resource Share. In the Principals section, click Edit to add or remove principals, and then click OK.
From the Resource Sharing console
For detailed instructions, see Modify a resource share.

Revoke sharing for a KMS instance

Revoking a share is performed by deleting the resource share. After the resource share is deleted, all principals in the resource share can no longer access the resources in the resource share.

Important

Before revoking a share, the principal must delete all keys and secrets they created. Otherwise, the revocation will fail. Ensure that no associated resources are still in use to avoid business disruptions.
Perform this operation only in the Resource Sharing console.

Log on to the Resource Sharing console using a management account.
In the left-side navigation pane, choose Resource Sharing > Resources I Share. On the page that opens, find the target resource share and click its ID.
In the upper-right corner of the page that appears, click Delete Resource Share. In the Delete Resource Share dialog box, click OK.

Apply in production

When deploying and using a shared instance in a production environment, follow these guidelines to ensure system stability, security, and compliance.

Network connectivity
If a principal's self-managed application is deployed in a VPC and needs to access KMS through a private gateway, the instance owner must attach the principal's VPC to the shared KMS instance to enable internal-facing access. For instructions, see Access a KMS instance from multiple VPCs in the same region.
Audit and compliance
- Resource owner: Must enable ActionTrail for your account to record all management operations on the shared instance and key operations performed by principals.
- Principal: We recommend enabling ActionTrail to record all API calls within your account.
Change management:
- Revoke sharing: Before revoking a sharing or deleting a resource share, the principal must delete all keys and secrets they created in the shared instance. If any resources remain, the revocation fails. Ensure that no associated resources are in use to avoid business disruptions. To learn how to revoke a share, see Revoke a KMS instance share.
- Modify principals: Adding or removing principals from a resource share affects all resources within that share. To avoid permission conflicts, we recommend creating separate resource shares for different business scenarios or teams. To learn how to make changes, see Modify the principal of a resource share.

Limitations and quotas

Feature limitations
- Default keys cannot be shared, such as alias/acs/oss.
- Principals cannot use a shared KMS instance across regions.
- In Joint Ownership mode, all key and secret names within the instance must be globally unique.
Access Management Quota
Sharing a KMS instance consumes the resource owner's Access Management Quota. If the quota is insufficient, upgrade the KMS instance promptly.