{"id":17961005,"url":"https://github.com/slok/simple-ingress-external-auth","last_synced_at":"2026-03-15T10:45:28.247Z","repository":{"id":36959164,"uuid":"505058021","full_name":"slok/simple-ingress-external-auth","owner":"slok","description":"A very simple external authentication service for Kubernetes ingresses (ingress-nginx, traefik...)","archived":false,"fork":false,"pushed_at":"2025-02-12T20:30:18.000Z","size":157,"stargazers_count":19,"open_issues_count":3,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-19T08:39:17.630Z","etag":null,"topics":["auth","authentication","external-auth","external-authentication","ingress","ingress-nginx","k8s","kubernetes","nginx","traefik"],"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/slok.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-19T08:55:53.000Z","updated_at":"2024-11-10T12:07:17.000Z","dependencies_parsed_at":"2024-06-19T05:27:55.043Z","dependency_job_id":"d999e735-3926-4708-b808-52a0e59fb2f4","html_url":"https://github.com/slok/simple-ingress-external-auth","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Fsimple-ingress-external-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Fsimple-ingress-external-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Fsimple-ingress-external-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slok%2Fsimple-ingress-external-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slok","download_url":"https://codeload.github.com/slok/simple-ingress-external-auth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245394746,"owners_count":20608122,"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":["auth","authentication","external-auth","external-authentication","ingress","ingress-nginx","k8s","kubernetes","nginx","traefik"],"created_at":"2024-10-29T11:08:02.440Z","updated_at":"2026-03-15T10:45:23.213Z","avatar_url":"https://github.com/slok.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# simple-ingress-external-auth\n\n[![CI](https://github.com/slok/simple-ingress-external-auth/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/slok/simple-ingress-external-auth/actions/workflows/ci.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/slok/simple-ingress-external-auth)](https://goreportcard.com/report/github.com/slok/simple-ingress-external-auth)\n[![Apache 2 licensed](https://img.shields.io/badge/license-Apache2-blue.svg)](https://raw.githubusercontent.com/slok/simple-ingress-external-auth/master/LICENSE)\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/slok/simple-ingress-external-auth)](https://github.com/slok/simple-ingress-external-auth/releases/latest)\n\nEasy and simple Kubernetes ingress authentication.\n\n## How does it work\n\nMost kubernetes ingress have a way of delegating the authentication to an external auth system.\n\nTo make this possible normally the ingress controller will forward the request to the external auth system (this auth app), and the auth app will return a 200 if its authenticated, and different than 200 if its not.\n\nWhen it starts, this application will load a configuration file where it has all the tokens defined (and some other optional properties).\n\nWhen the ingress-controller forwards the request, this app will check for `Authorization: Bearer \u003ctoken\u003e` header and validate against the tokens it has defined.\n\n## Proxy examples that can be used:\n\n### Nginx\n\n[ingress-nginx external authentication](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#external-authentication):\n\nNginx is the default configuration used by simple-ingress-external-auth:\n\n- `--request-method-header=X-Original-Method`\n- `--request-url-header=X-Original-URL`\n\n### Traefik\n\n[traefik forward authentication](https://doc.traefik.io/traefik/v2.0/middlewares/forwardauth/) options that can be used on simple-ingress-external-auth:\n\n- `--request-method-header=X-Forwarded-Method`\n- `--request-url-header=X-Forwarded-Uri`\n\n## Features\n\n- Simple and easy to deploy (no complex setup, no databases...).\n- Ability to rotate tokens (create a new token and add expiration date to the old one).\n- Authenticate Kubernetes ingress easily.\n- Fast and scalable (everything is in memory).\n- Advanced token validation properties (expire date, disable...).\n- Can be used with GRPC (e.g [ingress-nginx grpc](https://kubernetes.github.io/ingress-nginx/examples/grpc/))\n- Different configuration formats (including env vars substitution support).\n- Optionally return the authenticated client ID in a header.\n\n## Example\n\n```bash\n$  docker run --rm -it -p 8080:8080 -p 8081:8081 ghcr.io/slok/simple-ingress-external-auth --token-config-data='{\"version\": \"v1\",\"tokens\": [{\"value\": \"6kXEuNEWMYcd1yP16HsgrA==\"}]}'\nINFO[0000] Tokens loaded                                 addr=\":8080\" app=simple-ingress-external-auth svc=memory.TokenRepository tokens=1 version=dev\nINFO[0000] http server listening for requests            addr=\":8080\" app=simple-ingress-external-auth version=dev\nINFO[0000] http server listening for requests            addr=\":8081\" app=simple-ingress-external-auth health-check=/status metrics=/metrics pprof=/debug/pprof version=dev\n```\n\n```bash\n$ curl -I -H \"Authorization: Bearer 1234567890\" http://127.0.0.1:8080/auth\nHTTP/1.1 401 Unauthorized\nDate: Mon, 20 Jun 2022 05:39:41 GMT\nContent-Length: 13\nContent-Type: text/plain; charset=utf-8\n\ncurl -I -H \"Authorization: Bearer 6kXEuNEWMYcd1yP16HsgrA==\" http://127.0.0.1:8080/auth\nHTTP/1.1 200 OK\nDate: Mon, 20 Jun 2022 05:39:50 GMT\n```\n\n## Token format\n\nThere is no restriction on the token format, for this application, it's just an string. You can use `1234567890` (please don't) or a JWT token.\n\nAn easy and portable way of generating tokens, would be using the old well known `openssl`, e.g:\n\n```bash\n$ openssl rand -base64 32\ngmMCgSWCDzuBKxznnH7+vCajFnhRIK1+sTRvGJI2g1I=\n```\n\n## Advanced optional properties\n\nApart from regular token validation, we can use different optional properties:\n\n- `client_id`: Not a security option, but used as metadata, for debugging/auditing purposes and token identification.\n- `disable`: Will disable the token, handy when we want to disable temporally a token.\n- `expires_at`: After the specified timestamp (RFC3339) the token will be invalid. Handy to rotate tokens.\n- `allowed_url`: Regex that will validate the original URL being requested (Got from `X-Original-URL` header).\n- `allowed_method`: Regex that will validate the original method being requested (Got from `X-Original-Method` header).\n\n## Configuration\n\nThe tokens that the application will load will be provisioned with a configuration file (simple and portable). It has some features:\n\n- JSON and YAML.\n- Env vars substitution (`${X_Y_Z}` style).\n\n### JSON example\n\n```json\n{\n \"version\": \"v1\",\n \"tokens\": [\n  {\n   \"value\": \"9bOlMT/vGlWCq56D+Ycgp7eTNj9uQWInbGf4tjRr/P8=\",\n   \"client_id\": \"test1\"\n  },\n  {\n   \"value\": \"NOX11CM2EP9xlP0HsS8NRPNHMmsQKQis7egKGcI+tHQ=\",\n   \"client_id\": \"test2\",\n   \"disable\": true,\n   \"expires_at\": \"2022-07-04T14:21:22.52Z\",\n   \"allowed_url\": \"https://custom.host.slok.dev/.*\",\n   \"allowed_method\": \"(GET|POST)\"\n  },\n  {\n   \"value\": \"6yvOSWrLmjC+2Vz8QdwHCjYoHyqWkD+70krxDt5XzlY=\",\n   \"client_id\": \"test3\",\n   \"allowed_method\": \"PUT\"\n  }\n  {\n   \"value\": \"${TOKEN_CLIENT_3}\",\n   \"client_id\": \"test4\"\n  }\n ]\n}\n```\n\n### YAML example\n\n```yaml\nversion: v1\ntokens:\n- value: 9bOlMT/vGlWCq56D+Ycgp7eTNj9uQWInbGf4tjRr/P8=\n  client_id: \"test1\"\n- value: NOX11CM2EP9xlP0HsS8NRPNHMmsQKQis7egKGcI+tHQ=\n  client_id: \"test2\"\n  disable: true\n  expires_at: 2022-07-04T14:21:22.52Z\n  allowed_url: https://custom.host.slok.dev/.*\n  allowed_method: (GET|POST)\n- value: 6yvOSWrLmjC+2Vz8QdwHCjYoHyqWkD+70krxDt5XzlY=\n  client_id: \"test3\"\n  allowed_method: PUT\n- value: ${TOKEN_CLIENT_3}\n  client_id: \"test4\"\n```\n\n### As a Go API\n\nYou can access the configuration as a Go library so you can automate easily the creation of the configuration file.\n\nImport as:\n\n```go\npackage main\n\nimport (\n apiv1 \"github.com/slok/simple-ingress-external-auth/pkg/api/v1\"\n)\n\nfunc main() {\n //...\n}\n```\n\n[Check this example of generating 1000k tokens](examples/config-generator).\n\n## Why tokens and not basic auth\n\nAlthough basic auth is simple and easy to use for web UIs, they are not secure. Tokens on the other side yes:\n\n- Unique: The generated tokens can easily be unique (e.g: use `openssl` or [JWT](https://jwt.io/) to generate the tokens).\n- Revocable: Tokens can have an expiration date, removed or temporally disabled. This gives us the ability to rotate them easily.\n- Limited: Tokens can be narrowly scoped to specific URLs.\n- Random: As with the `Unique` property, the tokens generated can be randomly generated easily with tools like `openssl`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslok%2Fsimple-ingress-external-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslok%2Fsimple-ingress-external-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslok%2Fsimple-ingress-external-auth/lists"}