Key Management Service:SDK Overview

1. Log on to the RAM console. On the Users page, click the name of the target RAM user.

2. On the Authentication tab, in the AccessKey section, click Create AccessKey and follow the on-screen instructions.

3. Grant the RAM user permissions to access KMS.

   • Method 1: Configure an identity-based policy

     In the Actions column of the RAM user, click Grant Permission to attach a built-in system permission policy for KMS to the RAM user. For more information about the system permission policies for KMS, see System policies for KMS.

     Note

     You can also create custom permission policies. For more information, see Create a custom policy.

   • Method 2: Configure a resource-based policy

     KMS supports resource-based policies that grant access permissions for individual keys and secrets. You can use these policies to control which Alibaba Cloud accounts, RAM users, and RAM roles can manage or use KMS keys and secrets. For more information, see Key policies and Secret policies.

An ECS instance RAM role allows you to obtain a temporary access credential (STS token) from within an ECS instance to call KMS API operations, without needing to configure an AccessKey pair.

For more information, see Instance RAM roles.

1. Log on to the RAM console and create a RAM role for a trusted Alibaba Cloud service.

   • Trusted Entity Type: Select Elastic Compute Service.

   • Trusted entity: Select Elastic Compute Service (ECS).

2. Grant the RAM role permissions to access KMS.

   • Method 1: Configure an identity-based policy

     In the Actions column of the RAM role, click Grant Permission to attach a built-in system permission policy for KMS to the RAM role. For more information about the system permission policies for KMS, see System policies for KMS.

     Note

     You can also create custom permission policies. For more information, see Create a custom policy.

   • Method 2: Configure a resource-based policy

     KMS supports resource-based policies that grant access permissions for individual keys and secrets. You can use these policies to control which Alibaba Cloud accounts, RAM users, and RAM roles can manage or use KMS keys and secrets. For more information, see Key policies and Secret policies.

3. Log on to the ECS console and attach the RAM role to an ECS instance.

RAM users or cloud services can assume a role to obtain temporary permissions (STS token) instead of using long-term keys, which reduces the risk of key leaks. For example, in a temporary data processing task, a RAM user or cloud service temporarily assumes a role with a specific RamRoleArn. After the task is complete, the role permissions are revoked, minimizing the risk of exposure.

1. Create a user AccessKey pair

   1. Log on to the RAM console. In the left-side navigation pane, choose Identities > Users. On the Users page, click the name of the target RAM user.

   2. Attach the AliyunSTSAssumeRoleAccess system policy or a custom policy that includes the sts:AssumeRole action to the RAM user.

   3. On the Authentication tab, in the AccessKey section, click Create AccessKey and follow the on-screen instructions.

2. Create and authorize a RAM role:

   1. In the left-side navigation pane, choose Identities > Roles. On the Roles page, click Create Role. For more information, see Create a RAM role.

   2. Grant the RAM role permissions to access KMS.

      • Method 1: Configure an identity-based policy

        In the Actions column of the RAM role, click Grant Permission to attach a built-in system permission policy for KMS to the RAM role. For more information about the system permission policies for KMS, see System policies for KMS.

        Note

        You can also create custom permission policies. For more information, see Create a custom policy.

      • Method 2: Configure a resource-based policy

        KMS supports resource-based policies that grant access permissions for individual keys and secrets. You can use these policies to control which Alibaba Cloud accounts, RAM users, and RAM roles can manage or use KMS keys and secrets. For more information, see Key policies and Secret policies.

3. Obtain the RamRoleArn of the target RAM role. For more information, see View the information about a RAM role.

   1. In the left-side navigation pane, choose Identities > Roles. On the Roles page, click the name of the target role.

   2. On the role details page, find the RamRoleArn in the ARN section.

      Note

      The RamRoleArn is the Alibaba Cloud Resource Name (ARN) of the RAM role to assume. The format is acs:ram::$accountID:role/$roleName, where $accountID is the Alibaba Cloud account ID and $roleName is the RAM role name.

Security Token Service (STS) issues a temporary access credential, an STS token, to a RAM user or RAM role. This token allows access to KMS with specific permissions for a limited validity period. After the token expires, it automatically becomes invalid.

1. Log on to the RAM console to create a RAM user or a RAM role. For more information, see Create a RAM user and Create a RAM role.

2. Grant the AliyunSTSAssumeRoleAccess permission to the RAM user or RAM role. For more information, see Manage RAM user permissions and Grant permissions to a RAM role.

3. Grant the RAM user or RAM role permissions to access KMS.

   • Method 1: Configure an identity-based policy

     In the Actions column of the RAM role or user, click Grant Permission to attach a built-in system permission policy for KMS. For more information about the system permission policies for KMS, see System policies for KMS.

     Note

     You can also create custom permission policies. For more information, see Create a custom policy.

   • Method 2: Configure a resource-based policy

     KMS supports resource-based policies that grant access permissions for individual keys and secrets. You can use these policies to control which Alibaba Cloud accounts, RAM users, and RAM roles can manage or use KMS keys and secrets. For more information, see Key policies and Secret policies.

4. Use the RAM user or RAM role to call the STS AssumeRole operation to obtain a temporary STS access credential. For more information, see AssumeRole.

1. Create an OIDC provider

   1. Log on to the RAM console as a RAM administrator. On the SSO page, click the Role-based SSO tab.

   2. On the OIDC tab, click Create IdP.

   3. On the Create IdP page, configure the provider information. For more information, see Manage OIDC providers.

2. Obtain and save the OIDC identity information (ARN and Client ID)

   1. Go to the SSO page, and on the IdP tab, click the name of the target OIDC provider.

   2. On the IdP details page, you can view the ARN and Client ID.

3. Create and authorize a RAM role for the OIDC provider

   1. Log on to the RAM console as a RAM administrator and go to the Identities > Roles page.

   2. Click Create Role. In the upper-right corner of the creation page, click Switch to Policy Editor.

   3. In the policy editor, specify the OIDC provider. Select the visual editor and configure the parameters as described below.

      Note

      For information about other modes, see Create a RAM role for an OIDC identity provider.

      1. In the Select Trusted Entity section, select IdP.

      2. In the Edit Trust Policy section, configure the following parameters.

         • IdP Type: Select OIDC.

         • IdP: Select the OIDC provider you created earlier.

4. Grant the OIDC RAM role permissions to access KMS

   • Method 1: Configure an identity-based policy

     Return to the Identities > Roles list page and click Grant Permission in the Actions column of the target OIDC role to directly attach a KMS built-in system permission policy to the RAM role. For more information about KMS built-in system permission policies, see Key Management Service System Permission Policy Reference.

     Note

     Custom permission policies are also supported. For more information, see Create a custom policy.

   • Method 2: Configure a resource-based policy

     KMS supports resource-based policies that grant access permissions for individual keys and secrets. You can use these policies to control which Alibaba Cloud accounts, RAM users, and RAM roles can manage or use KMS keys and secrets. For more information, see Key policies and Secret policies.

5. Obtain the target OIDC Role ARN

   1. On the Identities > Roles page, click the name of the target role.

   2. On the role details page, find the OIDC Role ARN in the ARN section.

      Note

      The Role ARN is the ARN of the RAM role to be assumed. The format is acs:ram::$accountID:role/$roleName, where $accountID is the Alibaba Cloud account ID and $roleName is the RAM role name.

6. Issue and save the OIDC token file

   Alibaba Cloud does not support direct OIDC login from the console, but you can complete the OIDC SSO process programmatically. Obtaining an OIDC token involves an OAuth flow, commonly through a standard OAuth 2.0 process from the OIDC identity provider (IdP).

   For example:when an application runs in an ACK cluster with RRSA enabled, the cluster automatically creates and mounts the corresponding service account OIDC token file for the application pod.

1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Application Access > Multi-Cloud Access (formerly AAP).

2. (Optional) Create a network rule.

   Note

   Configuring a network rule to restrict access by source IP address is optional. However, we recommend configuring one for better security.

   1. Click the Network Access Rules tab and then click Create Network Access Rule.

   2. In the Create Network Access Rule panel, set Network Type to Public, enter the Allowed Source IP Addresses, and click OK.

3. Create a permission policy.

   1. Click the Policies tab and then click Create Policy.

   2. In the Create Policy panel, configure the parameters for the shared gateway as described below, and then click OK.

      1. Scope: Shared KMS Gateway

      2. Accessible Resources: Select the secrets you want to access.

      3. (Optional) Network Access Rules: Select the network rule created in the previous step.

4. Create an application access point (AAP).

   1. Click the Application Access tab and then click Create AAP.

   2. In the Create AAP panel, set Mode to Standard Creation, and then configure the parameters as described below.

      Parameter	Description
      Authentication Method	Select ClientKey.
      Encryption Password	Enter an 8- to 64-character string that contains digits, letters, and special characters: ~!@#$%^&*?_-.
      Validity Period	Important We recommend setting the validity period to one year to reduce the risk of ClientKey leaks. Be sure to rotate the ClientKey before it expires to avoid service interruptions. For more information, see Rotate a ClientKey.
      Policies	Select the permission policy that you created in the previous step.

   3. Click OK. The browser automatically downloads the ClientKey. The ClientKey includes the following files:

      • Credential (ClientKeyContent): The default filename is clientKey_****.json.

      • Credential password (ClientKeyPassword): The default filename is clientKey_****_Password.txt.

You can create a ClientKey by using either Quick Create or Standard Create mode. For more information about ClientKeys, see Application access points and Create an application access point.

• Method 1: Quick Create

  This method is convenient and efficient, making it suitable for rapid testing and development. The access credential created this way has full access to all resources in the KMS instance.

  1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Application Access > Multi-Cloud Access (formerly AAP).

  2. On the Application Access tab, click Create AAP. In the Create AAP panel, configure the parameters.

     Parameter	Description
     Mode	Select Quick Creation.
     Scope (KMS Instance)	Select the KMS instance that your application needs to access.
     Application Access Point Name	Enter a name for the application access point.
     Authentication Method	This is set to ClientKey and cannot be changed.
     Default Permission Policy	The value is key/* secret/* and cannot be changed. This means the application can access all keys and secrets in the specified KMS instance.

  3. Click OK. The browser automatically downloads the ClientKey. The ClientKey includes the following files:

     • Credential (ClientKeyContent): The default filename is clientKey_****.json.

     • Credential password (ClientKeyPassword): The default filename is clientKey_****_Password.txt.

• Method 2: Standard Create

  If you need to configure fine-grained access permissions for resources, we recommend that you use the Standard Create method.

  1. Follow the Standard Create instructions in Create an application access point to create a ClientKey for accessing the dedicated gateway. The key parameters are described below:

     1. When configuring network rules, select Private for the network type.

     2. When you configure the scope of the permission rule, select the corresponding KMS Instance ID.

  2. After creation, your browser automatically downloads the ClientKey, which includes:

     • Credential (ClientKeyContent): The file is named clientKey_****.json by default.

     • Credential password (ClientKeyPassword): The file is named clientKey_****_Password.txt by default.