An application access point (AAP) is the identity your self-managed application uses to authenticate against a Key Management Service (KMS) instance. Without an AAP, applications cannot call KMS Instance SDK to perform cryptographic operations or retrieve secrets from a KMS instance.
An AAP is only required when calling KMS Instance SDK. If you use keys in a KMS instance for server-side encryption in Alibaba Cloud services, or call KMS SDK to access secrets, you do not need an AAP.
This tutorial walks through creating an AAP and its supporting resources—network rule, access control policy, and client key—using Terraform.
To run the sample code with a few clicks, visit Terraform Explorer.
How it works
Creating a functional AAP requires four Terraform resources, built in dependency order:
Network rule (
alicloud_kms_network_rule) — defines which source private IP ranges are allowed to connect to the KMS instance.Access control policy (
alicloud_kms_policy) — specifies which keys and secrets the application can access, and binds a network rule to enforce network-level restrictions.AAP (
alicloud_kms_application_access_point) — the application identity that references one or more access control policies.Client key (
alicloud_kms_client_key) — the credential file your application loads at runtime to authenticate as the AAP.
Think of the AAP as the application's username and the client key as its password file.
Prerequisites
Before you begin, ensure that you have:
A Resource Access Management (RAM) user with the
AliyunKMSFullAccesspolicy attached. For instructions, see Create a RAM user and Grant permissions to a RAM user. The minimum policy required is:{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": ["kms:*"], "Resource": ["*"], "Condition": {} } ] }An AccessKey pair for the RAM user. See Create an AccessKey pair.
Terraform 0.12.28 or later. Run
terraform --versionto check. Set up Terraform using one of these methods:Method Best for Terraform Explorer Quick testing with no local setup Cloud Shell Low-overhead access with pre-configured credentials Local installation Unstable networks or custom environments A KMS instance. The example in this tutorial creates the instance as part of the same Terraform configuration.
Required resources
alicloud_kms_network_rule: Creates a network rule.
alicloud_kms_application_access_point: Creates an AAP.
alicloud_kms_client_key: Creates a client key.
alicloud_kms_policy: Creates an access control policy.
Create an AAP
Step 1: Write the Terraform configuration
Create a working directory and add a main.tf file with the following content.
The configuration creates a KMS instance, a network rule, an access control policy, an AAP, and a client key in one pass.
variable "region" {
default = "cn-heyuan"
}
provider "alicloud" {
region = var.region
}
variable "instance_name" {
default = "tf-kms-vpc-172-16"
}
variable "instance_type" {
default = "ecs.n1.tiny"
}
# Query available zones that support the required instance type and disk category.
data "alicloud_zones" "default" {
available_disk_category = "cloud_efficiency"
available_resource_creation = "VSwitch"
available_instance_type = var.instance_type
}
# Create a virtual private cloud (VPC).
resource "alicloud_vpc" "vpc" {
vpc_name = var.instance_name
cidr_block = "192.168.0.0/16"
}
# Create vSwitch 1 (192.168.10.0/24).
resource "alicloud_vswitch" "vsw" {
vpc_id = alicloud_vpc.vpc.id
cidr_block = "192.168.10.0/24"
zone_id = data.alicloud_zones.default.zones.0.id
vswitch_name = "terraform-example-1"
}
# Create vSwitch 2 (192.168.20.0/24).
resource "alicloud_vswitch" "vsw1" {
vpc_id = alicloud_vpc.vpc.id
cidr_block = "192.168.20.0/24"
zone_id = data.alicloud_zones.default.zones.0.id
vswitch_name = "terraform-example-2"
}
# Create a KMS instance (software key management, product_version = "3").
resource "alicloud_kms_instance" "default" {
product_version = "3"
vpc_id = alicloud_vpc.vpc.id
zone_ids = [
"cn-heyuan-a",
"cn-heyuan-b",
]
vswitch_ids = [
alicloud_vswitch.vsw.id, alicloud_vswitch.vsw1.id
]
vpc_num = "1"
key_num = "1000"
secret_num = "100"
spec = "1000"
}
# Save the CA certificate of the KMS instance to a local file.
resource "local_file" "ca_certificate_chain_pem" {
content = alicloud_kms_instance.default.ca_certificate_chain_pem
filename = "ca.pem"
}
# Create a network rule that allows connections from 172.16.0.0/12.
resource "alicloud_kms_network_rule" "network_rule_example" {
network_rule_name = "sample_network_rule"
description = "description_test_module"
source_private_ip = ["172.16.0.0/12"]
}
# Create an access control policy that grants key and secret permissions,
# and enforces the network rule above.
resource "alicloud_kms_policy" "policy_example" {
policy_name = "sample_policy"
description = "description_test_module"
permissions = ["RbacPermission/Template/CryptoServiceKeyUser", "RbacPermission/Template/CryptoServiceSecretUser"]
resources = ["key/*", "secret/*"]
kms_instance_id = alicloud_kms_instance.default.id
access_control_rules = <<EOF
{
"NetworkRules":[
"alicloud_kms_network_rule.network_rule_example.network_rule_name"
]
}
EOF
}
# Create an AAP and attach the access control policy.
resource "alicloud_kms_application_access_point" "application_access_point_example" {
application_access_point_name = "sample_aap"
policies = [alicloud_kms_policy.policy_example.policy_name]
description = "aap_description"
}
# Create a client key for the AAP.
# The private key is saved to ./client_key.json — store it securely.
resource "alicloud_kms_client_key" "client_key" {
aap_name = alicloud_kms_application_access_point.application_access_point_example.application_access_point_name
password = "testPassword@"
not_before = "2023-09-01T14:11:22Z"
not_after = "2032-09-01T14:11:22Z"
private_key_data_file = "./client_key.json"
}After terraform apply completes, retrieve client_key.json from the output path and store it in a secure location. Anyone with access to this file and the password can authenticate as the AAP. To avoid exposing the password in plain text, use Terraform sensitive input variables.
Step 2: Initialize Terraform
terraform initA successful initialization returns output similar to:
Initializing the backend...
Initializing provider plugins...
- Reusing previous version of hashicorp/alicloud from the dependency lock file
- Using previously-installed hashicorp/alicloud v1.231.0
Terraform has been successfully initialized!Step 3: Preview the execution plan
terraform planReview the list of resources Terraform will create before applying.
Step 4: Apply the configuration
terraform applyEnter yes when prompted and press Enter. A successful run returns output similar to:
alicloud_kms_network_rule.network_rule_example: Creating...
alicloud_kms_policy.policy_example: Creating...
alicloud_kms_network_rule.network_rule_example: Creation complete after 0s [id=sample_network_***]
alicloud_kms_policy.policy_example: Creation complete after 0s [id=sample_pol***]
alicloud_kms_application_access_point.application_access_point_example: Creating...
alicloud_kms_application_access_point.application_access_point_example: Creation complete after 0s [id=sample_***]
alicloud_kms_client_key.client_key: Creation complete after 0s [id=KAAP.5093ea57-0b84-4455-a8e9-7679bdc****]
...
Apply complete! Resources: 4 added, 0 changed, 0 destroyed.Verify the result
Run the terraform show command
Run the following command to inspect the created resources:
terraform show
Log on to the KMS console
Log in to the KMS console to confirm the AAP appears in the console.
Clean up resources
To delete all resources created by this configuration, run:
terraform destroyFor details on terraform destroy, see Common commands.