JWT Header Auth

Authenticate API requests with JWTs minted by your own identity provider

Onyx can accept a JWT that your identity provider or API gateway mints, and use it to authenticate a request. This is useful when another system already holds the user’s identity and calls Onyx on their behalf — for example an API gateway, a portal, or a service that fronts Onyx for its own users.

Set JWT_PUBLIC_KEY_URL to a URL that serves the public key material for your token issuer. When the variable is set, Onyx accepts a signed JWT in the Authorization header:

Authorization: Bearer <JWT>

This option is part of Onyx Community Edition. It needs no Enterprise license, and it works the same way in both editions. See Support and stability below.

Setup

1. Publish your public key

   Your identity provider must serve the verification key at a URL that the Onyx API server can reach. Onyx accepts two formats:

   • JWKS — a JSON document with a keys array. This is what Microsoft Entra ID, Okta, Auth0, and most other providers publish at their jwks_uri.
   • PEM — a single PEM-encoded RSA public key.

   Onyx picks the format from the response. A response with Content-Type: application/json, or a body that starts with {, is read as JWKS. Any other body is read as PEM.

   Most identity providers list the JWKS URL in their OIDC discovery document at https://<YOUR_IDP>/.well-known/openid-configuration, under the jwks_uri field.

2. Configure Onyx

   Set the variable in your .env or values.yaml file (Docker and Kubernetes, respectively).

   .env

   JWT_PUBLIC_KEY_URL=https://<YOUR_IDP>/.well-known/jwks.json
   

   values.yaml

   configMap:
     JWT_PUBLIC_KEY_URL: https://<YOUR_IDP>/.well-known/jwks.json
   

   Restart the API server to apply the change.

3. Send a request

   Put the token in the Authorization header of any Onyx API call. GET /api/me returns the user that Onyx resolved, so it is a good first check.

   curl https://<YOUR_ONYX_DOMAIN>/api/me \
     -H "Authorization: Bearer <JWT>"
   

Token requirements

Requirement	Value
Signature	RS256
Identity claim	The first valid email address in email, preferred_username, then upn
Expiry	exp is enforced. Expired tokens are rejected
Audience	aud and iss are checked when an expected value is configured (v4.7.0+), and unchecked otherwise

The address in the identity claim is normalized and lowercased. It becomes the Onyx user’s email.

With no expected audience configured, any token that your configured key signs is accepted, even if it was minted for a different application. If the signing key is shared across several applications, set an expected audience so only tokens minted for Onyx authenticate.

Audience and issuer enforcement

Starting in v4.7.0, Onyx can enforce the aud and iss claims. When an expected value is set, a token whose claim does not match is rejected, and a token missing the claim is rejected too (the check fails closed). Both the string and array forms of aud are accepted, and an array containing the expected audience matches.

Configure the values at Admin Panel → Security & Hardening → External JWT Authentication, or with environment variables:

Setting	Environment variable
Public Key URL	JWT_PUBLIC_KEY_URL
Expected Audience	JWT_EXPECTED_AUDIENCE
Expected Issuer	JWT_EXPECTED_ISSUER

A setting whose environment variable is set is pinned: the environment value wins over anything saved in the admin panel, and the field displays as read-only text. This keeps auth-gating configuration as reviewable config-as-code that cannot be changed from inside the application, even by an admin account. With the variable unset, the value saved in the admin panel applies. On startup, Onyx mirrors set environment values into the database, so removing a variable later keeps its last pinned value in effect.

A Public Key URL saved through the admin panel must use https and is validated against the deployment’s SSRF Protection level, at save time and on every fetch, with redirects held to the same rules. A URL pinned by the environment variable is trusted as operator configuration and skips these checks, so internal endpoints stay usable when the operator configures them. Changes made from the admin panel are recorded in the audit log with the acting user and the old and new values.

Key selection and rotation

When the URL serves JWKS, Onyx selects the key by the token header kid, then by x5t. If neither matches and the document holds exactly one key, Onyx uses that key.

Onyx caches the fetched key material. If verification fails, Onyx clears the cache, fetches the URL again, and retries once. Routine key rotation therefore needs no restart.

User handling

A request authenticated by JWT is treated like any other logged-in user.

• Just-in-time provisioning. If no Onyx user has that email, Onyx creates one. The account is marked verified and gets a random password it never uses.
• Existing users. If the email belongs to an existing user, that user is returned. Deactivated users are rejected. Accounts that are not web-login accounts are rejected.
• Access policies still apply. The email must satisfy the same invite allowlist and VALID_EMAIL_DOMAINS rules as every other login path.
• Session expiry. With TRACK_EXTERNAL_IDP_EXPIRY=true, Onyx stores the token’s exp as the user’s external IdP expiry.

A user provisioned this way gets no elevated permissions, with one exception: the first user on an empty instance becomes an admin, whichever login path creates them. Grant admin access to anyone else from the Admin Panel → Users page, or add them to a group that grants the permissions they need.

Enterprise Edition adds two behaviors on this path. Emails in the default-admin list are made admins at creation. Provisioning a new user also consumes a license seat, so a login for an unknown user fails once the workspace reaches its seat limit. Community Edition applies no seat limit. Enterprise Edition can also manage access through SCIM.

Precedence

A valid Onyx session cookie takes priority. Onyx reads the Authorization header only when the request has no session.

API keys and personal access tokens use the same header. Onyx tries the JWT path first, and a value that is not a valid RS256 JWT falls through to the API key and personal access token paths. Those credentials keep working unchanged when JWT_PUBLIC_KEY_URL is set.

Support and stability

JWT_PUBLIC_KEY_URL is a documented and supported configuration option. Onyx treats it like every other published setting on this page:

• The variable name, the Authorization: Bearer header, the RS256 requirement, the accepted key formats, and the identity claim order are part of the documented interface.
• Automated tests cover the behavior described above — existing-user login, just-in-time provisioning, rejection of tokens signed by an unknown key, rejection of expired tokens, and key rotation without a restart.
• If a future release changes or replaces this option, the change is called out in the release notes for that release, together with the mechanism that replaces it.

If you plan to build an integration on this option, contact us. We are happy to review your design and tell you about anything on the roadmap that touches it.

Troubleshooting

Onyx logs every verification failure on the API server. Check api_server logs for these messages:

Log message	Cause
JWT_PUBLIC_KEY_URL is not set	The variable is missing or empty
Failed to fetch JWT public key	Onyx cannot reach the URL. Check egress rules and TLS
JWT public key URL returned invalid JSON	The response looks like JSON but does not parse
no JWKS 'keys' field was found	The JSON response is not a JWKS document
No matching JWK found for token header	The token kid is absent from the JWKS document
Invalid JWT token	Bad signature, expired token, or an algorithm other than RS256
no email claim found	None of email, preferred_username, or upn holds a valid email

A request that fails JWT verification is not rejected outright. It continues as an unauthenticated request, and the endpoint returns 401 if it needs a user.