{"id":19374717,"url":"https://github.com/gyselroth/kube-ldap","last_synced_at":"2025-04-23T18:32:06.235Z","repository":{"id":41101073,"uuid":"126817673","full_name":"gyselroth/kube-ldap","owner":"gyselroth","description":"A Webhook Token Authentication plugin for kubernetes to use LDAP as authentication source","archived":false,"fork":false,"pushed_at":"2022-12-22T11:23:30.000Z","size":805,"stargazers_count":30,"open_issues_count":15,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-06-20T10:15:34.839Z","etag":null,"topics":["javascript","kubernetes","kubernetes-authentication","kubernetes-cluster","ldap","ldap-authentication","webhook"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gyselroth.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-26T11:19:24.000Z","updated_at":"2023-01-12T01:04:49.000Z","dependencies_parsed_at":"2023-01-30T07:30:53.948Z","dependency_job_id":null,"html_url":"https://github.com/gyselroth/kube-ldap","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gyselroth%2Fkube-ldap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gyselroth%2Fkube-ldap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gyselroth%2Fkube-ldap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gyselroth%2Fkube-ldap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gyselroth","download_url":"https://codeload.github.com/gyselroth/kube-ldap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223932207,"owners_count":17227272,"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","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":["javascript","kubernetes","kubernetes-authentication","kubernetes-cluster","ldap","ldap-authentication","webhook"],"created_at":"2024-11-10T08:35:57.370Z","updated_at":"2024-11-10T08:35:57.441Z","avatar_url":"https://github.com/gyselroth.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kube-ldap\n[![Build Status](https://travis-ci.org/gyselroth/kube-ldap.svg)](https://travis-ci.org/gyselroth/kube-ldap)\n [![Coverage Status](https://coveralls.io/repos/github/gyselroth/kube-ldap/badge.svg)](https://coveralls.io/github/gyselroth/kube-ldap)\n [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA [Webhook Token Authentication](https://kubernetes.io/docs/admin/authentication/#webhook-token-authentication) plugin for kubernetes,  written in javascript, to use LDAP as authentication source.\n\n## Description\nThe kube-ldap webhook token authentication plugin can be used to integrate username/password authentication via LDAP for your kubernetes cluster.\nIt exposes two API endpoints:\n* /auth\n  * HTTP basic authenticated requests to this endpoint result in a JSON Web Token, signed by the webhook, including the username and uid of the authenticated user.\n  * The issued token can be used for authenticating to kubernetes.\n* /token\n  * Is called by kubernetes (see [TokenReview](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.9/#tokenreview-v1-authentication)) to verify the token used for authentication.\n  * Verifies the integrity of the JWT (using the signature) and returns a TokenReview response containing the username, uid, group memberships and extra attributes (if configured) of the authenticated user.\n\n## Deployment\nThe recommended way to deploy kube-ldap is deplyoing kube-ldap in kubernetes itself using the [gyselroth/kube-ldap](https://hub.docker.com/r/gyselroth/kube-ldap/) docker image.\n\nExample YAML for kubernetes (secrets, deployment including tls termination and service):\n```yaml\napiVersion: v1\ndata:\n  key: #base64 encoded jwt key (see \"Configuration\" in README)\nkind: Secret\nmetadata:\n  name: kube-ldap-jwt-key\n  namespace: kube-system\ntype: Opaque\n---\napiVersion: v1\ndata:\n  binddn: #base64 encoded bind dn (see \"Configuration\" in README)\n  bindpw: #base64 encoded bind password (see \"Configuration\" in README)\nkind: Secret\nmetadata:\n  name: kube-ldap-ldap-bind-credentials\n  namespace: kube-system\ntype: Opaque\n---\napiVersion: v1\ndata:\n  cert.pem: #base64 encoded certificate (pem)\n  key.pem: #base64 encoded private key (pem)\nkind: Secret\nmetadata:\n  name: kube-ldap-tls\n  namespace: kube-system\ntype: Opaque\n---\napiVersion: apps/v1beta2\nkind: Deployment\nmetadata:\n  labels:\n    k8s-app: kube-ldap\n  name: kube-ldap\n  namespace: kube-system\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      k8s-app: kube-ldap\n  template:\n    metadata:\n      labels:\n        k8s-app: kube-ldap\n    spec:\n      volumes:\n      - name: kube-ldap-tls\n        secret:\n          secretName: kube-ldap-tls\n      containers:\n      - env:\n        - name: LDAP_URI\n          value: #ldap uri (see \"Configuration\" in README)\n        - name: LDAP_BINDDN\n          valueFrom:\n            secretKeyRef:\n              name: kube-ldap-ldap-bind-credentials\n              key: binddn\n        - name: LDAP_BINDPW\n          valueFrom:\n            secretKeyRef:\n              name: kube-ldap-ldap-bind-credentials\n              key: bindpw\n        - name: LDAP_BASEDN\n          value: #ldap base dn (see \"Configuration\" in README)\n        - name: LDAP_FILTER\n          value: #ldap filter(see \"Configuration\" in README)\n        - name: LOGLEVEL\n          value: info\n        - name: JWT_KEY\n          valueFrom:\n            secretKeyRef:\n              name: kube-ldap-jwt-key\n              key: key\n        - name: JWT_TOKEN_LIFETIME\n          value: #jwt token lifetime (see \"Configuration\" in README)\n        image: gyselroth/kube-ldap:latest # Better use fixed version tag here since 'latest' can point to new major releases with breaking changes\n        volumeMounts:\n          - name: kube-ldap-tls\n            mountPath: \"/etc/ssl/kube-ldap\"\n        livenessProbe:\n          httpGet:\n            path: /healthz\n            port: 8080\n            scheme: HTTP\n          initialDelaySeconds: 5\n          periodSeconds: 10\n        name: kube-ldap\n        ports:\n        - containerPort: 8081\n---\napiVersion: v1\nkind: Service\nmetadata:\n  labels:\n    k8s-app: kube-ldap\n  name: kube-ldap\n  namespace: kube-system\nspec:\n  ports:\n  - port: 8081\n    protocol: TCP\n    targetPort: 8081\n  selector:\n    k8s-app: kube-ldap\n  type: ClusterIP\n```\n\n\n## Configuration\n### kube-ldap\nkube-ldap itself can be configured via environment variables.\n\nList of configurable values:\n\n|Setting|Description|Environment Variable| Default Value|\n|-------|-----------|--------------------|--------------|\n|`config.port`|HTTP port to listen|`PORT`|8081 (8080 if TLS is disabled)|\n|`config.loglevel`|Loglevel for winston logger. **CAUTION: debug loglevel may log sensitive parameters like user passwords**|`LOGLEVEL`|info|\n|`config.tls.enabled`|Enable TLS (HTTPS). **DO NOT DISABLE IN PRODUCTION UNLESS YOU HAVE A TLS REVERSE PROXY IN PLACE**|`TLS_ENABLED` (\"true\" or \"false\")|true|\n|`config.tls.cert`|Path to certificate (pem) to use for TLS (HTTPS)|`TLS_CERT_PATH`|/etc/ssl/kube-ldap/cert.pem|\n|`config.tls.key`|Path to private key (pem) to use for TLS (HTTPS)|`TLS_KEY_PATH`|/etc/ssl/kube-ldap/key.pem|\n|`config.tls.ca`|*Optional: Path to ca certificate (pem) to use for TLS (HTTPS)*|`TLS_CA_PATH`|*none*|\n|`config.ldap.uri`|URI of LDAP server|`LDAP_URI`|ldap://ldap.example.com|\n|`config.ldap.binddn`|DN of LDAP bind user connection|`LDAP_BINDDN`|uid=bind,dc=example,dc=com|\n|`config.ldap.bindpw`|Password of LDAP bind user|`LDAP_BINDPW`|secret|\n|`config.ldap.baseDn`|Base DN for LDAP search|`LDAP_BASEDN`|dc=example,dc=com|\n|`config.ldap.filter`|Filter for LDAP search|`LDAP_FILTER`|(uid=%s)|\n|`config.ldap.timeout`|Timeout for LDAP connections \u0026 operations (in seconds)|`LDAP_TIMEOUT`|0 (infinite for operations, OS default for connections)|\n|`config.mapping.username`|Name of ldap attribute to be used as username in kubernetes TokenReview|`MAPPING_USERNAME`|uid|\n|`config.mapping.uid`|Name of ldap attribute to be used as uid in kubernetes TokenReview|`MAPPING_UID`|uid|\n|`config.mapping.groups`|Name of ldap attribute to be used for groups in kubernetes TokenReview|`MAPPING_GROUPS`|memberOf|\n|`config.mapping.extraFields`|Comma separated list of additional ldap attributes to be used for extra in kubernetes TokenReview|`MAPPING_EXTRAFIELDS`|[]|\n|`config.mapping.username`|Name of Ldap attribute to be used as username in kubernetes TokenReview|`MAPPING_USERNAME`|uid|\n|`config.jwt.key`|Key for signing the JWT. **DO NOT USE THE DEFAULT VALUE IN PRODUCTION**|`JWT_KEY`|secret|\n|`config.jwt.tokenLifetime`|Seconds until token a expires|`JWT_TOKEN_LIFETIME`|28800|\n|`config.prometheus.username`|Username for prometheus exporter basic auth (use empty string to disable basic auth)|`PROMETHEUS_USERNAME`|prometheus|\n|`config.prometheus.password`|Password for prometheus exporter basic auth (use empty string to disable basic auth)|`PROMETHEUS_PASSWORD`|secret|\n|`config.prometheus.nodejsProbeInterval`|Probe interval for nodejs metrics in milliseconds|`PROMETHEUS_NODEJS_PROBE_INTERVAL`|10000|\n\n### kubernetes\nConfigure your kubernetes apiserver to use the kube-ldap [webhook for authentication](https://kubernetes.io/docs/admin/authentication/#webhook-token-authentication) using the following configuration file.\n```yaml\n# clusters refers to the remote service.\nclusters:\n  - name: kube-ldap\n    cluster:\n      server: https://your-kube-ldap-url/token\n\n# users refers to the API server's webhook configuration.\nusers:\n  - name: apiserver\n\n# kubeconfig files require a context. Provide one for the API server.\ncurrent-context: webhook\ncontexts:\n- context:\n    cluster: kube-ldap\n    user: apiserver\n  name: webhook\n```\n\n### kubectl\nYou can either use [kube-ldap-client-go-exec-plugin](https://github.com/gyselroth/kube-ldap-client-go-exec-plugin), a kubectl plugin ([client-go credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins)) doing the authentication for you, or you can do it manually.\n\nTo configure `kubectl` for manual authentication initially:\n```bash\nTOKEN=$(curl https://your-kube-ldap-url/auth -u your-username)\nkubectl config set-cluster your-cluster --server=https://your-apiserver-url [...]\nkubectl config set-credentials your-cluster-ldap --token=\"$TOKEN\"\nkubectl config set-context your-cluster --cluster=your-cluster --user=your-cluster-ldap\n```\n\nTo refresh your token after expiration:\n```bash\nTOKEN=$(curl https://your-kube-ldap-url/auth -u your-username)\nkubectl config set-credentials your-cluster-ldap --token=\"$TOKEN\"\n```\n\n\n## Development\n### Requirements\n* nodejs\n* yarn\n\n### Development Server\nDuring development an auto-reloading development server (using babel watch) can be used.\n\nRemember to set the environment variables required to configure kube-ldap. E.g.:\n```bash\nLDAP_URI=ldap://ldap.example.local TLS_ENABLED=false yarn start\n```\n\n### Test\nTo run automated tests using jest you can use yarn:\n```bash\nyarn test\n```\n\n### Build\nkube-ldap can be built via yarn, to get native nodejs code, or via docker (which uses yarn), to get a docker image.\n\nEither way the build process lints the code (including flow type annotations) before building. When building via docker the process also includes running the automated tests.\nIf any of these steps fail, the build will fail too.\n\n#### yarn\nWhen using yarn, it places the build output in `./build/` directory.\n```bash\nyarn build\n```\n\n#### docker\nWhen using docker, the `./Dockerfile` is used to build an image.\n```bash\ndocker -t kube-ldap build .\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgyselroth%2Fkube-ldap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgyselroth%2Fkube-ldap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgyselroth%2Fkube-ldap/lists"}