simonschneider / traefik-jwt-decode Goto Github PK

Traefik forward auth implementation for JWT tokens

License: Apache License 2.0

Go 91.06% Dockerfile 0.73% Makefile 3.30% Mustache 4.91%

traefik forwardauth jwt-auth jwt-tokens jwt-authentication

traefik-jwt-decode's Introduction

Traefik JWT Decode

Traefik Forward auth implementation that decodes and validates JWT (JWS) tokens and populates headers with configurable claims from the token. The tokens are validated using jwks, checked for expiration and cached.

If the token is invalid, ie. can't be verified or is expired traefik-jwt-decode will respond with a UNAUTHORIZED 401.

If the token is valid traefik-jwt-decode will respond with a OK 200 and headers mapped from the claims of the token and an additional (configurable) jwt-token-validated: true header. Traefik should be configured to forward these headers via the authResponseHeaders which forwards them to the end destination.

If no token is present on the request and AUTH_HEADER_REQUIRED is true, traefik-jwt-decode will return 401.

If no token is present on the request and AUTH_HEADER_REQUIRED is false, traefik-jwt-decode will return 200 and set the header jwt-token-validated: false.

Installation and usage

Minimal with helm

The below example will deploy traefik-jwt-decode into kubernetes which will map the claims email and scopes into the headers jwt-token-email and jwt-token-scopes.

It will then create a traefik forwardAuth middleware that forwards the jwt-token-validated, jwt-token-email and jwt-token-scopes to the upstream service.

cd _helm

helm install traefik-jwt-decode traefik-jwt-decode \
  --set env.JWKS_URL="https://www.googleapis.com/oauth2/v3/certs" \
  --set env.CLAIM_MAPPINGS="email:jwt-token-email,scopes:jwt-token-scopes"

cat <<EOF >> traefik-auth-resource.yaml
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: jwt-decode-auth
spec:
  forwardAuth:
    address: http://traefik-jwt-decode:8080
    authResponseHeaders:
      - jwt-token-validated
      - jwt-token-email
      - jwt-token-scopes
EOF

kubectl apply -f traefik-auth-resource.yaml

Configuring and running the docker image:

minimal (with claimMapping env variable)

docker run \
  -e CLAIM_MAPPINGS="claim-123:header-123,claim-456:header-456" \
  -e JWKS_URL="https://www.googleapis.com/oauth2/v3/certs" \
  -p 8080:8080 \
  simonschneider/traefik-jwt-decode:latest

minimal (with claim file):

echo "{ \"claim-123\": \"header-123\" }" > config.json

docker run \
  -v $(pwd)/config.json:/config.json \
  -e JWKS_URL="https://www.googleapis.com/oauth2/v3/certs" \
  -p 8080:8080 \
  simonschneider/traefik-jwt-decode:latest

Configuration reference

required configurations:

JWKS_URL
url pointing at the jwks json file (https://auth0.com/docs/tokens/concepts/jwks)

default configurations

CLAIM_MAPPING_FILE_PATH    = config.json
AUTH_HEADER_KEY            = Authorization
TOKEN_VALIDATED_HEADER_KEY = jwt-token-validated
AUTH_HEADER_REQUIRED       = false
PORT                       = 8080
LOG_LEVEL                  = info                = trace | debug | info | warn | crit
LOG_TYPE                   = json                = json | pretty
MAX_CACHE_KEYS             = 10000
CACHE_ENABLED              = true
FORCE_JWKS_ON_START        = true

optional configurations

CLAIM_MAPPINGS=claim1:header1,claim2:header2
set up claim mappings by env, on the format
the above corresponds to the json

{
  "claim1": "header1",
  "claim2": "header2"
}

traefik-jwt-decode's People

Contributors

Stargazers

Watchers

Forkers

pnocera colcek jinsoo-youn nstankov-bg mattwilliamson athics-team atb-as eduardomineo rdwinter2 papercup-ai ghpr-asia

traefik-jwt-decode's Issues

Refactor testing

the testing right now relies on global vars a lot, refactor it to be more streamlined and easy to extend.

Support nested json claim mapping

Some IDPs such as Keycloak uses nested JSON claims such as realm_access or address. Here is the example:

{
   "realm_access":{
      "roles":[
         "offline_access",
         "default-roles-tcl",
         "uma_authorization"
      ]
   },
   "address":{
      "city":"City"
   }
}

It would be good to define mapping like realm_access.roles:x-user-roles or address.city:city to extract values from nested structs.

add metrics

Prometheus support with metrics:

http_server_request_duration
authed_requests
unauthed_requests
unauthorized_requests
cache_size
cache_hits
cache_misses

Testing

increase coverage

"No token" results in 200 OK

As stated in the README:

If no token is present on the request traefik-jwt-decode will return 200 and set the header jwt-token-validated: false.

Is there any reason behind?

I am asking because I expect traefik-jwt-decode to fail with 401 if no Authorization header is set. I have set up traefik with traefik-jwt-decode as forward auth middleware and I would like to block any incoming request without that header set. Is there a way to do it?

Maybe this behavior could be slightly modified through an env var, as happened for #28 ? Or maybe there is a way to do it with other traefik middlewares?

Thank you very much

Configure max cache size

Roles Validation

Just want to confirm that Roles Validation is not supported, right?
Is there any chance to add this feature?

It should be great to validate the roles of the user to return an Ok or Error. For example: Let's assume that I have 2 different users (Admin and NormalUser), and I want to access to an application that only admins can use, so if I send a token from the admin user that includes the admin role should return an Ok and if I send a token from a NormalUser without the admin role it should return an error.

Cache failed tokens to improve ddos protection

Use proper logging and error wrapping

logging:
https://github.com/rs/zerolog

error wrapping:
https://blog.golang.org/go1.13-errors

Documentation

a readme

Improve release process

As this is an OpenSource project without CI/CD we should consider switching to a more deliberate release process instead of releasing new versions whenever we merge to master.

Move configuration into config package

Make a single line main function in the main file. Move all config into a config package.

Helm chart

helm chart for simple installation

add tracing

Liveliness probe check fails with 401 in Kubernetes using Helm chart

Helm repository : https://athics-team.github.io/traefik-jwt-decode/
Helm chart : traefik-jwt-decode
Helm version : 0.1.0
Helm values

replicaCount: 1
service:
  port: 8080
env:
  PORT: 8080
  AUTH_HEADER_REQUIRED: "true"
  JWKS_URL: https://myauth0tenant.auth0.com/.well-known/jwks.json

When deploying to my Kubernetes cluster, the liveliness probe check fails (401). I looked at the configuration and the probe checks (both liveliness and readiness) were not set to use /ping but the default / instead, despite the configuration in this file.

Do you have any idea of how to fix this ?