ingress-nginx-validate-jwt

What is this?

This project is an API server which is used along with the nginx.ingress.kubernetes.io/auth-url annotation for ingress-nginx and enables per Ingress customizable JWT validation.

Install

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

Configure Ingress

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.

{
  "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

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=https%3A%2F%2Fexample.com%2Fgroups,groups&inject-claim=scope
    nginx.ingress.kubernetes.io/configuration-snippet: |
      auth_request_set $groups $upstream_http_groups;
      auth_request_set $scope $upstream_http_scope;
      proxy_set_header JWT-Claim-Groups $groups;
      proxy_set_header JWT-Claim-Scope $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