{"id":16885126,"url":"https://github.com/ericchiang/kube-oidc","last_synced_at":"2025-03-22T08:30:38.214Z","repository":{"id":57536571,"uuid":"134009302","full_name":"ericchiang/kube-oidc","owner":"ericchiang","description":"OpenID Connect utilities for Kubernetes","archived":false,"fork":false,"pushed_at":"2018-05-30T16:23:44.000Z","size":2192,"stargazers_count":38,"open_issues_count":1,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-18T09:45:37.617Z","etag":null,"topics":["authentication","kubernetes","oidc","openid-connect"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ericchiang.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-05-18T22:21:10.000Z","updated_at":"2022-10-01T15:13:31.000Z","dependencies_parsed_at":"2022-08-29T00:40:31.537Z","dependency_job_id":null,"html_url":"https://github.com/ericchiang/kube-oidc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericchiang%2Fkube-oidc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericchiang%2Fkube-oidc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericchiang%2Fkube-oidc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericchiang%2Fkube-oidc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ericchiang","download_url":"https://codeload.github.com/ericchiang/kube-oidc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244931299,"owners_count":20534005,"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":["authentication","kubernetes","oidc","openid-connect"],"created_at":"2024-10-13T16:33:27.158Z","updated_at":"2025-03-22T08:30:37.524Z","avatar_url":"https://github.com/ericchiang.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenID Connect utilities for Kubernetes\n\n[![Build Status](https://travis-ci.org/ericchiang/kube-oidc.svg?branch=master)](https://travis-ci.org/ericchiang/kube-oidc)\n\n## OpenID Connect and Kubernetes\n\n[OpenID Connect][oidc-docs] is an extension of OAuth2 that introduces ID Tokens, a signed JSON Web Token with standard claims representing users.\n\nFor example, OpenID Connect might return the following JWT:\n\n```\neyJhbGciOiJSUzI1NiIsImtpZCI6IjAyOWYyNjlmM2YwNmFmMWU5M2RhYzY3MDYzOTc3ZjcxM2E3N2YxOWUifQ.eyJhenAiOiIxMDc3ODQxODE2OTU5LWtrZGgwbHZxMWF1ODBxdjRndHVib3R2Z3M5YW00YTk1LmFwcHMuZ29vZ2xldXNlcmNvbnRlbnQuY29tIiwiYXVkIjoiMTA3Nzg0MTgxNjk1OS1ra2RoMGx2cTFhdTgwcXY0Z3R1Ym90dmdzOWFtNGE5NS5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbSIsInN1YiI6IjEwMzYxMzAwMzc2NDQ5MDY0ODQ0OSIsImhkIjoicmVkaGF0LmNvbSIsImVtYWlsIjoiZWNoaWFuZ0ByZWRoYXQuY29tIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImF0X2hhc2giOiJPR0RPaklKOTJGa2F0REJvQ204eWRnIiwiZXhwIjoxNTI3MjAzOTQwLCJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJpYXQiOjE1MjcyMDAzNDAsIm5hbWUiOiJFcmljIENoaWFuZyIsInBpY3R1cmUiOiJodHRwczovL2xoNS5nb29nbGV1c2VyY29udGVudC5jb20vLUNzMmlIVFhpRVRzL0FBQUFBQUFBQUFJL0FBQUFBQUFBQUNNLzBRODVVaFppempnL3M5Ni1jL3Bob3RvLmpwZyIsImdpdmVuX25hbWUiOiJFcmljIiwiZmFtaWx5X25hbWUiOiJDaGlhbmciLCJsb2NhbGUiOiJlbiJ9.RjnTPN6RoQqL-lufUoAZxfaNVzET1uBZpszEodRZJlutYdThZHq_97bitG_qy5mIy07BmBPvr6lqOAeqBadENSkudhj6pQR9C3YD5Uyj9yTh7xp4CUx01Az6gsi8OCOgE1RCDRVwAialRhBlf3GCz4QBtBcwogTNVBoiDEwa5SKfopnwxsuKo_mBoHOjo9i_h-SakybrTe5ZJY_FuthtDli-s5LpFCuaiTLv6UpR84Zw9sNaxQ7Riiw1Mxya0xQXZnewhoJ8N2TwYlXuJJORvF0Pe2qjDwQmMEiqrv53E-f6C5pekGZip-ZtpDvZ7WmlNd5yGIbB8xvcH0RuHQLOoA\n```\n\nThis ID Token holds claims such as the user's emal, username, and an expiration:\n\n```json\n{\n    \"azp\": \"1077841816959-kkdh0lvq1au80qv4gtubotvgs9am4a95.apps.googleusercontent.com\",\n    \"aud\": \"1077841816959-kkdh0lvq1au80qv4gtubotvgs9am4a95.apps.googleusercontent.com\",\n    \"sub\": \"103613003764490648449\",\n    \"hd\": \"redhat.com\",\n    \"email\": \"echiang@redhat.com\",\n    \"email_verified\": true,\n    \"at_hash\": \"OGDOjIJ92FkatDBoCm8ydg\",\n    \"exp\": 1527203940,\n    \"iss\": \"https://accounts.google.com\",\n    \"iat\": 1527200340,\n    \"name\": \"Eric Chiang\",\n    \"picture\": \"https://lh5.googleusercontent.com/-Cs2iHTXiETs/AAAAAAAAAAI/AAAAAAAAACM/0Q85UhZizjg/s96-c/photo.jpg\",\n    \"given_name\": \"Eric\",\n    \"family_name\": \"Chiang\",\n    \"locale\": \"en\"\n}\n```\n\nMany providers have support for OpenID Connect, including:\n\n* [Google][google-oidc]\n* [Azure][azure-oidc]\n* [Okta][okta-oidc]\n* [Salesforce][salesforce-oidc]\n* [Dex][dex]\n\nKubernetes can validate [ID Tokens][kubernetes-oidc], but leaves login flows and other conviences as exercises to the user. This repo is intended to hold tools that fill in gaps and improve the experience of setting up SSO for Kubernetes clusters.\n\n[azure-oidc]: https://msdn.microsoft.com/en-us/library/azure/dn645541.aspx\n[dex]: https://github.com/coreos/dex\n[google-oidc]: https://developers.google.com/identity/protocols/OpenIDConnect\n[kubernetes-oidc]: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens\n[oidc-docs]: http://openid.net/connect/\n[okta-oidc]: https://developer.okta.com/docs/api/resources/oidc\n[salesforce-oidc]: https://developer.salesforce.com/page/Inside_OpenID_Connect_on_Force.com\n\n## kube-oidc-login\n\n`kube-oidc-login` is an OAuth2 client for generating user kubeconfig files. It logs in the user through an OpenID connect provider, then templates the returned ID Token into the kubeconfig:\n\n![](docs/imgs/kube-oidc-login.png)\n\n## kube-oidc-proxy\n\n`kube-oidc-proxy` is an authenticating proxy for the Kubernetes API server. It authenticates OpenID Connect ID Tokens then [impersonates the authenticated user][impersonation] to the API server.\n\nUnlike other OpenID Connect solutions, `kube-oidc-proxy` doesn't require reconfiguration of the API server and works with any Kubernetes cluster out of the box.\n\n[impersonation]: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation\n\n## Getting started\n\nThis guide requires:\n\n* A Kubernetes cluster (consider [Minikube][minikube] to run one locally)\n* An OAuth2 Google client credentials and a Google account\n* Go 1.10+\n\nClone this repo to your local [GOPATH][gopath].\n\n```\ngit clone https://github.com/ericchiang/kube-oidc.git $( go env GOPATH )/src/github.com/ericchiang/kube-oidc\ncd $( go env GOPATH )/src/github.com/ericchiang/kube-oidc\n```\n\nRegister a \"Web application\" [OAuth client with Google][google-oauth2] and enter `http://localhost:8080/login/callback` as an authorized redirect URI. Set the OAuth client ID and secret as environment variables, as well as your email:\n\n```\nexport GOOGLE_OAUTH2_CLIENT_ID=\"...\"\nexport GOOGLE_OAUTH2_CLIENT_SECRET=\"...\"\nexport USER_EMAIL=\"jane.doe@gmail.com\"\n```\n\nThe `examples` directory holds reference config files for `kube-oidc-login` and `kube-oidc-proxy`. Use `sed` to template these with the values defined above and generate self-signed certs for the proxy:\n\n```\nmkdir -p assets\nmkdir -p secrets\nsed \"s/CLIENT_ID/$GOOGLE_OAUTH2_CLIENT_ID/g\" examples/config-login.yaml \u003e assets/config-login.yaml\nsed \"s/CLIENT_ID/$GOOGLE_OAUTH2_CLIENT_ID/g\" examples/config-proxy.yaml \u003e assets/config-proxy.yaml\necho -n \"$GOOGLE_OAUTH2_CLIENT_SECRET\" \u003e secrets/client-secret\nkubectl config view --raw=true \u003e secrets/kubeconfig\nmake example-certs\nsed \"s/USER_EMAIL/$USER_EMAIL/g\" examples/rbac.yaml \u003e assets/rbac.yaml\nkubectl apply -f assets/rbac.yaml\n```\n\nThese commands should create the following directory structure:\n\n```\n$ tree assets/ secrets/\nassets/\n├── ca.csr\n├── ca-key.pem\n├── ca.pem\n├── config-login.yaml\n├── config-proxy.yaml\n├── rbac.yaml\n├── server.csr\n├── server-key.pem\n└── server.pem\nsecrets/\n├── client-secret\n└── kubeconfig\n\n0 directories, 11 files\n```\n\nFirst, run `kube-oidc-login`:\n\n```\nmake\n./bin/kube-oidc-login serve assets/config-login.yaml\n```\n\nIn another window run `kube-oidc-proxy`:\n\n```\n./bin/kube-oidc-proxy serve assets/config-proxy.yaml\n```\n\nVisit [http://localhost:8080/](http://localhost:8080) to login with Google. The `email` claim MUST match the `USER_EMAIL` environment variable defined above. If the values don't match, re-template and re-apply the RBAC manifest.\n\nUse the downloaded kubeconfig to access the cluster through the OpenID Connect proxy:\n\n```\n$ kubectl --kubeconfig ~/Downloads/kubeconfig get pods -n kube-system\nNAME                                                              READY     STATUS    RESTARTS   AGE\nheapster-6f69d6797f-jvlg8                                         2/2       Running   3          5d\nkube-apiserver-f94t9                                              1/1       Running   1          5d\nkube-controller-manager-6d6db4c69d-jmhtj                          1/1       Running   2          5d\nkube-dns-64cd9cc494-bqwvx                                         3/3       Running   3          5d\nkube-flannel-jzqjz                                                2/2       Running   4          5d\nkube-flannel-xvblb                                                2/2       Running   2          5d\nkube-proxy-kgqth                                                  1/1       Running   1          5d\nkube-proxy-rzqsk                                                  1/1       Running   1          5d\nkube-scheduler-7b675dc9f7-jppj6                                   1/1       Running   1          5d\npod-checkpointer-h298b                                            1/1       Running   1          5d\npod-checkpointer-h298b-ip-10-0-22-42.us-west-1.compute.internal   1/1       Running   1          5d\n$ kubectl --kubeconfig ~/Downloads/kubeconfig get nodes\nError from server (Forbidden): nodes is forbidden: User \"echiang@redhat.com\" cannot list nodes at the cluster scope\n```\n\n[google-oauth2]: https://developers.google.com/identity/protocols/OpenIDConnect#appsetup\n[gopath]: https://github.com/golang/go/wiki/GOPATH\n[minikube]: https://github.com/kubernetes/minikube\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericchiang%2Fkube-oidc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericchiang%2Fkube-oidc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericchiang%2Fkube-oidc/lists"}