Operator reference

JWT Header Auth

Authenticate API requests with JWTs minted by your own identity provider

Before you begin

This reference describes the underlying platform. Use a Nexus school release with its school membership, class policy, and cost controls. Installing a base engine alone does not add those controls. Some options require a separately licensed feature. The presence of a guide does not unlock that feature.

Nexus 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 Nexus on their behalf. for example an API gateway, a portal, or a service that fronts Nexus 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, Nexus accepts a signed JWT in the Authorization header:

Authorization: Bearer <JWT>

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

Setup#

Publish your public key#

Your identity provider must serve the verification key at a URL that the Nexus API server can reach. Nexus 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.

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

Configure Nexus#

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

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

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

Restart the API server to apply the change.

Send a request#

Put the token in the Authorization header of any Nexus API call. GET /api/me returns the user that Nexus 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 Nexus 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 Nexus authenticate.

Audience and issuer enforcement#

Starting in v4.7.0, Nexus 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, Nexus 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, Nexus selects the key by the token header kid, then by x5t. If neither matches and the document holds exactly one key, Nexus uses that key.

Nexus caches the fetched key material. If verification fails, Nexus 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 Nexus user has that email, Nexus 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, Nexus 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 Nexus session cookie takes priority. Nexus reads the Authorization header only when the request has no session.

API keys and personal access tokens use the same header. Nexus 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. Nexus 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#

Nexus 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`	Nexus 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.