{"id":16943377,"url":"https://github.com/carlpett/nginx-subrequest-auth-jwt","last_synced_at":"2025-03-22T12:33:01.093Z","repository":{"id":45011898,"uuid":"204871298","full_name":"carlpett/nginx-subrequest-auth-jwt","owner":"carlpett","description":"Auth requests through NGINX with JWT tokens","archived":false,"fork":false,"pushed_at":"2021-04-08T18:23:32.000Z","size":29,"stargazers_count":43,"open_issues_count":2,"forks_count":17,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-18T11:22:52.401Z","etag":null,"topics":["jwt","nginx","nginx-ingress-controller"],"latest_commit_sha":null,"homepage":"","language":"Go","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/carlpett.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":"2019-08-28T07:15:56.000Z","updated_at":"2024-03-12T13:09:35.000Z","dependencies_parsed_at":"2022-08-25T13:41:46.191Z","dependency_job_id":null,"html_url":"https://github.com/carlpett/nginx-subrequest-auth-jwt","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlpett%2Fnginx-subrequest-auth-jwt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlpett%2Fnginx-subrequest-auth-jwt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlpett%2Fnginx-subrequest-auth-jwt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlpett%2Fnginx-subrequest-auth-jwt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carlpett","download_url":"https://codeload.github.com/carlpett/nginx-subrequest-auth-jwt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244959449,"owners_count":20538625,"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":["jwt","nginx","nginx-ingress-controller"],"created_at":"2024-10-13T21:14:18.481Z","updated_at":"2025-03-22T12:33:00.832Z","avatar_url":"https://github.com/carlpett.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nginx-subrequest-auth-jwt\nThis project implements a simple JWT validation endpoint meant to be used with NGINX's [subrequest authentication](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/), and specifically work well with the Kubernetes [NGINX Ingress Controller](https://github.com/kubernetes/ingress-nginx) external auth annotations.\n\nIt validates a JWT token passed in the `Authorization` header against a configured public key, and further validates that the JWT contains appropriate claims.\n\n## Limitations\nThe configuration format currently only supports a single elliptic curve public key for signature validation, and does not have a facility for rotating keys without restart. Basic support in the configuration format for supporting multiple active keys, and of different types, at once is in place but currently not used.\n\n# Configuration\nA number of flags affect how the service is started:\n\nFlag     | Description | Default\n---------|-------------|--------------------\n  --help | Show help | -\n  --config | Path to configuration file | config.yaml\n  --log-level| Log level | info\n  --tls-key | Path to TLS key | `\u003crequired\u003e`\n  --tls-cert | Path to TLS cert | `\u003crequired\u003e`\n  --addr | Address/port to serve traffic in TLS mode | :8443\n  --insecure | Serve traffic unencrypted over http | false\n  --insecure-addr | Address/port to serve traffic in insecure mode | :8080\n\n## Configuration file\nThe service takes a configuration file in YAML format, by default `config.yaml`. For example:\n\n```yaml\nvalidationKeys:\n  - type: ecPublicKey\n    key: |\n      -----BEGIN PUBLIC KEY-----\n      ...\n      -----END PUBLIC KEY-----\nclaimsSource: static\nclaims:\n  - group:\n      - developers\n      - administrators\n```\n\nWith this configuration, a JWT will be validated against the given public key, and the claims are then matched against the given structure, meaning there has to be a `group` claim, with either a `developers` or `administrators` value.\n\nClaims can either be statically set, as in the above example, or passed via query string parameters. The `claimsSource` configuration parameter controls which mode the server operates in, and can be either `static` or `queryString`. Further examples of the two modes are given below.\n\n### Static\n\nMultiple alternative allowed sets of claims can be configured, for example:\n\n```yaml\nvalidationKeys:\n  - type: ecPublicKey\n    key: |\n      -----BEGIN PUBLIC KEY-----\n      ...\n      -----END PUBLIC KEY-----\nclaims:\n  - group:\n      - developers\n      - administrators\n  - deviceClass:\n      - server\n      - networkEquipment\n```\n\nIn this case, the token claims **either** needs to have the groups as per the previous example, **or** a `deviceClass` of `server` or `networkEquipment`.\n\nThere can also be multiple claims requirements, for example:\n\n```yaml\nvalidationKeys:\n  - type: ecPublicKey\n    key: |\n      -----BEGIN PUBLIC KEY-----\n      ...\n      -----END PUBLIC KEY-----\nclaims:\n  - group:\n      - developers\n      - administrators\n    location:\n      - hq\n```\n\nHere, the token claims must **both** have the groups as before, **and** a `location` of `hq`.\n\n### Query string\nIn query string mode, the allowed claims are passed via query string parameters to the /validate endpoint. For example, with `/validate?claims_group=developers\u0026claims_group=administrators\u0026claims_location=hq`, the token claims must **both** have a `group` claim of **either** `developers` or `administrators`, **and** a `location` claim of `hq`.\n\nEach claim must be prefixed with `claims_`. Giving the same claim multiple time results in any value being accepted.\n\nIn this mode, in contrast to static mode, only a single set of acceptable claims can be passed at a time (but different NGINX server blocks can pass different sets).\n\nIf no claims are passed in this mode, the request will be denied.\n\n# NGINX Ingress Controller integration\nTo use with the NGINX Ingress Controller, first create a deployment and a service for this endpoint. See the [kubernetes/](kubernetes/) directory for example manifests. Then on the ingress object you wish to authenticate, add this annotation for a server in static claims source mode:\n\n```yaml\nnginx.ingress.kubernetes.io/auth-url: https://nginx-subrequest-auth-jwt.default.svc.cluster.local:8443/validate\n```\n\nOr, in query string mode:\n\n```yaml\nnginx.ingress.kubernetes.io/auth-url: https://nginx-subrequest-auth-jwt.default.svc.cluster.local:8443/validate?claims_group=developers\n```\n\nChange the url to match the name of the service and namespace you chose when deploying. All requests will now have their JWTs validated before getting passed to the upstream service.\n\n# Metrics\nThis endpoint exposes [Prometheus](https://prometheus.io) metrics on `/metrics`:\n\n- `http_requests_total{status=\"\u003cstatus\u003e\"}` number of requests handled, by status code (counter)\n- `nginx_subrequest_auth_jwt_token_validation_time_seconds` number of seconds spent validating tokens (histogram)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlpett%2Fnginx-subrequest-auth-jwt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlpett%2Fnginx-subrequest-auth-jwt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlpett%2Fnginx-subrequest-auth-jwt/lists"}