Overview

This guide provides the requirements for JWT tokens used with OpenID Connect (OIDC) in Clavister systems. These requirements include both standard claims as defined by the OIDC specification and an additional header requirement unique to Clavister.

Prerequisites

Ensure you have a working OIDC provider configured and that you understand the basics of JSON Web Tokens (JWT). Refer to the OIDC specification for general OIDC and JWT information.

JWT Requirements

A JWT (JSON Web Token) consists of three parts: the Header, Payload, and Signature. Each section must adhere to specific requirements to ensure compatibility with Clavister’s OIDC implementation.

1. Header Requirements

The JWT header must specify the token type and the hashing algorithm used to sign the token. The following claims are required:

Claim: alg
Description: The algorithm used to sign the JWT, typically HS256 or RS256.
Example: “alg”: “RS256”

Claim: typ
Description: Clavister-specific requirement. This claim must be set to “JWT” to comply with Clavister’s implementation.
Example: “typ”: “JWT”

2. Payload Requirements

The JWT payload must contain specific claims for proper authorization and authentication. The following are essential:

Claim: iss
Description: The issuer of the token. Must match the OIDC provider’s identifier.
Example: “iss”: “https://issuer.example.com”

Claim: sub
Description: The subject (user) the token refers to.
Example: “sub”: “user@example.com”

Claim: aud
Description: The audience for which the token is intended. Must match Clavister’s client ID.
Example: “aud”: “clavister_client_id”

Claim: exp
Description: The expiration time of the token as a Unix timestamp.
Example: “exp”: 1690887600

Claim: iat
Description: Issued-at time of the token as a Unix timestamp.
Example: “iat”: 1690884000

3. Signature

The JWT must be signed with the algorithm specified in the header. The signature ensures the token’s integrity and authenticity.

Example JWT Token

Below is an example structure of a JWT token formatted for Clavister OIDC requirements:

Header: “typ”: “JWT”,
“alg”: “RS256”,
“kid”: “9GmnyFPkhc3hOuR22mvSvgnLo7Y”

Payload: “aud”: “8d0208c5-d8ec-45b6-9845-4eb90cfe2a09”,
“iss”: “https://login.microsoftonline.com/1f66a877-2fb6-433f-80c2-e8aa6e368c68/v2.0”,
“iat”: 1697785476,
“nbf”: 1697785476,
“exp”: 1697789376,
“groups”: [“2b628494-67a8-47c8-a5c2-7a3dde8ca1f6”, “805e120a-80b0-469e-bbfb-c46eca902151”],
“nonce”: “1599046102647-dv4”,
“rh”: “0.AUsAd6hmH7YvP0OAwuiqbjaMaMUIAo3s2LZFmEVOuQz-KglLAD4.”,
“sub”: “jpG9t2IADisETTj2WJOFRfURa6JW68rbbz-Hjbou2Gw”,
“tid”: “1f66a877-2fb6-433f-80c2-e8aa6e368c68”,
“uti”: “IaqN-9DW4k-9sWtMHAPNAA”,
“ver”: “2.0”

Troubleshooting

If you experience issues authenticating with Clavister, ensure:

• The typ field in the header is explicitly set to "JWT".
• The audience (aud) matches the Clavister client ID.

For further assistance, contact Clavister Support.

Related articles