Application access points (AAPs) give applications a secure identity for accessing KMS keys and secrets. Each AAP combines three components: permission policies that define what resources can be accessed, network access rules that restrict which IP addresses are allowed, and client keys that serve as the actual credentials your application presents at runtime.
This page covers how to manage all four resources: AAPs, permission policies, network access rules, and client keys.
Prerequisites
Before you begin, ensure that you have:
A KMS instance (required for
Privatenetwork type and cryptographic operations)Access to the KMS console
The permissions required to manage AAPs in your account
Manage an AAP
View AAP details
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Application Access > AAPs.
On the Application Access tab, search for the AAP by Instance ID or AAP name.
Click the AAP name to open the details page. The details page has two tabs:
Policies: Shows the permission policies associated with this AAP. For more information, see Overview of AAPs.
Client Key: Shows each client key's Key ID, Algorithm, Validity Period, and Creation Date. The content of the client key cannot be viewed after creation.
Change permission policies for an AAP
Permission policy changes take up to 5 minutes to take effect. If the change does not take effect, wait 5 minutes and try again.
On the Application Access tab, find the AAP and click its name.
On the Policies tab, click Configure Permission Policy.
In the Update AAP panel, select a different value for Policies. An AAP can have up to three permission policies.
If your existing permission policies do not meet your requirements, create a new one first. See Create a permission policy.
Delete an AAP
Deleting an AAP takes effect immediately. If any client key in the AAP is still in use by an application, that application will lose access to KMS.
Before deleting, confirm that no client keys are in active use:
Go to the Simple Log Service for KMS page. Logs are available for the previous 180 days.
In the search box under
kms_audit_log, enter the client key ID to run a full-text search.If the
access_key_idfield in any result matches the client key ID, the key is still in use.
For more information, see Use Simple Log Service for KMS.
To delete the AAP:
On the Application Access tab, find the AAP and click Delete in the Actions column.
Complete security verification. KMS deletes the AAP.
Manage a permission policy
Create a permission policy
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Application Access > AAPs.
Click the Policies tab, then click Create Policy.
In the Create Permission Policy panel, configure the following parameters and click OK.
| Parameter | Description |
|---|---|
| Policy name | A name for the permission policy. |
| Scope | Determines which KMS gateway handles requests. Select a specific KMS instance if the Network type of your network access rule is Private. Select Shared KMS Gateway if the network type is Public or VPC. |
| RBAC permissions | Controls what the application can do. The available values depend on the Scope setting: <br>• Scope = a specific KMS instance: CryptoServiceKeyUser (use keys for cryptographic operations via Instance API) or CryptoServiceSecretUser (use secrets via Instance API). <br>• Scope = Shared KMS Gateway: SecretUser (access all secrets in the current account via the GetSecretValue API operation). |
| Accessible resources | The specific keys and secrets the application needs to access. If you select multiple secrets and the combined name length exceeds the limit, the error "The specified parameter is not valid." is returned. Use wildcards to work around this limit — for example, secret/rds-ibm* matches all secrets with the prefix rds-ibm. |
| Network access rules | The network access rule to associate with this policy. If you do not need to restrict access by source IP address, leave this blank. For security, associating a network access rule is strongly recommended. |
| Description | A description for the permission policy. |
After creating the permission policy, associate it with an AAP. See Change permission policies for an AAP.
Modify a permission policy
Modifying a permission policy affects all AAPs that use it. Proceed with caution. Changes take up to 5 minutes to take effect.
Modify by policy name:
On the Policies tab, find the policy and click Edit in the Actions column.
In the Modify Permission Policy panel, update RBAC permissions, Accessible resources, or Network access rules, then click OK.
Modify via an associated AAP:
On the Application Access tab, click the AAP name.
On the Policies tab, find the policy to modify and click Edit in the Actions column.
In the Modify Permission Policy panel, update the required fields and click OK.
Delete a permission policy
Before deleting a permission policy, make sure it is not associated with any AAP. Deleting a policy that is still in use will prevent the associated applications from accessing KMS.
On the Policies tab, find the policy and click Delete in the Actions column.
In the Confirm dialog, click OK.
Manage a network access rule
Choose a network type
Network access rules use one of three network types. Choose the type that matches how your application connects to KMS.
| Network type | Endpoint type | Supported operations | Supported regions |
|---|---|---|---|
| Private | KMS instance endpoint | Keys and secrets (all operations, including cryptographic operations) | All regions |
| Public | KMS public endpoint | Secrets only | All regions |
| VPC | KMS VPC endpoint | Secrets only | China (Hangzhou), China (Shanghai), China (Shenzhen), China (Zhangjiakou) |
Which SDK to use:
Cryptographic operations (encrypt, decrypt, sign, verify): Use KMS Instance SDK with network type Private.
Secret value retrieval: Use KMS Instance SDK or a secret SDK.
For high queries per second (QPS) and stronger security, use a secret SDK with network type Private.
If using KMS Instance SDK, set network type to Private and restrict allowed source IPs to addresses in the virtual private clouds (VPCs) associated with your KMS instance.
If using a secret SDK, set network type to Private, Public, or VPC.
Create a network access rule
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Application Access > AAPs.
Click the Network Access Rules tab, then click Create Network Access Rule.
In the Create Network Access Rule panel, configure the following parameters and click OK.
| Parameter | Description |
|---|---|
| Rule name | A name for the network access rule. |
| Network type | Select Private, Public, or VPC. See Choose a network type for guidance. |
| Allowed source IP addresses | The IP addresses from which access is permitted. If your application connects through a proxy server, enter the proxy server's IP address. <br>• Private: Enter the IP addresses in the VPCs associated with your KMS instance. <br>• Public: Enter public IP addresses. <br>• VPC: Enter the VPC IDs and IP addresses within those VPCs. |
| Description | A description for the network access rule. |
After creating the rule, associate it with a permission policy. See Create a permission policy.
Modify a network access rule
Modifying a network access rule affects all AAPs that use it. Proceed with caution.
On the Network Access Rules tab, find the rule and click Edit in the Actions column.
In the Modify Network Access Rule panel, update Allowed source IP addresses and click OK.
Delete a network access rule
Before you delete a network access rule, make sure that the network access rule is not associated with AAPs. Otherwise, related applications cannot access KMS.
On the Network Access Rules tab, find the rule and click Delete in the Actions column.
In the Confirm dialog, click OK.
Manage a client key
A client key is the credential your application uses to authenticate with KMS at runtime. Each client key consists of two files that are downloaded automatically when the key is created:
Application Access Secret (`clientKey_.json`): Contains the private key material. Treat this file as you would a password — store it securely and never commit it to source control.
Password (`clientKey__Password.txt`): The password used to decrypt the Application Access Secret file. Store this separately from the JSON file.
The contents of a client key cannot be retrieved after creation. Download and store both files immediately.
Create a client key
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Application Access > AAPs.
On the Application Access tab, search for the AAP by Instance ID or AAP name.
Click the AAP name. On the details page, click the Client Key tab, then click Create Client Key.
In the Create Client Key panel, configure the following parameters:
Encryption password: Must be 8–64 characters and can contain digits, letters, and the following special characters: `
~ ! @ # $ % ^ & * ? _ -`.Validity period: Defaults to five years. Set this to one year to reduce exposure if the client key is compromised.
Click OK. The browser automatically downloads both files.
Store the two files securely. For loading them in your application, refer to the KMS Instance SDK documentation.
Delete a client key
Deleting a client key takes effect immediately. Any application using it will immediately lose access to KMS.
Before deleting, confirm the key is no longer in use by checking audit logs. See Delete an AAP for the log search procedure.
On the Application Access tab, find the AAP and click its name.
On the Client Key tab, find the client key and click Delete in the Actions column.
In the Confirm dialog, click OK.
Complete security verification. KMS deletes the client key.
What's next
Overview of AAPs — understand the relationship between AAPs, permission policies, network access rules, and client keys
Use Simple Log Service for KMS — monitor and audit KMS access logs