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.

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 create ConfigMaps and CustomResourceDefinition (CRD) objects to define mappings between RAM identities and role-based access control (RBAC) permissions. 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 has ack-ram-authenticator installed.

123..png

When 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 API operation of RAM to obtain the identity information of the caller based on the received token URL. After the GetCallerIdentity API operation returns the identity information of the caller, ack-ram-authenticator matches the RAM identity of the caller with the identity mappings defined in ConfigMaps or RAMIdentityMapping objects.
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, click the name of the cluster that you want to manage and choose Operations > Add-ons in the left-side navigation pane.
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.

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: acs:ram::xxxxx:assumed-role/aliyunreservedsso-admin/tester2
  username: tester
  groups:
    - system:users    
EOF
```
Note
- 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.
- For more information about how to view the ARN of a RAM role, see View the information about a RAM role.
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
NAME              STATUS   AGE
arms-prom         Active   4h48m
default           Active   4h50m
kube-node-lease   Active   4h50m
kube-public       Active   4h50m
kube-system       Active   4h50m