Authentication

JWT Authentication

JWT JWKS RSA

The QQL gateway validates JWTs against any JWKS-compatible identity provider. No user database or custom auth code needed.

Supported IdPs

Any IdP that exposes a JWKS endpoint:

• Auth0
• Okta
• Keycloak
• Firebase / Google Identity
• Azure Active Directory / Entra ID
• AWS Cognito
• Descope
• SuperTokens
• Custom JWKS server

Configuration

Auth configuration

qql-go serve
--jwks-url https://idp.example.com/.well-known/jwks.json
--jwt-issuer https://idp.example.com
--jwt-audience my-app
--role-claim role
--tenant-claim org_id

Flag	Description
--jwks-url	JWKS endpoint URL — keys are fetched and cached here
--jwt-issuer	Expected iss claim — tokens with different issuers are rejected
--jwt-audience	Expected aud claim — tokens with different audiences are rejected
--jwks-cache-ttl	Key cache TTL (default: 10m) — how long JWKS keys are cached
--role-claim	JWT claim path for roles (default: role)
--tenant-claim	JWT claim path for tenant ID (default: tenant_id)

Supported Key Types

• RSA (RS256, RS384, RS512)
• EC (ES256, ES384, ES512)
• Ed25519 (EdDSA)

Keys are fetched from the JWKS endpoint and cached for the configured TTL. JWKS rotation is handled automatically.

Token Format

Pass the JWT in the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Auth0 Example

Auth0 configuration

qql-go serve
--qdrant-url http://localhost:6334
--jwks-url https://<your-domain>.auth0.com/.well-known/jwks.json
--jwt-issuer https://<your-domain>.auth0.com/
--jwt-audience https://api.yourapp.com
--role-claim https://yourapp.com/roles
--tenant-claim https://yourapp.com/org_id

Nested Claim Paths

Use # as a separator to extract nested claims:

Nested claims

--role-claim app_metadata#role --tenant-claim app_metadata#org_id

This reads token.app_metadata.role and token.app_metadata.org_id.

Slice Claims

If a claim is a JSON array, the gateway treats it as a list of values. Use op: "in" in policy rules to match any member.

Unauthenticated Requests

Without --jwks-url, the gateway accepts all requests with no token required.

With --jwks-url, requests without a valid token receive 401 Unauthorized.

The Explain and Convert RPCs skip authentication in all modes (no data risk).

Validation Checks

The gateway validates:

• JWT signature (against JWKS keys)
• exp (token not expired)
• iss (matches --jwt-issuer, if set)
• aud (matches --jwt-audience, if set)

Claims are extracted into the request context after successful validation.