Skip to main content

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 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

ClaimDescriptionExampleRequired
GroupsName 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.
groupsYes
User ID    Name of the claim that contains the user ID.subYes
User e-mailName of the claim that contains the user e-mail.emailNo
Token nameName of the claim that contains the name of the token.azpNo

Enable JWT in Traefik Hub

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

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

MethodDescription
signingSecretThe signingSecret option can be set to the secret used for signing the JWT certificates.
publicKeyThe 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.
jwksFileThe jwksFile option can be used to define a set of JWK to be used to verify the signature of JWTs.
jwksUrlThe 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

JWT settings form.

Examples

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

SettingValueExample
Token validation methodJWKs URLhttps://$KEYCLOAK-URL/realms/keycloak-demo/protocol/openid-connect/certs
Claims configurationGroupsgroups
Claims configurationUser IDsub
https://hub.traefik.io/auth-settings

Keycloak JWT configuration.

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

Configure the JWT validation and claims.

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 }
]
}