Some cloud products create KMS secrets from sensitive credentials that you submit or that the products generate, such as database secrets, API keys, and AccessKey pairs. These KMS secrets, called default secrets, are securely stored and retrieved using KMS. KMS helps prevent secret leaks by providing secure storage, access control, security audits, and multiple connection types. This topic outlines default secrets.
What are default secrets
Default secrets are KMS secrets that cloud products create and manage for you.
Management (handled by the cloud product): The associated cloud product handles lifecycle operations for default secrets, such as creation, updates, and deletion.
Usage (controlled by you): As the resource owner, you can use Resource Access Management (RAM) to precisely control which identities, such as RAM users or RAM roles, can access and use these secrets under specific conditions.
The name of a default secret follows the format <ProductCode>!<SecretIdentifier>. For example, bailian!secret-123 is a secret created by Alibaba Cloud Model Studio.
Hosting modes
Default secrets are available in free and paid hosting modes. These modes differ in cost, security, and features. The supported mode varies by cloud product.
Comparison | Free default secrets | Paid default secrets |
Fee | Free. You do not need to purchase a KMS instance. | Paid. You must purchase a KMS instance. You are charged based on the instance type. |
Quota limit | Each cloud product has a limited quota. | The quota is determined by the instance type of the purchased KMS instance. On-demand scale-out is supported. |
Lifecycle management | You can delete or modify them only from the cloud product. In KMS, you can only read them. | You can delete or modify them only from the cloud product. In KMS, you can only read them. |
Encryption key | Uses a key managed by Alibaba Cloud. The key is not visible or controllable by users. | Uses a customer managed key (CMK). You have full control over the encryption key. Before you create a default secret in the cloud product, you must first create a key in KMS. |
Access policy | Only supports identity-based policies. | Supports the following two types of policies:
|
Security audit | You can query access records only in ActionTrail. | You can query access records in ActionTrail and in the Simple Log Service (SLS) logs of the KMS instance. |
Access gateway | Shared gateway | Dedicated gateway, shared gateway |
Integration flow
Step 1: Confirm cloud product support
Before you begin, confirm that the cloud product you are using supports default secrets. You trigger the creation of a default secret in the cloud product. The cloud product then assumes a RAM role to create the default secret in KMS.
Product | Supported secret type | Quota | References |
AI Gateway | Payment credentials | The quota of the KMS instance applies. | |
API Gateway | Payment credentials | The quota of the KMS instance applies. |
Step 2: Configure access permissions
To allow your application (through a RAM role) or developers (through a RAM user) to retrieve a secret value, you must grant the required RAM permissions.
You can configure an identity-based policy. If you use the paid mode, you can also configure a secret policy for more flexible authorization.
If the secret is in paid mode and encrypted with a customer managed key, the authorization policy must include the kms:Decrypt permission for the encryption key in addition to permissions for secret operations.
Identity-based policy
This policy is attached to a RAM user or RAM role to control which secrets they can access. For more information, see Grant permissions.
The following sample policy grants permissions to access all default secrets created by Model Studio (product code:
mcp).{ "Version": "1", "Statement": [{ "Effect": "Allow", "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue" ], "Resource": "acs:kms:${region}:${account}:secret/mcp!*" }] }Secret policy (paid mode only)
This policy is attached directly to the default secret resource and is often used for cross-account authorization.
The following sample policy allows a RAM user named
key_ramuser3that belongs to another Alibaba Cloud account (190325303126****) to retrieve the value of this secret.{ "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue" ], "Effect": "Allow", "Principal": { "RAM": [ "acs:ram::190325303126****:user/key_ramuser3" ] }, "Resource": [ "acs:kms:cn-hangzhou:123456789012****:secret/ai-gateway!secret-name" ] }], "Version": "1" }
Step 3: Call the secret
You can use the following methods to call secrets:
You can grant a cloud product permission to call the secret using a RAM role.
You can call the secret from the console or an application using the Alibaba Cloud SDK, secret client, or KMS Agent.
Supported API operations
Default secrets can be called by cloud products and users. Write operations, such as creating, updating, and deleting default secrets, are performed automatically by the associated cloud product. You cannot call APIs directly to perform these operations. The operations that you can perform are primarily for reading secrets and managing access policies. For more information, see the following table.
You can call OpenAPI operations by integrating the Alibaba Cloud SDK. You can also retrieve secrets by integrating the secret client or KMS Agent into your application. Free default secrets can be called only through a shared gateway. Paid default secrets can be called through either a shared gateway or a dedicated gateway.
API | Description | Cloud product call | User call | |
Secret management | Creates a secret and stores its initial version. | |||
Queries all secrets of the current Alibaba Cloud account in the region where the operation is called. | ||||
Obtains the metadata of a secret. | ||||
Updates the metadata of a secret. | ||||
Stores a new version of a secret value. | ||||
Updates the version stage of a secret. | ||||
Schedules a secret for deletion or immediately deletes a secret. | ||||
Recovers a secret that is scheduled for deletion. | ||||
Queries information about all versions of a secret. | ||||
Manually rotates a secret. | - | |||
Updates the rotation policy of a secret. | - | - | ||
Sets a secret policy. | ||||
Retrieve secret | Obtains a secret value. |
FAQ
How do I identify a default secret in the console or in code?
By credential name
The name of a default secret follows the format
<ProductCode>!<SecretIdentifier>. For example,bailian!secret-123is a default secret for Alibaba Cloud Model Studio, andaigw!secret-abcis a default secret for AI Gateway.My application failed to retrieve a default secret. How do I troubleshoot this issue?
You can troubleshoot this issue by checking the following items:
Check permissions: Confirm that the RAM role or RAM user that runs the application has been granted an access policy for the target secret.
Check the secret status: In the KMS console, check whether the secret is in the Normal state and not scheduled for deletion.
Check network connectivity: If you use a dedicated gateway, check whether the VPC where your application resides can connect to the KMS dedicated gateway.
Check encryption key permissions: If the secret is encrypted with a customer managed key (paid mode), confirm that the RAM identity also has the
kms:Decryptpermission for the key.
Is there a queries per second (QPS) limit for default secrets?
Yes, there is. For example, when you retrieve a secret value, the QPS limit is 450 for calls through a shared gateway. For calls through a dedicated gateway, the QPS limit is determined by the instance type that you purchase. For more information, see Performance metrics.