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.
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. | No | |
Token name | Name of the claim that contains the name of the token. | azp | No |
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.
| 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. |
Examples
The following configuration example will use jwksUrl to validate JWT against a Keycloak or Okta instance, using the claims groups and sub.
- Keycloak
- Okta
| 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 |
| 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 |
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.
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.
curl -i --url 'https://api.example.com/tickets/tickets' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer abCdeFciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbkBleGFtcGxlLmNvbSIsIm5hbWUiOiJteS10b2tlbiIsImdyb3VwcyI6WyJhZG1pbiJdfQ.INzvgtArvSYdz3CDTresRdcmwPKocgEsFv_aH123456'
Which will show:
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.