When an enterprise has multiple Alibaba Cloud accounts, you can add the accounts to a resource directory for centralized management. Then, you can use the resource sharing feature of Resource Management to enable multiple Alibaba Cloud accounts to use the same Key Management Service (KMS) instance. This topic describes how to share a KMS instance across multiple Alibaba Cloud accounts of an enterprise.
Overview
Scenarios
The account owner of a KMS instance is known as the resource owner and can share the KMS instance with other Alibaba Cloud accounts which are known as principals. The principals can create keys and secrets in the KMS instance, use the keys for server-side encryption in Alibaba Cloud services and data encryption in self-managed applications, and use the secrets to prevent data leaks due to hardcoded sensitive data in your code.
KMS instances can be shared only within a resource directory. For more information about resource directories and resource sharing, see Resource directory overview and Resource Sharing overview.
Limits
Feature limits
Only KMS instances of the software key management type and the hardware key management type can be shared. The instances must be in the Enabled state. Default keys cannot be shared.
KMS instances can be shared only within a resource directory. The principals must belong to the same enterprise entity as the resource owner of the KMS instance. The enterprise entity must pass real-name verification.
If a self-managed application of a principal accesses keys or secrets of a KMS instance across virtual private clouds (VPCs) by using the KMS instance endpoint, the resource owner must associate the VPC of the application with the KMS instance. For more information, see Access a KMS instance from multiple VPCs in the same region.
NoteYou can run the
ping {KMS instance endpoint}command to check whether a self-managed application can access the KMS instance. For example: run theping kst-hzz62****.cryptoservice.kms.aliyuncs.comcommand.A self-managed application can use a KMS endpoint to access secrets of a KMS instance. This method does not require the VPC networks of the application and the KMS instance to be interconnected. A self-managed application cannot use a KMS endpoint to access keys of a KMS instance.
To unshare a KMS instance, principals must delete the keys and secrets that the principals created.
Principals who want to create Resource Access Management (RAM) secrets, ApsaraDB RDS secrets, and Elastic Compute Service (ECS) secrets must submit a ticket to contact technical support to upgrade the KMS instance.
Region limits
Principals cannot use a KMS instance across regions. For example, if a KMS instance resides in the Singapore region, principals can use keys in the KMS instance for server-side encryption in Alibaba Cloud services only in the Singapore region.
Quota limits
If you share a KMS instance with principals, the access management quota of the KMS instance is consumed. The quota is deducted by one for one Alibaba Cloud account to which the principals belong. If the quota is insufficient, you can request a quota increase. For more information, see Upgrade a KMS instance.
The access management quota includes the number of principals and the number of VPCs that are associated with the KMS instance. For example, you want to share a KMS instance with two principals and associate the KMS instance with three VPCs. In this case, you must set the access management quota to at least five to meet your business requirements.
Permissions of principals
When you share a KMS instance, you must grant the AliyunRSDefaultPermissionKMSInstance permission to the required resource share. For more information about permissions, go to the Permission Library page in the Resource Management console.
AliyunRSDefaultPermissionKMSInstance: The permission is provided in two versions: v1 and v2. By default, v2 is used. For more information about how to view the versions of permissions, see Permissions for resource sharing.
AliyunRSPermissionKMSInstanceReadWrite: The permission is deprecated. If you previously used this permission, you can continue to use the permission.
Feature comparison
A tick (√) indicates that the feature is supported. A cross (×) indicates that the feature is not supported.
Category | Feature | Resource owner | Principal |
Instance management | View the details of an instance | ✓ | × |
Configure multi-VPC access | ✓ | × | |
Upgrade an instance | ✓ | × | |
Renew an instance | ✓ | × | |
Unshare an instance | ✓ | × | |
Key management | Create a key | ✓ | ✓ |
| ✓ All keys are supported, including keys that are created by principals. | ✓ Only keys that are created by principals are supported. | |
Cryptographic operation | - | ✓ All keys can be used for server-side encryption in Alibaba Cloud services and data encryption in self-managed applications. | ✓ Only keys that are created by principals can be used for server-side encryption in Alibaba Cloud services and data encryption in self-managed applications. |
Secret management | Create a secret | ✓ | ✓ |
| ✓ All secrets are supported, including secrets that are created by principals. | ✓ Only secrets that are created by principals are supported. | |
Secret retrieval | - | ✓ All secrets are supported, including secrets that are created by principals. | ✓ Only secrets that are created by principals are supported. |
Backup management | - | ✓ All keys and secrets are supported, including keys and secrets that are created by principals. | × |
Application management | Create an application access point (AAP) | ✓ | ✓ |
Examples
Department A of an enterprise purchased a KMS instance. Department B of the enterprise wants to access the KMS instance. The enterprise can manage the Alibaba Cloud accounts of the two departments by using a resource directory in a centralized manner and share the KMS instance across the accounts by using the resource sharing feature. The following figure shows the resource sharing architecture.
Step 1: Enable a resource directory and build a multi-account organizational structure
Use Alibaba Cloud Account M to enable a resource directory. Alibaba Cloud Account M is the management account of the resource directory. Create two folders named Department 1 and Department 2. Invite Alibaba Cloud Account A1 to join the Department A folder, and invite Alibaba Cloud Accounts B1 and B2 to join the Department B folder.
Log on to the Resource Management console by using an account that can be used as a management account.
Enable a resource directory.
For more information, see Enable a resource directory.
Create folders to build an organizational structure for your enterprise.
For more information, see Create a folder.
Create members in the resource directory or invite existing Alibaba Cloud accounts to join the resource directory. Then, move all members to the folders that you created based on your business requirements.
For more information, see Create a member, Invite an Alibaba Cloud account to join a resource directory, and Move a member.
Step 2: Enable resource sharing
Use Alibaba Cloud Account M to enable the resource sharing feature. After the resource sharing feature is enabled for the resource directory, a resource owner can share resources with the resource directory and folders or members in the resource directory. A resource owner can be the management account or a member of a resource directory. For more information, see Enable resource sharing.
Log on to the Resource Management console by using Alibaba Cloud Account M. In the left-side navigation pane, choose .
Click Enable. In the Service-linked Role for Resource Sharing dialog box, click OK.
The system creates a service-linked role named AliyunServiceRoleForResourceSharing to obtain the organizational structure information of the resource directory. For more information, see Service-linked role for Resource Sharing.
Step 3: Share a KMS instance as a resource owner
If you want to share a KMS instance with other Alibaba Cloud accounts, we recommend that you create a resource share to manage the scope of principals that can access your resources.
The KMS instance that you want to share must be in the Enabled state.
You can share a KMS instance in the KMS or Resource Management console.
In the KMS console
Log on to the KMS console by using Alibaba Cloud Account A1. In the top navigation bar, select the region of the KMS instance. In the left-side navigation pane, click Instances.
On the Instances page, click the Software Key Management tab or the Hardware Key Management tab based on the type of your KMS instance.
Find the KMS instance that you want to share and click Share Resources in the Actions column.
In the Add to Resource Share panel, click Create. Then, configure the parameters and click OK.
Parameter
Description
Resource Share Name
The name of the resource share. You can enter a custom value. The name can contain letters, digits, and the following special characters: periods (.), commas (,). underscores (_), and hyphens (-). The name can be up to 50 characters in length.
Add Permissions
The permissions of the principal. To check the permissions of principals, go to the Permission Library page in the Resource Management console.
AliyunRSDefaultPermissionKMSInstance (recommended)
AliyunRSPermissionKMSInstanceReadWrite The permission is deprecated. If you previously used this permission, you can continue to use the permission.
Add Principals
ImportantIf the KMS instance is shared with a principal, the access management quota of the KMS instance is consumed. When you create a resource share, we recommend that you set the Principal Type parameter to Alibaba Cloud Account or Folder.
The principal. Valid values:
Alibaba Cloud Account: Enter the ID of an Alibaba Cloud account in the Principal ID field and click Add to share the KMS instance with the Alibaba Cloud account. In this example, this method is used.
Resource Directory: Share the KMS instance with all members in a resource directory. If a member is added to the resource directory after resource sharing, the KMS instance is automatically shared with the member.
Folder (Organizational Unit): Enter the ID of a folder in the Folder ID field to share the KMS instance with all members in the folder. The ID of a folder starts with fd. Example: fd-gLh1HJ****. If an Alibaba Cloud account is added to the folder as a member after resource sharing, the KMS instance is automatically shared with the account.
If you do not specify a principal when you create a resource share, you can specify a principal when you modify the resource share.
After you share the KMS instance, Being Shared is displayed below the ID of the KMS instance. A principal can log on to the KMS console and view the KMS instance. Shared Resource is displayed below the ID of the KMS instance.
In the Resource Management console
For more information, see Share resources only in a resource directory.
Step 4: Use a KMS instance as a principal
Use a key
Create a key. For more information, see Manage a key.
Use the key to perform cryptographic operations.
Server-side encryption in Alibaba Cloud services: For more information, see Overview of integration with KMS and Alibaba Cloud services that can be integrated with KMS.
Data encryption in self-managed applications: For more information, see SDK references.
Use a secret
Create a secret. For more information, see Getting started with Secrets Manager.
Retrieve a secret by using an SDK. For more information, see SDK references.
What to do next
Add a principal to or remove a principal from a resource share
In the KMS console
Log on to the KMS console. In the top navigation bar, select the region of your KMS instance. In the left-side navigation pane, click Instances.
On the Instances page, click the Software Key Management tab or the Hardware Key Management tab based on the KMS instance type.
Find the KMS instance that you want to manage and click Share Resources in the Actions column.
In the Add to Resource Share panel, select a resource share from the Select Resource Share drop-down list, click Edit in the Principals section, add or remove a principal, and then click OK.
In the Resource Management console
For more information, see Modify a resource share.
Unshare a KMS instance
To unshare a KMS instance, principals must delete the keys and secrets that the principals created. Make sure that the keys or secrets are no longer in use. If keys and secrets that are in use are deleted, your services may become unavailable.
You can perform this operation only in the Resource Management console. For more information, see Delete a resource share.