A KMS instance uses an application access point (AAP) to authenticate caller identity and permissions. When using the KMS instance SDK to call a KMS instance, you must configure access credentials (a ClientKey) for the AAP. This topic describes how to create a ClientKey.
Usage notes
We recommend creating a separate application access point (AAP) for each application you integrate with KMS to isolate its access permissions.
The validity period of a ClientKey is 5 years by default. You can specify a custom validity period when you create a ClientKey. We recommend that you set the validity period to 1 year. You must replace the key before it expires to prevent access issues with KMS. For more information, see Replace a ClientKey.
For more information, see .
Create access credentials
You can create access credentials in two ways: quick creation and standard creation. The quick creation method is fast, convenient, and ideal for testing and development. It grants full access to all resources in the KMS instance. For fine-grained access control, use the standard creation method.
Quick creation
Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
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 custom name for the application access point.
Authentication Method
Defaults to ClientKey and cannot be changed.
Default Permission Policy
Defaults to
key/*andsecret/*and cannot be changed. This policy grants the application access to all keys and secrets in the specified KMS instance.Click OK. The browser automatically downloads the ClientKey.
A ClientKey includes Application Access Secret and ClientKeyPassword. The default filename for Application Access Secret is
clientKey_****.json. The default filename for ClientKeyPassword isclientKey_****_Password.txt.
Standard creation
Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Create a network access rule.
NoteA network access rule is optional if you do not need to restrict access by source IP address. However, we recommend creating one for enhanced security.
On the Network Access Rules tab, click Create Network Access Rule.
In the Create Network Access Rule panel, configure the parameters and click OK.
Parameter
Description
Rule Name
Enter a custom name for the network access rule.
Network Type
Select Private.
Allowed Source IP Addresses
Typically, enter the IP address of your application server. If you use a proxy, enter the proxy's IP address.
Description
Enter a custom description.
Create a permission policy.
On the Policies tab, click Create Policy.
In the Create Policy panel, configure the parameters and click OK.
Parameter
Description
Policy Name
Enter a custom name for the permission policy.
Scope
Select your KMS instance.
RBAC Permissions
CryptoServiceKeyUser: Allows the application to use keys in the KMS instance. This role grants permissions for cryptographic operations of instance APIs. For more information, see Key-related operations.
CryptoServiceSecretUser: Allows the application to use secrets in the KMS instance. This role grants permissions for secret-related operations of instance APIs. For more information, see Secret-related operations.
Accessible Resources
Select the keys and secrets that the application needs to access.
ImportantIf the combined length of the names for the selected secrets exceeds the limit, an 'InvalidParameter' error is returned. In this case, use wildcards to specify the accessible secrets.
For example, enter
secret/rds-ibm*to grant access to all secrets that have the prefixrds-ibm.Network Access Rules
Select the network access rule that you created.
NoteSelecting a network access rule is optional if you do not need to restrict access by source IP address. However, we recommend selecting one for enhanced security.
Description
Enter a custom description.
Create an application access point (AAP).
Click the Application Access tab and then click Create AAP.
In the Create AAP panel, configure the parameters.
Parameter
Description
Mode
Select Standard Creation.
Application Access Point Name
Enter a custom name for the application access point.
Authentication Method
Select ClientKey.
Encryption Password
This password is used to encrypt the ClientKey. It must be 8 to 64 characters long and contain characters from at least two of the following groups: digits, uppercase letters, lowercase letters, and special characters (
~!@#$%^&*?_-).Validity Period
The validity period of the ClientKey.
ImportantWe recommend setting the validity period to one year to reduce the risk of a ClientKey leak. You must replace the ClientKey before it expires to avoid service disruptions. For more information, see Replace a ClientKey.
Policies
Select the permission policy that you created.
Description
Enter a custom description.
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.
Required information
To integrate the SDK with your application, you need the following information. Store it securely.
ClientKey: This refers to the ClientKeyContent, which is automatically downloaded after creation. The default filename is
clientKey_****.json.ClientKeyPassword: This is automatically downloaded after you create the ClientKey. The default filename is
clientKey_****_Password.txt.KMS instance CA certificate:
On the Instances page, find the Instance CA Certificate section and click Download.
In the Instance CA Certificate dialog box, select an instance ID, and then click Download. Store the certificate securely.
The default filename of the downloaded CA certificate is PrivateKmsCA_kst-**.pem.
KMS instance VPC endpoint:
On the Instances page, click the Software Key Management or Hardware Key Management tab, and then select your KMS instance.
Click the instance ID to go to the details page and view the Instance VPC Endpoint.