JSON Web Token (JWT)

This page describes how to configure a service with JSON Web Tokens (JWT) as Access Control Policy.

Introduction to JWT¶

JSON Web Tokens (JWT) are an open standard (RFC 7519). JWTs are JSON objects containing information (claims) that can be trusted because they are 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¶

JSON web tokens claims are pieces of information asserted about a subject.

For example, a token can contain a claim called grp that declares a group (admin in the example below).

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:

Key

user.name

Claims

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

Result

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, select the Create a policy button or go to the creation page directly.

The form contains general and method-specific fields.

Required fields¶

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, select the Save button to register the Access Control Policy. 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 to manage ACPs.

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

See this minimal working configuration to create a basic Access Control Policy.

jwt-acp.yaml

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¶

Required

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¶

Required

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 JSON Web Key (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 (for example: https://www.googleapis.com/oauth2/v3/certs) or to a path (for example: /oauth2/v3/certs).

In the first case, the ACP 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