https://github.com/ivanjosipovic/ingress-nginx-validate-jwt
Enables Kubernetes ingress-nginx to validate JWT tokens
https://github.com/ivanjosipovic/ingress-nginx-validate-jwt
ingress ingress-nginx jwt jwt-authentication kubernetes nginx traefik validate
Last synced: 8 months ago
JSON representation
Enables Kubernetes ingress-nginx to validate JWT tokens
- Host: GitHub
- URL: https://github.com/ivanjosipovic/ingress-nginx-validate-jwt
- Owner: IvanJosipovic
- License: mit
- Created: 2022-09-28T15:13:12.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-03-13T10:07:30.000Z (8 months ago)
- Last Synced: 2025-03-16T02:47:27.733Z (8 months ago)
- Topics: ingress, ingress-nginx, jwt, jwt-authentication, kubernetes, nginx, traefik, validate
- Language: C#
- Homepage:
- Size: 482 KB
- Stars: 45
- Watchers: 1
- Forks: 9
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# ingress-nginx-validate-jwt
[](https://codecov.io/gh/IvanJosipovic/ingress-nginx-validate-jwt)
[](https://github.com/IvanJosipovic/ingress-nginx-validate-jwt)
[](https://artifacthub.io/packages/helm/ingress-nginx-validate-jwt/ingress-nginx-validate-jwt)
[](https://hub.docker.com/r/ivanjosipovic/ingress-nginx-validate-jwt)
| :exclamation: This project has been superseded by [OIDC-Guard](https://github.com/IvanJosipovic/OIDC-Guard), which provides authentication and authorization for both APIs and web applications, supporting JWT, cookie authentication, and more! |
|-----------------------------------------|
## What is this?
This project is an API server which is used along with the [nginx.ingress.kubernetes.io/auth-url](https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md#external-authentication) annotation for ingress-nginx and enables per Ingress customizable JWT validation.
### Supports AMD64 and ARM64
## Install
```bash
helm repo add ingress-nginx-validate-jwt https://ivanjosipovic.github.io/ingress-nginx-validate-jwt
helm repo update
helm install ingress-nginx-validate-jwt \
ingress-nginx-validate-jwt/ingress-nginx-validate-jwt \
--create-namespace \
--namespace ingress-nginx-validate-jwt \
--set openIdProviderConfigurationUrl="https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration"
```
### Options
- openIdProviderConfigurationUrl
- OpenID Provider Configuration Url for your Identity Provider
- logLevel
- Logging Level (Trace, Debug, Information, Warning, Error, Critical, and None)
- [Helm Values](charts/ingress-nginx-validate-jwt/values.yaml)
## Configure Ingress
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ingress
namespace: default
annotations:
nginx.ingress.kubernetes.io/auth-url: http://ingress-nginx-validate-jwt.ingress-nginx-validate-jwt.svc.cluster.local:8080/auth?tid=11111111-1111-1111-1111-111111111111&aud=22222222-2222-2222-2222-222222222222&aud=33333333-3333-3333-3333-333333333333
spec:
```
## Parameters
The /auth endpoint supports configurable parameters in the format of \{claim\}=\{value\}. In the case the same claim is called more than once, the traffic will have to match only one.
For example, using the following query string
/auth?
tid=11111111-1111-1111-1111-111111111111
&aud=22222222-2222-2222-2222-222222222222
&aud=33333333-3333-3333-3333-333333333333
Along with validating the JWT token, the token must have a claim tid=11111111-1111-1111-1111-111111111111 and one of aud=22222222-2222-2222-2222-222222222222 or aud=33333333-3333-3333-3333-333333333333
### How to query arrays
The /auth endpoint is able to query arrays. We'll use the following JWT token in the example.
```json
{
"email": "johndoe@example.com",
"groups": ["admin", "developers"],
}
```
Using the following query string we can limit this endpoint to only tokens with an admin group
/auth?
groups=admin
### Inject claims as headers
The /auth endpoint supports a custom parameter called "inject-claim". The value is the name of claim which will be added to the response headers.
For example, using the following query string
/auth?
tid=11111111-1111-1111-1111-111111111111
&aud=22222222-2222-2222-2222-222222222222
&inject-claim=email
The /auth response will contain header email=someuser@domain.com
### Inject claims as headers with custom name
The value should be in the following format, "\{claim name\},\{header name\}".
For example, using the following query string
/auth?
tid=11111111-1111-1111-1111-111111111111
&aud=22222222-2222-2222-2222-222222222222
&inject-claim=email,mail
The /auth response will contain header mail=someuser@domain.com
Example Ingress
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: app
annotations:
nginx.ingress.kubernetes.io/auth-url: http://ingress-nginx-validate-jwt.ingress-nginx-validate-jwt.svc.cluster.local:8080/auth?aud=11111111-11111-1111111111&inject-claim=groups,JWT-Claim-Groups&inject-claim=scope,JWT-Claim-Scope
nginx.ingress.kubernetes.io/auth-response-headers: JWT-Claim-Groups, JWT-Claim-Scope
```
## Design
## Metrics
Metrics are exposed on :8080/metrics
| Metric Name | Description |
|---|---|
| ingress_nginx_validate_jwt_authorized | Number of Authorized operations ongoing |
| ingress_nginx_validate_jwt_unauthorized | Number of Unauthorized operations ongoing |
| ingress_nginx_validate_jwt_duration_seconds | Histogram of JWT validation durations |
## Building locally
```
cd src/ingress-nginx-validate-jwt
docker build -t ingress-nginx-validate-jwt -f Dockerfile .
docker run ingress-nginx-validate-jwt -e "OpenIdProviderConfigurationUrl=https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration"
```