> For the complete documentation index, see [llms.txt](https://docs.strongdm.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.strongdm.com/admin/resources/clusters/kubernetes-user-impersonation.md). # Kubernetes (User Impersonation) {% hint style="warning" %} This feature is deprecated and should not be used in new deployments. Please contact StrongDM at the [StrongDM Help Center](https://help.strongdm.com/hc/en-us) for more details. {% endhint %} *Recent features (such as Groups) may not be supported for deprecated resource types.* ## Overview When using StrongDM to proxy authentication with your Kubernetes resources, a leased credential is typically used. No matter how many StrongDM users access the resource, they can use that leased credential. User-level auditing and monitoring occur on the StrongDM side, and the actions are executed via the leased account with the resource. In some cases, you may require that individual user details be recorded via native logging. [User Impersonation mode](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation) can assist with this task. User Impersonation mode makes the initial connection to the Kubernetes endpoint using the leased credentials, as usual. But that request also includes headers with account and role details. If the named role matches a Role-Based Access Control (RBAC) group, the calling user is granted access to resources defined in that group rather than the level of access defined by the leased credentials. {% hint style="info" %} For User Impersonation cluster types, if you intend to use RBAC, the role names in StrongDM need to match the group names in your Kubernetes. If necessary, StrongDM role names can be edited or Kubernetes groups can be remade with a new name. However, if some roles match and others do not, provisioning can still continue. {% endhint %} Utilizing User Impersonation mode results in your native Kubernetes logs identifying the particular user performing an action, rather than identifying all actions conducted via StrongDM connections as being performed by the single leased user account. The username employed is the user's email for their StrongDM user account. Their group(s) are whichever group(s) match their StrongDM role(s). {% hint style="warning" %} If you are using AKS, you must ensure that RBAC is enabled on your cluster. You can check the status of this setting from the cluster overview page. If RBAC is not enabled in your cluster’s configuration, AKS does not adhere to RBAC rules, so you need to recreate the cluster with RBAC enabled before using User Impersonation. {% endhint %} ## Set Up User Impersonation Mode {% hint style="info" %} If you are using kubectl 1.30 or higher, it will default to using websockets, which the StrongDM client did not support prior to version 45.35.0. This can be remedied by taking one of the following actions: * Update your client to version 45.35.0 or greater. * Set the environment variable `KUBECTL_REMOTE_COMMAND_WEBSOCKETS=false` to restore the previous behavior in your kubectl. {% endhint %} Use the following steps to set up User Impersonation mode. 1. Create your cluster if you do not have one already. {% hint style="warning" %} Using a version of Kubernetes below 1.20 (which at this point are also not supported by Kubernetes) in a User Impersonation situation will fail. A known bug affects earlier versions when using User Impersonation with Anonymous Requests enabled. Kubernetes in those cases is incorrectly expecting `system:authenticated` in the auth headers. {% endhint %} 2. Create your resource in StrongDM, choosing the User Impersonation mode version of a Kubernetes cluster. 3. Set your RBAC rules to allow User Impersonation. The cluster-admin role has that information built in, but custom roles do not. If you have a custom role, create or edit your cluster role to be like the following example. In this example YAML file, the ClusterRole rules allow users with that role to view the specified cluster resources and to impersonate and review their access: ```yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: annotations: rbac.authorization.kubernetes.io/autoupdate: "true" labels: name: view rules: # Ability to view only any of these cluster resources - apiGroups: - "" resources: - "*" verbs: - get - list - watch - apiGroups: - extensions resources: - "*" verbs: - get - list - watch - apiGroups: - apps resources: - "*" verbs: - get - list - watch - apiGroups: # Ability to impersonate and review your own access - "" resources: - users - groups verbs: - impersonate - apiGroups: - "authorization.k8s.io" resources: - selfsubjectaccessreviews verbs: - create ``` 4. For most cluster types, you need to create a cluster role binding to map the user's StrongDM role to a group under RBAC. In the following example YAML file, the ClusterRoleBinding allows any user in the "engineering" group/role to read secrets in any namespace: ```yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: sdm-operator subjects: - kind: Group name: engineering # Name of the StrongDM role apiGroup: rbac.authorization.k8s.io roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: view # Name of the cluster role you want that StrongDM role to have ``` You should use or create a role here that has the same rights as the leased credentials defined in the resource; the user in the given StrongDM role inherits only the rights in the RBAC group, not the rights defined in the leased credentials. This binding needs to be repeated for every desired StrongDM role. Note that you must be an administrator of the cluster with direct access to it (rather than through StrongDM) in order to apply the role binding (`kubectl apply -f filename.yaml`). Also, ensure that you have altered the group name (the StrongDM role) and the role name (the group name in Kubernetes). {% hint style="info" %} When matching StrongDM role names to Kubernetes groups, the StrongDM role names are transformed to be shown in all lowercase letters, spaces are changed to hyphens, and periods are ignored. This means that some similar StrongDM role names might collide and cause problems. For example: * **MyRole** and **myrole** are acceptable StrongDM role names, but they appear the same after transformation: **myrole**. * Both **My-Role** and **My role** become **my-role**. * Periods are ignored, so **My.Role** becomes **myrole**. In order to prevent issues, please keep this transformation in mind when creating the StrongDM roles you wish to use with Kubernetes. {% endhint %} 5. Configure your cluster to enable audit logs. (For example, in AKS, edit your cluster and go to **Configuration** > **Logs** and enable **Audit**.) 6. In the Admin UI, assign the new resource to the intended user(s). 7. As one of the users assigned to your new resource, in your desktop app, select the **Update kubectl configuration** option. 8. Run the commands you want to try as examples. 9. Access your logs and search for the term "impersonate" or your StrongDM username. For example, in AWS, go to **Cloudwatch** > **Log Groups**, search for your cluster name, and then search for your term. You should see audit records similar to the following: ```json { "kind": "Event", "apiVersion": "audit.k8s.io/v1", "level": "Metadata", "auditID": "8cadb874-1ec0-4670-9996-38dc0371fdca", "stage": "ResponseComplete", "requestURI": "/api?timeout=32s", "verb": "get", "user": { "username": "eks-header-validation_role", "uid": "heptio-authenticator-aws:000000000000:ARRRRRRRRRRRRRRRRRRR", "groups": [ "system:masters", "system:authenticated" ], "extra": { "accessKeyId": [ "ARRRRRRRRRRRRRRRRRRR" ], "arn": [ "arn:aws:sts::000000000000:assumed-role/eks-header-validation_role/1632846062627469349" ], "canonicalArn": [ "arn:aws:iam::000000000000:role/eks-header-validation_role" ], "sessionName": [ "1632846062627469349" ] } }, "impersonatedUser": { "username": "alice.glick@strongdm.com", "groups": [ "product", "system:authenticated" ] }, "sourceIPs": [ "10.0.0.1" ], "userAgent": "kubectl/v1.20.4 (darwin/amd64) kubernetes/e87da0b", "responseStatus": { "metadata": {}, "code": 200 }, "requestReceivedTimestamp": "2021-09-28T16:21:03.167286Z", "stageTimestamp": "2021-09-28T16:21:03.167566Z", "annotations": { "authorization.k8s.io/decision": "allow", "authorization.k8s.io/reason": "RBAC: allowed by ClusterRoleBinding \"system:discovery\" of ClusterRole \"system:discovery\" to Group \"system:authenticated\"" } } ``` ## Supported Kubernetes Variants * Kubernetes * Elastic Kubernetes Service (EKS) * Azure Kubernetes Service (AKS) * Google Kubernetes Engine (GKE) (only GKE Standard mode; GKE Auto-pilot mode is **not** supported) {% hint style="info" %} Want to see StrongDM's capabilities beyond User Impersonation mode and native logging with Kubernetes? Learn more about [how it works](https://www.strongdm.com/how-it-works) or [get a demo](https://www.strongdm.com/get-a-demo) to see it in action. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.strongdm.com/admin/resources/clusters/kubernetes-user-impersonation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.