how to use ack-ram-authenticator to help the API server complete webhook authentication - Container Service for Kubernetes

ack-ram-authenticator is a component that can help authenticate requests sent to the API server of a Container Service for Kubernetes (ACK) managed cluster by using webhooks and Resource Access Management (RAM). In single sign-on (SSO) scenarios, ack-ram-authenticator can help the API server authenticate the requests sent to the API server by users that assume the same role. This topic introduces how ack-ram-authenticator helps the API server complete webhook authentication. This topic also describes how to configure webhook authentication.

Prerequisites

An ACK managed cluster is created and the version of the cluster is 1.24.6-aliyun.1 or later. For more information, see Create an ACK managed cluster.

Usage notes

Installing or uninstalling the ack-ram-authenticator component restarts the API server in the cluster and closes all persistent connections to the API server. We recommend that you install or uninstall the ack-ram-authenticator component during off-peak hours.
After you enable webhook authentication, you can continue to use the kubeconfig file returned by the DescribeClusterUserKubeconfig API operation to access the API server as normal.
The ack-ram-authenticator component is supported in ACK Serverless clusters.

How ack-ram-authenticator works

ack-ram-authenticator is an authentication component for ACK managed clusters. The component can help authenticate requests sent to the API server of an ACK managed cluster by using Kubernetes-native webhook token authentication and RAM. The component allows you to define mappings between RAM identities and role-based access control (RBAC) permissions by using custom resource definitions (CRDs). This helps you verify the RBAC permissions of different RAM identities in a more flexible manner.

When a user assumes an Alibaba Cloud single sign-on (SSO) role to access the API server of an ACK managed cluster, ack-ram-authenticator passes the name of the session that corresponds to the user identity to the API server. This helps the API server authenticate the requests sent to the API server by users that assume the same role.

The following figure shows how webhook authentication works in an ACK managed cluster that installs ack-ram-authenticator.

123..png

If you use a tool such as kubectl to authenticate to the API server of an ACK managed cluster, the kubectl client runs the exec command in the kubeconfig file and calls ack-ram-tool to generate a signed Security Token Service (STS) token URL.
After the kubectl client sends the authentication webhook to the API server, the API server routes the webhook to ack-ram-authenticator.
ack-ram-authenticator then calls the GetCallerIdentity operation of RAM to obtain the identity information about the caller based on the received token URL. After the GetCallerIdentity operation returns the identity information about the caller, ack-ram-authenticator matches the RAM identity of the caller with the identity mappings defined in the RAMIdentityMapping configurations.
The API server verifies the RBAC permissions of the RAM user or user group in the matching mapping and then returns the authentication result to the kubectl client.

Benefits of ack-ram-authenticator

Compared to the default x509 certificate authentication mode provided by ACK clusters, using ack-ram-authenticator to perform webhook authentication has the following advantages:

It is suitable for enterprises that use CloudSSO and provides a flexible and controllable method to implement Role-Based Access Control (RBAC) authorization.
In scenarios where users access the API server with SSO roles, the audit logs of the API server contain identity information provided by the enterprise identity provider (IDP). This enables the API server to authenticate requests sent by users assuming the same role.
When an enterprise employee resigns and you need to delete the RAM user or RAM role used by the employee, ack-ram-authenticator can automatically revoke the cluster RBAC permissions from the employee.

Step 1: Install the ack-ram-authenticator component

To enable webhook authentication, you need to install the ack-ram-authenticator component to interact with the API server. You can perform the following steps to install the ack-ram-authenticator component:

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side navigation pane, choose Operations > Add-ons.
On the Add-ons page, click the Security tab, find the ack-ram-authenticator component, click Install in the lower-right part of the card, and then click OK.

Step 2: Install the ack-ram-tool client

You can use the ack-ram-tool client to automatically generate a kubeconfig file in an on-premises environment. The kubeconfig file contains credentials that are used to access a cluster.

Download an ack-ram-tool client version based on the operating system that you use.
Run the following command to make the client program executable:
```
chmod +x ./ack-ram-tool
```
Run the following command to copy the ack-ram-tool file to the directory specified in the PATH parameter:
```
 mkdir -p $HOME/bin && cp ./ack-ram-tool $HOME/bin/ack-ram-tool && export PATH=$HOME/bin:$PATH
```
Run the following command to persist the PATH setting in $HOME/bin:
```
echo 'export PATH=$HOME/bin:$PATH' >> ~/.bash_profile
```
Run the following command to check whether the client version that you installed is returned. If yes, the ack-ram-tool client is successfully installed.
```
ack-ram-tool version
```

Step 3: Configure Alibaba Cloud credentials

RAM users and CloudSSO users can use the following methods to obtain the credentials that are used to access cloud resources.

Note

If credential-related environment variables exist, ack-ram-tool preferentially uses the credentials configured in those variables. You can ignore these variables by adding the --ignore-env-credentials option when you run the ack-ram-tool command. For more information about the credential-related environment variables supported by ack-ram-tool, see Credentials.

RAM user

The ack-ram-tool client uses local credentials to access RAM and complete authentication.

For more information about how to configure credentials that are used to access cloud resources, see Alibaba Cloud CLI.

CloudSSO users

CloudSSO users can use the acs-sso CLI provided by CloudSSO to access CloudSSO and obtain the credentials that are used to access cloud resources. For more information about acs-sso, see Use Alibaba Cloud CLI to access CloudSSO and Alibaba Cloud resources. Alibaba Cloud CLI supports the external mode. You can use this mode to dynamically obtain credentials through an external program. Run the following command to access CloudSSO from the on-premises environment and automate credential retrieval:

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 a kubeconfig file

Run the following command to generate a kubeconfig file: For more information, see get-kubeconfig.

ack-ram-tool credential-plugin get-kubeconfig --cluster-id $cluster_id --mode ram-authenticator-token

Modify the returned kubeconfig file in the on-premises environment or in a specified environment. For more information, see Kubernetes Documentation.

Step 5: Map RAM identities to RBAC permissions

After the ack-ram-authenticator component is installed, a custom resource definition (CRD) named RAMIdentityMapping is created in the cluster by default. The CRD is used to map RAM identities to Kubernetes RBAC permissions. The permission administrator of the cluster can perform the following steps to map a RAM user or RAM role to Kubernetes RBAC permissions.

Create a file named auth.yaml and add the following content to the file:

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

In the spec section of the RAMIdentityMapping CRD, you can map a RAM Alibaba Cloud Resource Name (ARN) to only one pair of username and groups. To map an ARN to multiple identities, you need to create the same number of RAMIdentityMapping CRDs.

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 name of the RAM user that you want to use.	`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 that you want to use. For more information about how to view the ARN of a RAM role, see View the information about a RAM role.	`acs:ram::123456789012****:role/testrole`

Run the following command to create a RAMIdentityMapping CRD:
```
kubectl apply -f auth.yaml
```

Create a custom RBAC role and grant the required cluster permissions to the role.

The following code block shows an example:

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
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: tester2
EOF

kubectl apply -f binding.yaml

Step 6: Use the kubeconfig file to send requests

Use the kubeconfig file generated in Step 4 to send requests to the API server. Then, check whether the requests are processed without permission issues.

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