Active Directory Authentication for Kubernetes Kubectl CLI

Posted on 257 views

Kubernetes supports various authentication strategies for users. For Cluster Administrators to do better User and Password Management, Integration of Kubernetes to Active Directory proves to be useful. This is a better approach as compared to using Service accounts tokens to authenticate users.

Most developers and cluster administrators prefer using a command line interface in their operations. Therefore, this tutorial will look at how we can authenticate users using Active Directory on Kubernetes CLI. We will use gangway to achieve this.

Gangway is an application that can be used to enable authentication flows using OpenID Connect. Kubernetes support OIDC Tokens as a way to identify users who access the cluster. The authenticator uses ID tokens rather than access token to identify these users.

When using OIDC to authenticate with Kubernetes, the client (e.g. kubectl) sends the ID token alongside all requests to the API server. The Kubernetes API server verifies the token to ensure it is valid. Once verified, the API server extracts the username and group membership information from the token, and continues processing the request.

Gangway is configured as a client of an upstream Identity Service ( In our case is Active Directory). To obtain the ID token, the user accesses Gangway, initiates the OIDC flow by clicking the “Log In” button, and completes the flow by authenticating with the upstream Identity Service. Once the authentication flow is complete, the user is redirected to a Gangway page that provides instructions on how to configure kubectl to use the ID token.

The diagram below show the authentication sequence a user must go during the authentication process.



  1. You will need an Active Directory or LDAP server already configured.
  2. A running Kubernetes Cluster with role based access enable. You should have Administrative access
  3. An Ingress Controller installed in the cluster.
  4. A Certificate Manager if not using Custom Certificates. I will be using custom certificates for my deployment
  5. You will also need a domain name that supports wildcard DNS entry. I will use the wildcard DNS “*” to route external traffic to my Kubernetes cluster.

Assuming all prerequisites are in place, let’s look at how to deploy Gangway in our cluster. We will require to deploy Dex and Gangway. Dex will serve as the identity provider that will validate our credentials with the Active Directory (ldap) identity store. Dex uses OpenID Connect to perform this validation. Gangway will enable the end users to self-configure their kubectl configuration using the OpenID Connect Token provided by Dex after successful authentication.

STEP 1. Deploy DEX on Kubernetes

To do this, Follow Step One of guide below on deployment of Dex in kubernetes cluster.

Authenticate Kubernetes Dashboard Users With Active Directory

STEP 2: Configure the Kubernetes API to access Dex as OpenID connect provider

Dex requires that the Kubernetes API server is configured for OIDC. There are several flags that need to be passed to the API server.

Edit the Kubernetes api-server manifest file in each master node as follows:

$ sudo vim /etc/kubernetes/manifests/kube-apiserver.yaml
    - /hyperkube
    - apiserver
    - --advertise-address= 
## ADD these lines

    - --oidc-issuer-url=
    - --oidc-ca-file=/etc/ssl/kubernetes/    
    - --oidc-username-claim=email
    - --oidc-groups-claim=groups

Once saved, The api-server service will restart to pick the changes.

STEP 3: Deploy Gangway

Once Dex is deployed and running well, we are read to deploy Gangway. We will deploy Gangway in the same namespace as dex.

A. Deploy Configmap

We will first deploy a configmap that holds our gangway configurations. You need to modify the cluster name, apiserverURL, authorizeURL, tokenURL and redirectURL accordingly.

$ vim gangway_configmap.yaml
apiVersion: v1
kind: ConfigMap
  name: gangway
  namespace: auth-system
  gangway.yaml: |
    clusterName: "Kubernetes"
    apiServerURL: ""
    authorizeURL: ""  
    tokenURL: ""
    clientID: "oidc-auth-client"
    # API client secret as indicated by the identity provider: This should match the Dex key
    clientSecret: "secret"
    # Where to redirect back to. This should be a URL where gangway is reachable.
    # Typically this also needs to be registered as part of the oauth application
    # with the oAuth provider.
    redirectURL: ""
    # Used to specify the scope of the requested Oauth authorization.
    scopes: ["openid", "profile", "email", "offline_access"]
    usernameClaim: "email"
    emailClaim: "email"

Apply the configmap

$ kubectl apply -f gangway_configmap.yaml

B. Deploy Gangway

$ vim gangway.yaml
apiVersion: apps/v1
kind: Deployment
    app: gangway
  name: gangway
  namespace: auth-system
  replicas: 1
      app: gangway
        app: gangway
      - command:
        - gangway
        - -config
        - /gangway/gangway.yaml
              key: sesssionkey
              name: gangway-key
        image: gangway:v2.0.0
        imagePullPolicy: Always
        name: gangway
        - containerPort: 8080
          name: http
          protocol: TCP
            cpu: 100m
            memory: 100Mi
            cpu: 100m
            memory: 100Mi
        - mountPath: /etc/ssl/certs
          name: certs
        - mountPath: /gangway/
          name: gangway
      dnsPolicy: ClusterFirst
      restartPolicy: Always0
      - configMap:
          defaultMode: 420
          name: gangway
        name: gangway
      - name: certs
          defaultMode: 420
          secretName: secret

Apply the above configuration to deploy gangway.

$ kubectl apply -f gangway.yaml

Confirm that pods have been deployed and are running:

$ kubectl get pods -n auth-system 
NAME                            READY   STATUS    RESTARTS   AGE
dex-6cdc6dbbf9-fdlv2            1/1     Running   0          13m

gangway-5c95f5db79-6jjdr        1/1     Running   0          3m

Lastly, Deploy the gangway service :

$ vim gangway-svc.yaml
apiVersion: v1
kind: Service
    app: gangway
  name: gangway-svc
  namespace: auth-system
  - name: http
    port: 80
    protocol: TCP
    targetPort: http
    app: gangway

  type: ClusterIP

Apply the configuration:

$ kubectl apply -f gangway-svc.yaml

C. Configure an Ingress Rule

We will then create an ingress rule to allow communication to our service.

Since I use custom certificates, We first have to create a TLS certificate for our ingress. Make sure the certificate data for the cluster is at the location specified or change this path to point to it.

$ kubectl create secret tls gangway --key /data/Certs/ --cert /data/Certs/ -n auth-system

Create an gangway-ingress.yaml file. Modify the certificate manager issuer and the host parameters accordingly.

$ vim gangway-ingress.yaml
apiVersion: extensions/v1beta1
kind: Ingress
  annotations: "true"
#Add the line below if you have a certificate manager deployed in your kubernetes cluster "letsencrypt" #your cert-manager issuer here 
  name: gangway
  namespace: auth-system
  - host:
      - backend:
          serviceName: gangway-svc
          servicePort: http
  - hosts:
    secretName: gangway

Apply the above configuration.

$ kubectl apply -f gangway-ingress.yaml

Once all components are up and running, you should be able to obtain credentials for your cluster using a browser to access gangway.

Lets try to login with a user in our AD group that should have permissions to the cluster. Navigate to your gangway URL which in my case is at

The login page should look like this:


Click on “SIGN IN” to bring up the login page. Enter your username and AD passwordgamgway_login_pages

Once logged in, we are redirected back to a gangway page with instructions on configuring kubectl for the command line. These instructions involve installation of the kubectl and the second part has commands that can be executed to configure your kubeconfig file. You should be able to execute Kubectl commands once done.


Run the commands from the screen to install kubectl and configure kubectl for interacting with Kubernetes as an AD user.

You should now be able to interact with your cluster with ease.

Gravatar Image
A systems engineer with excellent skills in systems administration, cloud computing, systems deployment, virtualization, containers, and a certified ethical hacker.