User Impersonation Mode for Kubernetes

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 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.

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).

Set Up User Impersonation Mode #

Use the following steps to set up User Impersonation mode.

1. Create your cluster if you do not have one already.

   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.

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:

   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:

   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).

   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.

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:

   {
     "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)