Use ack-ram-authenticator for webhook authentication - Container Service for Kubernetes

The ack-ram-authenticator component allows ACK managed clusters to use Alibaba Cloud Resource Access Management (RAM) and a webhook to securely authenticate requests to the API Server. For role-based single sign-on (SSO), this component also helps you securely audit API Server requests from different users who assume the same role. This topic describes how to use the ack-ram-authenticator component for webhook authentication with the API Server of an ACK managed cluster.

Prerequisites

An ACK managed cluster is created. The cluster version must be 1.24.6-aliyun.1 or later. For more information, see Create an ACK managed cluster.

Notes

Installing or uninstalling the ack-ram-authenticator component restarts the API Server of the cluster's control plane. This causes persistent connections to the API Server to be disconnected. Install or uninstall the component during off-peak hours.
After you enable webhook authentication, the kubeconfig file returned by the DescribeClusterUserKubeconfig API operation can still be used to access the cluster's API Server.
ACK serverless clusters are also supported.

Authentication method

The ack-ram-authenticator component is an authentication plugin for ACK managed clusters. It uses the native Kubernetes Webhook Token Authentication method to authenticate requests to the cluster API Server using RAM. The component also provides mappings between RAM identities and RBAC permissions as Custom Resource Definitions (CRDs). This lets you configure RBAC authorization more flexibly.

When an Alibaba Cloud CloudSSO role is used to access an ACK managed cluster, the ack-ram-authenticator component can pass the session name of the requester's identity to the API Server. This enables more secure auditing of access requests to the cluster API Server from different users who assume the same role.

The webhook authentication flow for the cluster is as follows:

123..png

When you use a tool such as kubectl to send an authentication request to the API Server, the exec command plugin in the KubeConfig file runs the ack-ram-tool client. The client generates a signed Security Token Service (STS) request URL.
A webhook authentication request is sent to the API Server of the ACK managed cluster. The request is routed to the ack-ram-authenticator component based on the webhook authentication configuration.
The component uses the received token URL to authenticate the request against the Alibaba Cloud RAM GetCallerIdentity API. If authentication is successful, the ack-ram-authenticator component searches for a mapping between the RAM identity returned by the API and the user-configured identity in the specified RAMIdentityMapping custom resource (CR).
The API Server performs native RBAC authorization on the mapped user and group identities and returns the authorization result.

Advantages of this authentication method

Compared with the default X.509 certificate authentication method of ACK clusters, the ack-ram-authenticator webhook authentication method has the following advantages.

It adapts to enterprise cloud SSO scenarios and provides flexible and controllable data plane RBAC authorization.
In role-based SSO scenarios, the API Server audit log contains identity information from the enterprise Identity Provider (IDP). This enables effective auditing of the behavior of different IDP users who assume the same role.
When an employee leaves the company and their RAM user or RAM role is deleted, their RBAC permissions in the cluster are automatically revoked.

Step 1: Install the ack-ram-authenticator component

To enable RAM webhook authentication, install the ack-ram-authenticator server-side authentication plugin. This plugin interacts with the cluster's API Server for authentication. Perform the following steps to install the ack-ram-authenticator component.

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, find the one you want to manage and click its name. In the left navigation pane, click Add-ons.
On the Component Management page, click the Security tab and find the ack-ram-authenticator component. Click Install in the bottom-right corner of the card. In the Parameter Settings dialog box that appears, select the EnableNonBootstrapMapping configuration item, and then click Confirm.

Step 2: Install the ack-ram-tool client

The ack-ram-tool client automatically generates a kubeconfig access credential for a specific cluster on your local machine.

Download the ack-ram-tool client for the architecture of your environment.
Run the following command to grant execute permissions to the client program.
```
chmod +x ./ack-ram-tool
```
Run the following command to copy the ack-ram-tool file to a directory specified in the system's PATH.
```
mkdir -p $HOME/bin && cp ./ack-ram-tool $HOME/bin/ack-ram-tool && export PATH=$HOME/bin:$PATH
```
(Optional) Run the following command to make the PATH configuration for $HOME/bin persistent.
```
echo 'export PATH=$HOME/bin:$PATH' >> ~/.bash_profile
```
Run the following command to check the client version. If the version number is returned, the ack-ram-tool client is installed.
```
ack-ram-tool version
```

Step 3: Configure Alibaba Cloud credentials

Alibaba Cloud RAM users and SSO users can configure and obtain access credentials for cloud resources using the following methods.

Note

If your current environment has environment variables related to access credentials, ack-ram-tool prioritizes the credentials configured in those variables. You can add the --ignore-env-credentials parameter when you run the ack-ram-tool command to ignore them. For more information about the credential-related environment variables that ack-ram-tool supports, see Credentials.

RAM users

The ack-ram-tool client relies on locally configured Alibaba Cloud key credentials to access RAM for identity authentication.

For more information about how to configure access credentials, see Alibaba Cloud CLI.

SSO users

For Alibaba CloudSSO users, you can use the acs-sso command-line interface (CLI) tool provided by the CloudSSO service to log on and obtain access credentials for cloud resources. For more information about acs-sso, see Use the CLI to log on to CloudSSO and access Alibaba Cloud resources. The Alibaba Cloud CLI tool supports an external mode, which lets you dynamically obtain resource credentials by running an external command-line tool. Run the following command to log on to CloudSSO and automatically configure credentials on your local machine.

aliyun configure --mode External --profile sso

Configuring profile 'sso' in 'External' authenticate mode...
Process Command [acs-sso login --profile sso]:
Default Region Id [cn-shanghai]:
Default Output Format [json]: json (Only support json)
Default Language [zh|en] en:
Saving profile[sso] ...Done.


Configure Done!!!
..............888888888888888888888 ........=8888888888888888888D=..............
...........88888888888888888888888 ..........D8888888888888888888888I...........
.........,8888888888888ZI: ...........................=Z88D8888888888D..........
.........+88888888 ..........................................88888888D..........
.........+88888888 .......Welcome to use Alibaba Cloud.......O8888888D..........
.........+88888888 ............. ************* ..............O8888888D..........
.........+88888888 .... Command Line Interface(Reloaded) ....O8888888D..........
.........+88888888...........................................88888888D..........
..........D888888888888DO+. ..........................?ND888888888888D..........
...........O8888888888888888888888...........D8888888888888888888888=...........
............ .:D8888888888888888888.........78888888888888888888O ..............

Step 4: Generate the kubeconfig file

Run the following command to generate the kubeconfig file. For more information about the command, see get-kubeconfig.
```
ack-ram-tool credential-plugin get-kubeconfig --cluster-id $cluster_id --mode ram-authenticator-token
```
Configure the kubeconfig file that is returned by the command in your local environment or a specified environment. For more information, see the official Kubernetes documentation.

Step 5: Configure the mapping between RAM identities and RBAC permissions

Important

Make sure to Check the configuration item EnableNonBootstrapMapping when you install the component. Otherwise, the configured mapping will not take effect.

After the ack-ram-authenticator component is installed, a CRD named RAMIdentityMapping is installed in the cluster by default. This CRD is used to configure the mapping between RAM identities and the Kubernetes user model. A cluster administrator can use the following method to configure the user identity and bind a specific RAM user or RAM role to Kubernetes RBAC permissions.

You can create a configuration template file named auth.yaml with the following YAML content.

cat >auth.yaml <<EOF
---
apiVersion: ramauthenticator.k8s.alibabacloud/v1alpha1
kind: RAMIdentityMapping
metadata:
  name: tester
spec:
  arn: '<ARN>'
  username: tester
  groups:
    - system:users    
EOF

The spec field in a RAMIdentityMapping instance supports mapping only one RAM ARN to a username and groups. To map different RAM identities, you must create multiple RAMIdentityMapping instances.

Replace <ARN> with the ARN of the specified RAM user or RAM role. The following table describes the ARN format for different account types.

Account type	ARN format	Example
Alibaba Cloud account	`acs:ram::<root_uid>:root` where `<root_uid>` is the ID of the Alibaba Cloud account.	`acs:ram::123456789012****:root`
RAM user	`acs:ram::<root_uid>:user/<user_name>` where `<root_uid>` is the ID of the Alibaba Cloud account and `<user_name>` is the username of the RAM user.	`acs:ram::123456789012****:user/testuser`
RAM role	`acs:ram::<root_uid>:role/<role_name>` where `<root_uid>` is the ID of the Alibaba Cloud account and `<role_name>` is the name of the RAM role. For more information about how to view the ARN of a RAM role, see View a RAM role.	`acs:ram::123456789012****:role/testrole`

Run the following command to create the RAMIdentityMapping instance.
```
kubectl apply -f auth.yaml
```

Configure RBAC permissions for the destination cluster. Create custom RBAC roles and bindings as needed.

The following is an example of how to create an RBAC binding.

cat >binding.yaml <<EOF
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: tester-clusterrolebinding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cs:ops
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: tester
EOF

kubectl apply -f binding.yaml

Step 6: Use the kubeconfig file to send a request

Use the kubeconfig file generated in Step 4 to send a request to the APIServer. Verify that you can successfully access the API Server within the scope of your permissions.

kubectl get ns

Expected output:

NAME              STATUS   AGE
arms-prom         Active   4h48m
default           Active   4h50m
kube-node-lease   Active   4h50m
kube-public       Active   4h50m
kube-system       Active   4h50m

References

ack-ram-authenticator