JWT Authentication

JSON Web Token (JWT) (defined in the RFC 7519) allows Traefik Hub API Gateway to secure the API access using a token signed using either a private signing secret or a plublic/private key.

Traefik Hub API Gateway provides many kind of sources to perform the token validation:

Setting a secret value in the middleware configuration (option signingSecret).
Setting a public key: In that case, users should sign their token using a private key, and the public key can be used to verify the signature (option publicKey).
Setting a JSON Web Key (JWK) file to define a set of JWK to be used to verify the signature of the incoming JWT (option jwksFile).
Setting a JSON Web Key (JWK) URL to define the URL of the host serving a JWK set (option jwksUrl).

One single source

The JWT middleware does not allow you to set more than one way to validate the incoming tokens.

When a Hub API Gateway receives a request that must be validated using the JWT middleware, it verifies the token using the source configured as described above. If the token is successfully checked, the request is accepted.

Claim Usage

A JWT can contain metadata in the form of claims (key-value pairs). The claims contained in the JWT can be used for advanced use-cases such as adding an Authorization layer using the claims.

More information in the dedicated section.

Verify a JWT with a secret

To allow the Traefik Hub API Gateway to validate a JWT with a secret value stored in a Kubernetes Secret, apply the following configuration:

Middleware JWT
Kubernetes Secret
IngressRoute
Service & Deployment

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
  namespace: apps
spec:
  plugin:
    jwt:
      signingSecret: "urn:k8s:secret:jwt:signingSecret"

apiVersion: v1
kind: Secret
metadata:
  name: jwt
  namespace: apps
stringData:
  signingSecret: mysuperlongsecret

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
  namespace: apps
spec:
  entryPoints:
    - websecure
  routes:
  - match: Path(`/my-app`)
    kind: Rule
    services:
    - name: whoami
      port: 80
    middlewares:
    - name: test-jwt

kind: Deployment
apiVersion: apps/v1
metadata:
  name: whoami
  namespace: apps
spec:
  replicas: 3
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
      - name: whoami
        image: traefik/whoami

---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: apps
spec:
  ports:
  - port: 80
    name: whoami
  selector:
    app: whoami

Verify a JWT using an Identity Provider

To allow the Traefik Hub API Gateway to validate a JWT using an Identity Provider, such as Keycloak and Azure AD in the examples below, apply the following configuration:

Multiple Identity Providers

If you need to accept JWTs from multiple identity providers simultaneously, use the trustedIssuers option instead of jwksUrl.

JWKS with Keycloak URL
JWKS with Azure AD URL
IngressRoute
Service & Deployment

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
  namespace: apps
spec:
  plugin:
    jwt:
      # Replace KEYCLOAK_URL and REAL_NAME with your values
      jwksUrl: https://KEYCLOAK_URL/realms/REAL_NAME/protocol/openid-connect/certs
      # Forward the content of the claim grp in the header Group
      forwardHeaders:
        Group: grp
      # Check the value of the claim grp before sending the request to the backend
      claims: Equals(`grp`, `admin`)

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
  namespace: apps
spec:
  plugin:
    jwt:
      jwksUrl: https://login.microsoftonline.com/common/discovery/v2.0/keys

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
  namespace: apps
spec:
  entryPoints:
    - websecure
  routes:
  - match: Path(`/my-app`)
    kind: Rule
    services:
    - name: whoami
      port: 80
    middlewares:
    - name: test-jwt

kind: Deployment
apiVersion: apps/v1
metadata:
  name: whoami
  namespace: apps
spec:
  replicas: 3
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
      - name: whoami
        image: traefik/whoami

---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: apps
spec:
  ports:
  - port: 80
    name: whoami
  selector:
    app: whoami

Verify JWTs from Multiple Identity Providers

The trustedIssuers option allows the Traefik Hub API Gateway to accept and validate JWTs from multiple identity providers simultaneously. Each trusted issuer is configured with its own JWKS endpoint, and optionally an expected issuer claim for strict validation.

Migrating from Traefik Enterprise Edition

If you are migrating from Traefik Enterprise Edition and were using dynamic JWKS URL resolution with the pattern {iss}/jwks.json in the jwksUrl attribute, you will need to explicitly list each issuer you expect to handle using the trustedIssuers option. This approach is more secure as it requires you to explicitly define all trusted identity providers rather than dynamically resolving them from incoming JWT tokens.

When the issuer field is specified for a trusted issuer, JWTs with a matching iss claim will be validated against that specific JWKS endpoint only. This provides strict validation ensuring tokens are only verified against their designated provider.

When the issuer field is omitted, the JWKS endpoint acts as a fallback. JWTs from any issuer can be validated against this JWKS endpoint, which is useful for identity providers that don't include an iss claim or for catch-all scenarios.

Multiple Identity Providers
With Fallback Provider
IngressRoute
Service & Deployment

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: multi-issuer-jwt
  namespace: apps
spec:
  plugin:
    jwt:
      trustedIssuers:
        - jwksUrl: https://accounts.google.com/.well-known/jwks.json
          issuer: https://accounts.google.com
        - jwksUrl: https://login.microsoftonline.com/common/discovery/v2.0/keys
          issuer: https://login.microsoftonline.com/{tenant}/v2.0
        - jwksUrl: https://dev-12345.okta.com/oauth2/default/v1/keys
          issuer: https://dev-12345.okta.com/oauth2/default

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: jwt-with-fallback
  namespace: apps
spec:
  plugin:
    jwt:
      trustedIssuers:
        - jwksUrl: https://accounts.google.com/.well-known/jwks.json
          issuer: https://accounts.google.com
        - jwksUrl: https://my-company.com/.well-known/jwks.json
          # No issuer specified - acts as fallback for any other issuer

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
  namespace: apps
spec:
  entryPoints:
    - websecure
  routes:
  - match: Path(`/my-app`)
    kind: Rule
    services:
    - name: whoami
      port: 80
    middlewares:
    - name: multi-issuer-jwt

kind: Deployment
apiVersion: apps/v1
metadata:
  name: whoami
  namespace: apps
spec:
  replicas: 3
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
      - name: whoami
        image: traefik/whoami

---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: apps
spec:
  ports:
  - port: 80
    name: whoami
  selector:
    app: whoami

JWT with OAuth2 Resource Discovery

The JWT middleware can be configured to support OAuth 2.1/2.0 Resource Server discovery (defined in OAuth 2.1 IETF DRAFT & RFC 6750) by setting the wwwAuthenticate option. This is particularly useful when integrating with the MCP middleware for Model Context Protocol servers.

Middleware JWT with OAuth Discovery
IngressRoute

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oauth-jwt
  namespace: apps
spec:
  plugin:
    jwt:
      jwksUrl: https://auth.example.com/.well-known/jwks.json
      # In case it's an MCP Server secured by the MCP Gateway, put the gateway's well-known URL here
      wwwAuthenticate: https://api.example.com/.well-known/oauth-protected-resource/mcp-server
      forwardAuthorization: true
      forwardHeaders:
        X-User-ID: sub
        X-User-Groups: groups

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: mcp-server
  namespace: apps
spec:
  entryPoints:
    - websecure
  routes:
  - match: Host(`api.example.com`)
    kind: Rule
    services:
    - name: mcp-server-service
      port: 80
    middlewares:
    - name: oauth-jwt
    - name: mcp-gateway  # MCP middleware for additional access control

When authentication fails, the JWT middleware will return a 401 Unauthorized response with a WWW-Authenticate header pointing to the OAuth resource metadata endpoint. This enables OAuth-compliant clients to discover authorization requirements automatically.

Advanced Configuration

Advanced options are described in the reference page.

For example, the metadata recovered from the Identity Provider can be used to restrict the access to the applications. To do so, you can use the claims option, more information in the dedicated section.

See the full options in the dedicated section.
See how to secure your API access using OIDC.

Verify a JWT with a secret​

Verify a JWT using an Identity Provider​

Verify JWTs from Multiple Identity Providers​

JWT with OAuth2 Resource Discovery​

Related Content​

Verify a JWT with a secret

Verify a JWT using an Identity Provider

Verify JWTs from Multiple Identity Providers

JWT with OAuth2 Resource Discovery

Related Content