JSON Web Tokens

JWT, or JSON Web Token, is a compact and self-contained method for transmitting information between parties as a JSON object. JWTs are used for API authorization.

---

Introduction

Every consumer in Traefik Hub is connected to an API Portal user. The user identifies the consumer, and the user access settings determine which APIs and API Portal the consumer can access.

In Traefik Hub, every user needs to be part of a user group.
It is not possible to assign an individual user to an API, however you can assign a user to a group as the only member.

When a user is a member of multiple groups, the user will inherit the permission level of the group with the most access.

Please refer to the user management documentation for more information.

info

If you switch from the default configuration (Key authentication) to JSON Web Tokens, all API keys generated in the API Portal are turned off.

---

JWT Validation

JWT claims are statements in key-value pair format about an entity (typically, the user) and additional data that are digitally signed to ensure their integrity.
For validation, Traefik Hub expects to find the following claims in the payload.

Claims

Claim	Description	Example	Required
Groups	Name of the claim that contains the user groups. To consume APIs, a user needs to be part of a user group. Please follow the APIAccess CRD and our user management documentation.	groups	Yes
User ID	Name of the claim that contains the user ID.	sub	Yes
User e-mail	Name of the claim that contains the user e-mail.	email	No
Token name	Name of the claim that contains the name of the token.	azp	No

Read More

Learn more about JWT claims by reading the official documentation.

---

Enable JWT in Traefik Hub

Select Auth settings in the dashboard to the authentication and authorization overview. Now enable JWT in the API authentication.

https://hub.traefik.io/auth-settings

Third, configure the JWT key validation method and claims.

Choose one of the following key validation techniques for your JWT.

Method	Description
signingSecret	The signingSecret option can be set to the secret used for signing the JWT certificates.
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.
jwksFile	The jwksFile option can be used to define a set of JWK to be used to verify the signature of JWTs.
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. This option can either be set to a full URL, for example https://www.googleapis.com/oauth2/v3/certs.

https://hub.traefik.io/auth-settings

Examples

The following configuration example will use jwksUrl to validate JWT against a Keycloak or Okta instance, using the claims groups and sub.

Keycloak

Setting	Value	Example
Token validation method	JWKs URL	https://$KEYCLOAK-URL/realms/keycloak-demo/protocol/openid-connect/certs
Claims configuration	Groups	groups
Claims configuration	User ID	sub

https://hub.traefik.io/auth-settings

Okta

Setting	Value	Example
Token validation method	JWKs URL	https://$your-okta-org/oauth2/$authorization-server-id/v1/keys
Claims configuration	Groups	groups
Claims configuration	User ID	sub

https://hub.traefik.io/auth-settings

Once you're done, select Save.

If you want to strip the authorization header or add forward header(s), you can do that under Additional configuration.
These settings are not required.

https://hub.traefik.io/auth-settings

Once you're done, select Save.

---

JWT Authentication Example

The following example uses curl to send test requests to an API using JWT as the authentication method.

CLI

curl -i --url 'https://api.example.com/tickets/tickets' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer abCdeFciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbkBleGFtcGxlLmNvbSIsIm5hbWUiOiJteS10b2tlbiIsImdyb3VwcyI6WyJhZG1pbiJdfQ.INzvgtArvSYdz3CDTresRdcmwPKocgEsFv_aH123456'

Which will show:

CLI Output

HTTP/2 200
access-control-allow-credentials: true
access-control-allow-origin: *
content-type: text/plain; charset=utf-8
date: Wed, 31 Jan 2024 15:42:15 GMT
x-ratelimit-limit: 2000
x-ratelimit-period: 65
x-ratelimit-remaining: 1999
x-ratelimit-reset: 1
content-length: 326

{
  "tickets": [
    { "id": 1, "flightCode": "TL123", "fare": 500, "class": "first", "available": 5, "total": 20 },
    { "id": 2, "flightCode": "TL234", "fare": 200, "class": "economy", "available": 2, "total": 5 },
    { "id": 3, "flightCode": "TL345", "fare": 300, "class": "business", "available": 3, "total": 10 }
  ]
}

---

Related Content

• Learn how to use JWT validation with Keycloak.
• See how to validate JWT with Okta.