{"id":14637853,"url":"https://github.com/HopopOps/k8s-ldap-auth","last_synced_at":"2025-09-07T06:31:03.488Z","repository":{"id":37950323,"uuid":"344566248","full_name":"HopopOps/k8s-ldap-auth","owner":"HopopOps","description":"Kubernetes webhook token authentication plugin implementation using ldap.","archived":false,"fork":false,"pushed_at":"2025-08-19T09:09:22.000Z","size":357,"stargazers_count":55,"open_issues_count":4,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-08-24T08:10:41.584Z","etag":null,"topics":["authentication","k8s","kubernetes","kubernetes-webhook","ldap"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HopopOps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["vbouchaud"],"custom":["https://paypal.me/vbouchaud"]}},"created_at":"2021-03-04T18:09:40.000Z","updated_at":"2025-08-19T07:29:35.000Z","dependencies_parsed_at":"2024-01-24T11:31:48.571Z","dependency_job_id":"cf0c500e-292d-4510-b758-1d8e8379b430","html_url":"https://github.com/HopopOps/k8s-ldap-auth","commit_stats":{"total_commits":210,"total_committers":4,"mean_commits":52.5,"dds":0.3857142857142857,"last_synced_commit":"834bd4aa3a4ff5d53df92c68075e11b930c81a0f"},"previous_names":["hopopops/k8s-ldap-auth","vbouchaud/k8s-ldap-auth"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/HopopOps/k8s-ldap-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HopopOps%2Fk8s-ldap-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HopopOps%2Fk8s-ldap-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HopopOps%2Fk8s-ldap-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HopopOps%2Fk8s-ldap-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HopopOps","download_url":"https://codeload.github.com/HopopOps/k8s-ldap-auth/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HopopOps%2Fk8s-ldap-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274005341,"owners_count":25205934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","k8s","kubernetes","kubernetes-webhook","ldap"],"created_at":"2024-09-10T02:01:18.536Z","updated_at":"2025-09-07T06:31:03.127Z","avatar_url":"https://github.com/HopopOps.png","language":"Go","funding_links":["https://github.com/sponsors/vbouchaud","https://paypal.me/vbouchaud"],"categories":["Go"],"sub_categories":[],"readme":"# k8s-ldap-auth\n\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/hopopops/k8s-ldap-auth?style=for-the-badge)](https://github.com/hopopops/k8s-ldap-auth/releases/latest)\n[![License](https://img.shields.io/github/license/hopopops/k8s-ldap-auth?style=for-the-badge)](https://opensource.org/licenses/MPL-2.0)\n[![Go Report Card](https://goreportcard.com/badge/github.com/hopopops/k8s-ldap-auth?style=for-the-badge)](https://goreportcard.com/report/github.com/hopopops/k8s-ldap-auth)\n[![Artifact Hub](https://img.shields.io/endpoint?style=for-the-badge\u0026url=https://artifacthub.io/badge/repository/hopopops)](https://artifacthub.io/packages/search?repo=hopopops)\n\nA webhook token authentication plugin implementation backed by LDAP.\n\n- [What](#what)\n- [Usage](#usage)\n  * [Server](#server)\n    + [New cluster](#new-cluster)\n    + [Existing cluster](#existing-cluster)\n  * [Client](#client)\n  * [RBAC](#rbac)\n    + [Example](#example)\n- [Build](#build)\n- [Distribution](#distribution)\n  * [Docker](#docker)\n  * [Binary](#binary)\n  * [Linux](#linux)\n    + [Archlinux](#archlinux)\n  * [Darwin](#darwin)\n    + [With `brew`](#with--brew-)\n  * [Kubernetes](#kubernetes)\n    + [Helm Chart](#helm-chart)\n- [Inspiration](#inspiration)\n\n## What\n\nk8s-ldap-auth is released as a binary containing both client and server.\n\nThe server part provides two routes:\n - `/auth` for the actual authentication from the CLI tool\n - `/token` for the token validation from the kube-apiserver.\n\nThe user created from the TokenReview will contain both uid and groups from the LDAP user so you can use both for role binding.\n\nThe same k8s-ldap-auth server can be used to authenticate with multiple kubernetes cluster since the ExecCredential it provides contains a signed token that will eventually be used by a kube-apiserver in a TokenReview that will be sent back.\n\nI actually use this setup on quite a few clusters with a growing userbase.\n\nAccess rights to clusters and resources will not be implemented in this authentication hook, kubernetes RBAC will do that for you.\n\n`KUBERNETES_EXEC_INFO` is currently disregarded but might be used in future versions.\n\n## Usage\n\nYou can see the commands and their options with:\n```\nk8s-ldap-auth --help\n# or\nk8s-ldap-auth [command] --help\n```\n\nPretty much all options can be set using environment variables and a few also read their values from files.\n\n### Server\n\nCreate the password file for the bind-dn:\n```\necho -n \"bind_P@ssw0rd\" \u003e /etc/k8s-ldap-auth/ldap/password\n```\n\nThe server can then be started with:\n```\nk8s-ldap-auth serve \\\n  --ldap-host=\"ldaps://ldap.company.local\" \\\n  --bind-dn=\"uid=k8s-ldap-auth,ou=services,ou=company,ou=local\" \\\n  --search-base=\"ou=people,ou=company,ou=local\"\n```\n\nNote that if the server do not know of any key pair it will create one at launch but will not persist it.\nIf you want your jwt tokens to be valid across server instances, after restarts or behind a load-balancer, you should provide a key pair.\n\nKey pair can be created with openssl:\n```\nopenssl genrsa -out key.pem 4096\nopenssl rsa -in key.pem -outform PEM -pubout -out public.pem\n```\n\nThen, the server can be started with:\n```sh\nk8s-ldap-auth serve \\\n  --ldap-host=\"ldaps://ldap.company.local\" \\\n  --bind-dn=\"uid=k8s-ldap-auth,ou=services,ou=company,ou=local\" \\\n  --search-base=\"ou=people,ou=company,ou=local\" \\\n  --private-key-file=\"path/to/key.pem\"\n  --public-key-file=\"path/to/public.pem\"\n```\n\nNow for the cluster configuration.\n\nIn the following example, I use the api version `client.authentication.k8s.io/v1beta1`. Feel free to put another better suited for your need.\n\nThe following authentication token webhook config file will have to exist on every control-plane. In the following configuration it's located at `/etc/kubernetes/webhook-auth-config.yml`:\n```yml\n---\napiVersion: v1\nkind: Config\n\nclusters:\n  - name: authentication-server\n    cluster:\n      server: https://\u003cserver address\u003e/token\n\nusers:\n  - name: kube-apiserver\n\ncontexts:\n  - context:\n      cluster: authentication-server\n      user: kube-apiserver\n    name: kube-apiserver@authentication-server\n\ncurrent-context: kube-apiserver@authentication-server\n```\n\n#### New cluster\n\nIf you're creating a new cluster with kubeadm, you can add the following to your init configuration file:\n```yml\n---\napiVersion: kubeadm.k8s.io/v1beta2\nkind: ClusterConfiguration\napiServer:\n  extraArgs:\n    authentication-token-webhook-config-file: \"/etc/ldap-auth-webhook/config.yml\"\n    authentication-token-webhook-version: client.authentication.k8s.io/v1beta1\n  extraVolumes:\n  - name: \"webhook-config\"\n    hostPath: \"/etc/kubernetes/webhook-auth-config.yml\"\n    mountPath: \"/etc/ldap-auth-webhook/config.yml\"\n    readOnly: true\n    pathType: File\n```\n\n#### Existing cluster\n\nIf the cluster was created with kubeadm, edit the kubeadm configuration stored in the namespace `kube-system` to add the configuration from above: `kubectl --namespace kube-system edit configmaps kubeadm-config`\nEditing this configuration does not actually update your api-server. It will however be used if you need to add a new control-plane with `kubeadm join`.\n\nOn every control plane, edit the manifest found at `/etc/kubernetes/manifests/kube-apiserver.yaml`:\n```yml\nspec:\n  containers:\n  - name: kube-apiserver\n    command:\n    - kube-apiserver\n    # ...\n    - --authentication-token-webhook-config-file=/etc/ldap-auth-webhook/config.yml\n    - --authentication-token-webhook-version=v1beta1\n\n    # ...\n\n    volumeMounts:\n    - mountPath: /etc/ldap-auth-webhook/config.yml\n      name: webhook-config\n      readOnly: true\n\n  # ...\n\n  volumes:\n  - hostPath:\n      path: /etc/kubernetes/webhook-auth-config.yml\n      type: File\n    name: webhook-config\n```\n\n### Client\n\nEven though it's not specified anywhere, the `--password` option and the equivalent `$PASSWORD` environment variable as well as the configfile containing a password were added for convenience’s sake, e.g. when running in an automated fashion, etc. If not provided, it will be asked at runtime and, if available, saved into the client OS credential manager. The same can be said for the `--user` options and `$USER` environment variables.\n\nAuthentication can be achieved with the following command you can execute to test your installation:\n```\nk8s-ldap-auth auth --endpoint=\"https://\u003cserver address\u003e/auth\"\n```\n\nYou can now configure `kubectl` to use `k8s-ldap-auth` to authenticate to clusters by editing your kube config file and adding the following user:\n```yml\nusers:\n  - name: my-user\n    user:\n      exec:\n        # In the following, we assume a binary called `k8s-ldap-auth` is\n        # available in the path. You can instead put the full path to the binary.\n        # Windows paths do work with kubectl so the following would also work:\n        # `C:\\users\\foo\\Documents\\k8s-ldap-auth.exe`.\n        command: k8s-ldap-auth\n\n        # This field is used by kubectl to fill a template TokenReview in\n        # `$KUBERNETES_EXEC_INFO` environment variable. Not currently used, it\n        # might be in the future.\n        apiVersion: client.authentication.k8s.io/v1beta1\n\n        env:\n          # This environment variable is used within `k8s-ldap-auth` to create\n          # an ExecCredential. Future version of this authenticator might not\n          # need it but you'll have to provide it for now.\n          - name: AUTH_API_VERSION\n            value: client.authentication.k8s.io/v1beta1\n\n          # You can fill a USER environment variable to your username if you\n          # want to overwrite the USER from your system or to an empty one if you\n          # want the authenticator to ask for one at runtime.\n          - name: USER\n            value: \"\"\n\n        args:\n          - authenticate\n\n          # This is the endpoint to authenticate against. Basically, the server\n          # started with `k8s-ldap-auth server` plus the `/auth` route, used for\n          # authentication.\n          - --endpoint=https://k8s-ldap-auth/auth\n\n        installHint: |\n          k8s-ldap-auth is required to authenticate to the current context.\n          It can be installed from https://github.com/hopopops/k8s-ldap-auth.\n\n        # This parameter, when true, tells `kubectl` to fill the TokenReview in\n        # the `$KUBERNETES_EXEC_INFO` environment variable with extra config\n        # from the definition of the specific cluster currently targeted.\n        # This is not used today but might be in the future to allow for custom\n        # rules on a per-cluster basis.\n        provideClusterInfo: false\n```\n\nThis user can be used by setting the `--user` attribute for `kubectl`:\n```\nkubectl --user my-user get nodes\n```\n\nYou can also create contexts with it:\n```yaml\ncontexts:\n  - name: context1\n    context:\n      cluster: cluster1\n      user: my-user\n  - name: context2\n    context:\n      cluster: cluster2\n      user: my-user\n\ncurrent-context: context1\n```\n\nAnd then:\n```\nkubectl --context context2 get nodes\nkubectl get nodes\n```\n\n### RBAC\nBefore you can actually get some result, you will have to upload some rolebindings to the cluster. As stated before, `k8s-ldap-auth` provides the apiserver with an ExecCredential containing both LDAP username and groups so both can be used in ClusterRoleBindings and RoleBindings.\n\nBeware: group DNs, username and user id are all set to lowercase in the TokenReview.\n\n#### Example\n\nGiven the following ldap users:\n\n```\n# User Alice\ndn: uid=alice,ou=people,ou=company,ou=local\nismemberof: cn=somegroup,ou=groups,ou=company,ou=local\n\n# User Bob\ndn: uid=bob,ou=people,ou=company,ou=local\nismemberof: cn=somegroup,ou=groups,ou=company,ou=local\n\n# User Carol\ndn: uid=carol,ou=people,ou=company,ou=local\n```\n\nIf I want to bind `cluster-admin` ClusterRole to the user `carol`, I can create a ClusterRoleBinding as following:\n```yaml\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\n  name: custom-cluster-admininistrators\nroleRef:\n  apiGroup: rbac.authorization.k8s.io\n  kind: ClusterRole\n  name: cluster-admin\nsubjects:\n- apiGroup: rbac.authorization.k8s.io\n  kind: User\n  name: carol\n```\n\nLet's say I want to bind the `view` ClusterRole so that all user in the group `somegroup` will have view access to a given namespace, I can create a RoleBinding such as:\n```yaml\napiVersion: rbac.authorization.k8s.io/v1\nkind: RoleBinding\nmetadata:\n  name: namespace-users\n  namespace: somenamespace\nroleRef:\n  apiGroup: rbac.authorization.k8s.io\n  kind: ClusterRole\n  name: view\nsubjects:\n- apiGroup: rbac.authorization.k8s.io\n  kind: Group\n  name: cn=somegroup,ou=groups,ou=company,ou=local\n```\n\nNote: Kubernetes comes with some basic [predefined roles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) for you to use.\n\n## Build\n\nA stripped binary can be built with:\n```\nmake k8s-ldap-auth\n```\n\nA stripped and compressed binary can be build with:\n```\nmake release\n```\n\nDocker release multi-arch image can be built and pushed with:\n```\nPLATFORM=\"linux/arm/v7,linux/amd64\" make docker\n```\n\n`PLATFORM` defaults to `linux/arm/v7,linux/arm64/v8,linux/amd64`\n\n## Distribution\n### Docker\nDocker images of this project are available for arm/v7, arm64/v8 and amd64 at [hopopops/k8s-ldap-auth](https://hub.docker.com/r/hopopops/k8s-ldap-auth) on docker hub and on quay.io at [hopopops/k8s-ldap-auth](https://quay.io/hopopops/k8s-ldap-auth).\n\n### Binary\nBinaries for the following OS and architectures are available on the release page:\n - linux/arm64\n - linux/arm\n - linux/amd64\n - darwin/arm64\n - darwin/amd64\n - windows/amd64\n\n### Linux\n#### Archlinux\n[![AUR version](https://img.shields.io/aur/version/k8s-ldap-auth?label=k8s-ldap-auth\u0026style=for-the-badge)](https://aur.archlinux.org/packages/k8s-ldap-auth/)\n\n[![AUR version](https://img.shields.io/aur/version/k8s-ldap-auth-bin?label=k8s-ldap-auth-bin\u0026style=for-the-badge)](https://aur.archlinux.org/packages/k8s-ldap-auth-bin/)\n\n[![AUR last modified](https://img.shields.io/aur/last-modified/k8s-ldap-auth-git?label=k8s-ldap-auth-git\u0026style=for-the-badge)](https://aur.archlinux.org/packages/k8s-ldap-auth-git/)\n\n### Darwin\n#### With `brew`\n`k8s-ldap-auth.rb` is not in the official repository, you can install it from [my repository](https://github.com/hopopops/homebrew-tap) with the following commands:\n\n`brew install hopopops/tap/k8s-ldap-auth`\n\nOr `brew tap hopopops/tap` and then `brew install k8s-ldap-auth`.\n\n### Kubernetes\n#### Helm Chart\nA Chart is hosted at [hopopops/chartrepo](https://hopopops.github.io/chartrepo/). Please see [its readme](https://github.com/hopopops/chartrepo/blob/main/charts/k8s-ldap-auth/README.md) for more information on how to install it.\n\n## Inspiration\nI originally started this project after reading Daniel Weibel's article \"Implementing LDAP authentication for Kubernetes\" (https://learnk8s.io/kubernetes-custom-authentication or https://itnext.io/implementing-ldap-authentication-for-kubernetes-732178ec2155).\n\n## What's next\n - Group search for ldap not supporting `memberof` attribute ;\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHopopOps%2Fk8s-ldap-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHopopOps%2Fk8s-ldap-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHopopOps%2Fk8s-ldap-auth/lists"}