ack-ram-authenticator is an authentication plugin for ACK managed clusters. It uses native Kubernetes Webhook Token Authentication to authenticate API server requests using Alibaba Cloud RAM, and provides mappings between RAM identities and Role-Based Access Control (RBAC) permissions as Custom Resource Definitions (CRDs).
How it works
When a CloudSSO role is used to access an ACK managed cluster, ack-ram-authenticator passes the session name of the requester's identity to the API server, enabling you to audit requests from different users who assume the same role.
The webhook authentication flow is as follows:
A tool such as kubectl sends an authentication request to the API server. The
execplugin in the kubeconfig file runs the ack-ram-tool client, which generates a signed Security Token Service (STS) request URL.ack-ram-tool sends a webhook authentication request to the API server.
The API server routes the request to ack-ram-authenticator based on the webhook authentication configuration.
ack-ram-authenticator uses the token URL to authenticate the request against the RAM
GetCallerIdentityAPI. If authentication succeeds, the component searches theRAMIdentityMappingcustom resource (CR) for a mapping between the returned RAM identity and a user-configured identity.The API server performs native RBAC authorization on the mapped user and group identities and returns the authorization result.
Component configuration
ack-ram-authenticator supports the following configuration parameter.
| Parameter | Type | Description |
|---|---|---|
EnableNonBootstrapMapping | boolean | Specifies whether to enable the identity mappings configured in Step 5: Configure mappings between RAM identities and RBAC permissions. Supported in v0.4.0.0-g33f30dac-aliyun and later.<br><br>- true: Enables the identity mappings configured in the cluster.<br>- false: Disables the configured identity mappings. Only the mappings required for node initialization are active. |
Change history
Installing or uninstalling ack-ram-authenticator restarts the cluster's control plane API server, which affects persistent connections to the API server. Install or uninstall the component during off-peak hours.
November 2025
| Version | Change | Date |
|---|---|---|
| 0.5.1 | Upgraded Go to 1.24.10 to improve component stability. | November 26, 2025 |
September 2025
| Version | Change | Date |
|---|---|---|
| 0.5.0 | Changed the version naming convention. Upgraded Go to 1.24.6 to improve component stability. | September 09, 2025 |
April 2025
| Version | Change | Date |
|---|---|---|
| v0.4.1.0-g8023a0b5-aliyun | Added "identitySource": ["ack-ram-authenticator"] to the extra field in the user information returned by the component, so you can quickly identify whether a user was authenticated by ack-ram-authenticator. Upgraded Go to 1.24.2 to improve component stability. | April 29, 2025 |
March 2025
| Version | Change | Date |
|---|---|---|
| v0.4.0.0-g33f30dac-aliyun | Added the EnableNonBootstrapMapping parameter. For details, see Component configuration. | March 31, 2025 |
September 2024
| Version | Change | Date |
|---|---|---|
| v0.3.0.0-gea598ff0-aliyun | Upgraded Go to 1.22.7 to improve component stability. | September 09, 2024 |
April 2024
| Version | Change | Date |
|---|---|---|
| v0.2.1.3-g694325a9-aliyun | Transmits component version information when calling the GetCallerIdentity API to help with troubleshooting. | April 12, 2024 |
| v0.2.0.3-gcea89d25-aliyun | Added support for the ARM architecture. This version was released as a phased rollout. | April 10, 2024 |
November 2023
| Version | Change | Date |
|---|---|---|
| v0.2.0.0-g9cf9d682-aliyun | Added support for ACK serverless clusters. Added support for the new token format. | November 15, 2023 |
May 2023
| Version | Change | Date |
|---|---|---|
| v0.1.0.5-g6e50a122-aliyun | Initial release. | May 18, 2023 |