Key Management Service (KMS) uses application access points (AAPs) to control how self-managed applications authenticate and access keys and secrets in a KMS instance. Before an application can use a key or secret, it must authenticate through an AAP.
An AAP contains two components: a permission policy and a credential.
Create a separate AAP for each application that accesses KMS. This way, each application has its own access permissions and can be audited independently.
How it works
Each AAP enforces two layers of control:
-
Permission policy — defines which keys and secrets the application can access, and from which IP addresses
-
Credential — authenticates the application's identity before granting access
Permission policies
A permission policy specifies which KMS resources an application can access and under what conditions. Each AAP supports up to three permission policies.
Each policy includes the following:
-
RBAC permissions — the operations the application is allowed to perform
-
Accessible resources — the keys or secrets the application can access
-
Network access rules — the source IP addresses from which access is allowed
RBAC permissions
| Role | Scope | Supported operations |
|---|---|---|
| CryptoServiceKeyUser | Keys in a KMS instance | Cryptographic operations via Instance API. See List of operations by function. |
| CryptoServiceSecretUser | Secrets in a KMS instance | Secret-related operations via Instance API. See List of operations by function. |
| SecretUser | All secrets in the current Alibaba Cloud account | GetSecretValue via OpenAPI |
Credentials
A credential proves the identity of the application accessing KMS. Two credential types are supported: client key and RAM role.
Choose a credential type
| Scenario | Credential type |
|---|---|
| Application requires identity and behavior authentication to use keys or secrets in a KMS instance | Client key |
| Application runs on Elastic Compute Service (ECS), Container Service for Kubernetes (ACK), or Function Compute, and is associated with a Resource Access Management (RAM) role | RAM role |
Client key
A client key signs requests from the application to KMS and verifies those signatures. It consists of two parts:
-
Application Access Secret(ClientKeyContent)
-
Password
Lifecycle limits:
| Property | Value |
|---|---|
| Default validity period | Five years (one year recommended) |
| Maximum client keys per AAP | Three |
| Storage | KMS does not store client keys. If you lose a client key, delete it and create a new one. |
| Compromise response | Delete the compromised key immediately and create a replacement. |
To rotate a client key before it expires, see Change a client key. After switching to the new key, delete the old one from KMS.
RAM role
Use a RAM role when your application runs on ECS, ACK, or Function Compute, is already associated with a RAM role, and you need to retrieve a secret value by using a KMS endpoint. KMS authenticates OpenAPI requests using RAM — no client key is required.
SDKs that support client key authentication
Different KMS SDKs support different authentication methods. For a full overview, see SDK references.
The following SDKs support client key authentication:
| SDK | Access scope | Endpoint type |
|---|---|---|
| KMS Instance SDK | Keys and secrets in a KMS instance | KMS instance endpoint (requires client key) |
| Secret SDK | Secrets in a KMS instance, or secrets across the current Alibaba Cloud account | KMS instance endpoint or KMS endpoint |
When using Secret SDK with a KMS endpoint, you can authenticate with a client key, an AccessKey pair of a RAM user, or a RAM role. The endpoint type depends on how you configure the permission policy scope: set it to a KMS instance to use a KMS instance endpoint, or set it to Shared KMS Gateway to use a KMS endpoint.
Client key expiration notifications
Alibaba Cloud sends expiration notifications by email or internal message at the following intervals before a client key expires: six months, three months, one month, and seven days.
To set up proactive alerts, configure CloudMonitor to send notifications 180 days, 90 days, 30 days, and 7 days before expiration. See SMS、Alert events.
Logs and audit
Management events
KMS integrates with ActionTrail to record management events of AAPs. See Audit events of KMS and Use ActionTrail to query KMS events.
Client key call logs
KMS integrates with Simple Log Service (SLS) to record calls made using client keys. Logs are retained for 180 days and are searchable on the Simple Log Service for KMS page. To check whether a specific client key has been used, enter its ID in the search box under kms_audit_log. If the access_key_id field in the results matches the client key ID, the key has been called.
Next steps
-
Access a KMS instance by using an AAP — create an AAP and integrate it with your application
-
SDK references — choose and integrate an SDK
-
Endpoint description — understand the difference between KMS instance endpoints and KMS endpoints
-
Performance quotas — QPS (queries per second) limits