Skip to content

JSON Web Token Authentication

JSON Web Tokens (JWT) authentication is an open standard (RFC 7519). It is a JSON object containing information (claims) that can be trusted because it is digitally signed. To sign the JWT, a hashed secret or a public/private key pair can be used.

The authentication is based on the HTTP header Authorization: Bearer <JWT>. The Traefik Hub Agent ensures both the JWT validity and claims conditions. The request is forwarded to the service if the checks succeed.

Claims

The JWT Claims Set represents a JSON object whose members are the claims conveyed by the JWT.

Those claims can be used to authorize requests based on the following functions:

Function Description Example
Equals The value in key must be equal to value. Equals(`grp`, `admin`)
Prefix The value in key must start with the prefix of value. Prefix(`referrer`, `http://example.com`)
Contains (string) The value in key must contain value. Contains(`referrer`, `/foo/`)
Contains (array) The array in key must contain the value. Contains(`areas`, `home`)
SplitContains The value in key must contain the value once split by the separator. SplitContains(`scope`, ` `, `writer`)
OneOf The array in key must contain one of the values. OneOf(`areas`, `office`, `lab`)

All functions can be joined by boolean operands. The supported operands are:

Operand Description Example
&& Compares two functions and returns true only if both evaluate to true. Equals(`grp`, `admin`) && Equals(`active`, `true`)
\\ Compares two functions and returns true if either evaluate to true. Equals(`grp`, `admin`) \
! Returns false if the function is true, otherwise returns true. !Equals(`grp`, `testers`)

All examples return true for the following data structure:

{
  "active": true,
  "grp": "admin",
  "scope": "reader writer deploy",
  "referrer": "http://example.com/foo/bar",
  "areas": [
    "office",
    "home"
  ]
}

Nested claims

Nested claims are supported by using a dot (.) between keys. For example:

user.name
{
  "active": true,
  "grp": "admin",
  "scope": "reader writer deploy",
  "referrer": "http://example.com/foo/bar",
  "areas": [
    "office",
    "home"
  ],
  "user" {
    "name": "John Snow",
    "status": "undead"
  }
}
John Snow

Handling keys that contain a dot (.)

If the key contains a dot, the dot can be escaped using a backslash (\).

Handling a key that contains a backslash ()

If the key contains a \, it needs to be doubled \\.

Web Interface

You can manage your Access Control Policies from the Traefik Hub UI.

Traefik Hub Agent

Creating any Access Control Policy (ACP) requires you to have a connected Traefik Hub Agent. Please, refer to the installation guide for more information.

To create a JWT Access Control Policy, click on the Create a policy button at the top-right corner of the page or go to the creation page directly.

Create ACP

Create JWT

The form contains general and method-specific fields.

Required

These are the required fields to fill to be able to create an Access Control Policy.

Field Example Description
Name my-jwt-auth-acp-1 The name identifies the ACP and is used to reference this resource in other components.
Must be less than 63 characters and should only contain letters, numbers, and hyphens.
Agent my-agent Reference to the agent on which the ACP will be created.
Method JWT Authentication protocol to use in this ACP.
Token Validation Method Signing Secret Secret method used to sign the JWT. Could be one of Signing Secret, JKWs URL, JKWs File and Public Key

Additional Parameters

These parameters allow you to configure the JWT authentication deeper. They are not mandatory.

Field Example Description
Claims my-claim Custom verification to apply on the JWT Claims.
Strip Authorization Header Enabled/Disabled Removes the Authorization headers from the request once authenticated.
Token Query Key jwt Sets the query parameter to use as JWT source.
Forward Headers my-claim1:claim1 Sets the HTTP headers to add to requests and populates them with claim values extracted from a JWT.

When all the fields are set up, click on the Save button to register the Access Control Policy on your cluster. The newly created ACP should be visible and manageable from the Access Control Policies listing page.

Custom Resource Definition

Custom Resource Definition is only available on Kubernetes.

Access Control Policies can be configured from Kubernetes manifest files containing a Traefik Hub custom resource. Custom Resource Definition contains resources that the Traefik Hub Agent can understand in order to manage ACPs.

The resource is called AccessControlPolicy from the hub.traefik.io group.

Here is the minimal working configuration to create a basic Access Control Policy.

apiVersion: hub.traefik.io/v1alpha1
kind: AccessControlPolicy
metadata:
  name: my-jwt-auth
spec:
  jwt:
    signingSecret: mysecret

To create the ACP, apply the manifest on the cluster using the Kubernetes CLI tool:

kubectl apply -f jwt-acp.yml

You are now able to see the ACP in the Traefik Hub UI, and in your Kubernetes cluster:

kubectl get accesscontrolpolicy my-jwt-auth

References

Name

metadata.name

This is the name of the resource. The name is used to reference this resource in other Kubernetes resources and is also visible in the Traefik Hub UI.

The name should have less than 63 characters. It should contain only letters, numbers, and hyphens.

Example:

metadata:
  name: my-jwt-auth-1

Authentication Source Options

One of the following authentication sources must be set.

Signing Secret

spec.jwt.signingSecret

The signingSecret option can be set to the secret used for signing the JWT certificates. It is then used by the Agent to verify incoming requests.

Example:

spec:
  jwt:
    signingSecret: my-secret

Signing Secret Base64 Encoded

spec.jwt.signingSecretBase64Encoded

The signingSecretBase64Encoded option can be set to indicate that the signingSecret is base64-encoded. If set to true, the signingSecret is base64-decoded before being used.

Example:

spec:
  jwt:
    signingSecret: c3VwZXItc2VjcmV0Cg==
    signingSecretBase64Encoded: true

JWKs Url

spec.jwt.jwksUrl

The jwksUrl option can be used as an alternative to a signing secret to verify incoming requests. It is the URL of the host serving a JWK set.

The keys are cached if the HTTP Cache Control allows caching.

More information on JWK can be found in RFC 7517.

This option can either be set to a full URL (e.g.: https://www.googleapis.com/oauth2/v3/certs) or to a path (e.g.: /oauth2/v3/certs). In the first case, the ACP simply fetches the keys located at the URL to verify the token. In the second case, the middleware builds the full URL using the iss property found in the JWT claims. It does so by concatenating the host defined by iss and the path set by jwksURL.

Example:

spec:
  jwt:
    jwksUrl: https://www.googleapis.com/oauth2/v3/certs

JWKs File

spec.jwt.jwksFile

The jwksFile option can be used as an alternative to a signing secret to verify incoming requests. The option can either be a path to a file mounted on the Agent or directly the content of a JWK set file.

More information on JWK can be found in RFC 7517.

Example:

spec:
  jwt:
    jwksFile: /etc/config/jwks.json

Public Key

spec.jwt.publicKey

The publicKey option can be used as an alternative to a signing secret to verify incoming requests. In that case, users should sign their token using a private key, and the public key can be used to verify the signature.

Example:

spec:
  jwt:
    publicKey:  |-
      -----BEGIN PUBLIC KEY-----
      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnzyis1ZjfNB0bBgKFMSv
      vkTtwlvBsaJq7S5wA+kzeVOVpVWwkWdVha4s38XM/pa/yr47av7+z3VTmvDRyAHc
      aT92whREFpLv9cj5lTeJSibyr/Mrm/YtjCZVWgaOYIhwrXwKLqPr/11inWsAkfIy
      tvHWTxZYEcXLgAXFuUuaS3uF9gEiNQwzGTU1v0FqkqTBr4B8nW3HCN47XUu0t8Y0
      e+lf4s4OxQawWD79J9/5d3Ry0vbV3Am1FtGJiJvOwRsIfVChDpYStTcHTCMqtvWb
      V6L11BWkpzGXSW4Hv43qa+GSYOD2QU68Mb59oSk2OB+BtOLpJofmbGEGgvmwyCI9
      MwIDAQAB
      -----END PUBLIC KEY-----

Claims

spec.jwt.claims

The claims option sets conditions to authorize the request.

Example:

spec:
  jwt:
    claims: Equals(`grp`, `admin`)

Strip Authorization Header

spec.jwt.stripAuthorizationHeader

Remove the Authorization headers from the request once authenticated.

Example:

spec:
  jwt:
    stripAuthorizationHeader: true

Forward Headers

spec.jwt.forwardHeaders

The forwardHeaders option sets the HTTP headers to add to requests and populates them with claim values extracted from a JWT.

Note

Claims to be forwarded that are not found in the JWT result in empty headers.

Example:

spec:
  jwt:
    forwardHeaders:
      group: grp