What is cattle-impersonation-system?​

It is part of the Rancher Authentication Proxy​:

• Cattle-impersonation-system is a critical part of how Rancher has implemented authentication.​

• A subject must explicitly have the “impersonate” privilege to be able to perform impersonation of other users. ​

• One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows users to use one set of credentials to authenticate with any of your Kubernetes clusters.  ​

• This centralized user authentication is accomplished using the Rancher authentication proxy, installed along with the rest of Rancher. This proxy authenticates your users and forwards their requests to your Kubernetes clusters using a service account.

Why do we need cattle-impersonation-system​?

Doesn't Kubernetes come with user authentication?

The short answer is yes, but Rancher is a multi-cluster Kubernetes management tool to deploy and run clusters anywhere and on any provider from one central point.​ Rancher is sitting "in front" of these multiple Kubernetes clusters. Because Kubernetes has a lot of support for authentication, each of these clusters can come with its own authentication strategy.

By default, Kubernetes clusters are accessed with a kubeconfig file, and the kubeconfig file contains full access to the cluster.​ With Rancher, this file is not required for cluster API communication because it uses the authentication proxy mechanism. The Rancher Manager server connects to the Kubernetes API server on a downstream user cluster by using a service account to communicate with the Kubernetes clusters, which provides an identity for processes that run in pods.​

What about users in Kubernetes?​

Kubernetes does not have full support for the user and group entities​

• It does have service accounts as users​

• But for normal users, Kubernetes documents that they should be managed externally by external identity providers.​

• Thus, there is no API support for a user object and its group membership (link)​

• If you want to manage multiple Kubernetes clusters and users across these clusters, you need to manage them externally.
   

How does Rancher do user authentication in this case?​

Rancher has designed and developed its authentication framework and extended Kubernetes to support the user and group object:​

To achieve this, it uses the user impersonation of Kubernetes.​ User Impersonation:​

• The ability for one user (or service account) to act as another​

• The user or service account should have "impersonate" permissions granted​

• An important key to Rancher's authentication system: on every Kubernetes API call, the authentication proxy authenticates the caller. It sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.​

​Rancher authentication proxy​

In the central authentication model, Rancher is sitting in "front" of all Kubernetes clusters, acts as a central authentication proxy, and thus facilitates the authentication for multiple clusters.​

A Rancher admin will configure and enable authentication against one of the integrations available for Rancher(e.g. Active Directory, OpenLdap, etc.) once, centrally on the Rancher server and manage it for all clusters. ​

Users authenticate with Rancher, and Rancher redirects the user request to the specific Kubernetes cluster using standard bearer tokens and user impersonation to act as that user.​

Resources for cattle-impersonation-system​

Four resources are created to handle impersonation:​

1. namespace: cattle-impersonation-system​

2. service account: cattle-impersonation-system/cattle-impersonation-<user ID>​
   Behind the scenes, Kubernetes also creates an account token that Rancher uses for authentication: cattle-impersonation-system/cattle-impersonation-<user ID>-token-<hash>​

3. cluster role: cattle-impersonation-<user ID>​

4. cluster role binding: cattle-impersonation-<user ID>

Internal implementation

Creating the impersonation resources works in two parts.  ​

Part 1​

• When a user creates a cluster or is added as a cluster owner/member/other (or added to a project on that cluster), a ClusterRoleTemplateBinding or a ProjectRoleTemplateBinding is created for that user on the cluster.​
• When the ClusterRoleTemplateBinding or a ProjectRoleTemplateBinding exists, Rancher creates the namespace (if it does not already exist), the service account, the cluster role binding, and the cluster role with rules based on the information it has at that time. The rules will include the ability to impersonate the user's ID and the groups that Rancher knows about.​

Part 2​

• When a user makes a request on the downstream cluster, using either the cluster explorer, kubectl with a downloaded kubeconfig, or curl with the /k8s/clusters proxy API, Rancher intercepts the request and checks to make sure the resources are up to date, that they exist, and that the rules are up to date for the user.​

• If the user is logging in from an external auth provider, Rancher may not know during part 1 what extra attributes the user has, as these are provided in the token in the request. At this point, Rancher will update the cluster role to include these extra attributes included in the request, such as the principal ID and username.​

• All relevant resources (namespace, service account, secret, clusterrole and clusterrolebinding) on the downstream cluster are watched and cached on the Rancher server, so checking the resources should have minimal performance overhead.
   

Request Diagram

Example:​



In this diagram, a user named Bob wants to see all pods running on a downstream user cluster called User Cluster. ​

1. From within Rancher, he can run a kubectl command to see the pods. Bob is authenticated through Rancher’s authentication proxy.​

2. The authentication proxy forwards all Kubernetes API calls to downstream clusters. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.​

3. Rancher communicates with Kubernetes clusters using a service account , which provides an identity for processes that run in a pod.​

4. By default, Rancher generates a kubeconfig file that contains credentials for proxying through the Rancher server to connect to the Kubernetes API server on a downstream user cluster. The kubeconfig file (kube_config_rancher-cluster.yml) contains full access to the cluster.

Q&A

When is the ClusterRole supposed to change? ​

• It often changes on the first login to add userextras/principalid and userextras/username. A future enhancement to the way user extra attributes are handled in Rancher will make this less necessary in the future.​

• It will change if the user adds an auth provider or changes auth providers. (NOTE: Rancher does not support changing auth providers at the moment).​

• It will change if the user's groups in the auth provider change.​

• It may change depending on how the user makes the request - UI, kubectl, or curl - sometimes the token includes different user extra attributes.

When will Cleanup happen?​

• The service account, clusterrole and clusterrolebinding are cleaned up when the ClusterRoleTemplateBinding or ProjectRoleTemplateBinding are deleted (when the user is removed from the project or cluster).