All Products
Search

This Product

    Key Management Service:Overview of AAPs

    Document Center

    Key Management Service:Overview of AAPs

    Last Updated:Mar 31, 2026

    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.

    Important

    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

    RoleScopeSupported operations
    CryptoServiceKeyUserKeys in a KMS instanceCryptographic operations via Instance API. See List of operations by function.
    CryptoServiceSecretUserSecrets in a KMS instanceSecret-related operations via Instance API. See List of operations by function.
    SecretUserAll secrets in the current Alibaba Cloud accountGetSecretValue 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

    ScenarioCredential type
    Application requires identity and behavior authentication to use keys or secrets in a KMS instanceClient 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) roleRAM 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:

    PropertyValue
    Default validity periodFive years (one year recommended)
    Maximum client keys per AAPThree
    StorageKMS does not store client keys. If you lose a client key, delete it and create a new one.
    Compromise responseDelete 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:

    SDKAccess scopeEndpoint type
    KMS Instance SDKKeys and secrets in a KMS instanceKMS instance endpoint (requires client key)
    Secret SDKSecrets in a KMS instance, or secrets across the current Alibaba Cloud accountKMS instance endpoint or KMS endpoint
    Note

    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 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