Trusted JWKS
Register an external JWT provider so your own users can open sessions
When you build a frontend on uRun, your users open sessions from the browser. They
authenticate with your identity provider, and uRun verifies the JWTs they present.
urun auth trust-jwk registers the trust relationship: it tells the control plane which
external JWKS to verify your org's session JWTs against.
This command registers trust only. It never mints, fetches, or stores a JWT — your IdP issues JWTs out of band, and uRun verifies them against the JWKS you point it at. This is the terminal twin of the console's Frontend Auth page.
Register a provider
urun auth trust-jwk https://auth.example.com/.well-known/jwks.json \
--issuer https://auth.example.com \
--audience urun-sessionsTrusted JWT provider registered.
Issuer: https://auth.example.com
Audience: urun-sessions
JWKS URL: https://auth.example.com/.well-known/jwks.jsonArguments
| Argument / flag | Required | Default | Purpose |
|---|---|---|---|
<jwks_url> (positional) | yes | — | HTTPS JWKS URL for the provider |
--issuer | yes | — | Expected JWT iss claim |
--audience | yes | — | Expected JWT aud claim |
--allow-insecure-jwks-url | no | off | Permit a non-HTTPS JWKS URL (local dev only) |
--json | no | off | Emit the raw JSON response |
Session verification always reads the user's identity from the token's sub and email
claims today — custom claim-name mapping is not yet supported end-to-end, so use those
claim names in your IdP's JWTs.
HTTPS is required
The JWKS URL must be HTTPS. The CLI rejects plaintext URLs unless you explicitly pass
--allow-insecure-jwks-url, which exists only for local development against a dev IdP:
# local dev only — never in production
urun auth trust-jwk http://localhost:4000/jwks.json \
--issuer http://localhost:4000 --audience urun-dev \
--allow-insecure-jwks-urlHow this fits the auth model
uRun supports three auth modes for browser clients:
- Scoped client token (recommended onramp) — your server mints a short-lived, app-scoped token from your API key; no JWKS registration needed. See Frontend Auth.
- WorkOS — if you use WorkOS as your IdP, uRun validates short-lived WorkOS access tokens against your org's registered WorkOS JWKS (registered the same way as any customer-JWT provider).
- customer-JWT — you bring your own JWTs, validated against the JWKS you register here.
For the two JWKS-backed modes, once you've registered a provider your frontend passes
orgId plus a user JWT to the browser client; scoped client tokens skip this page
entirely. See the TypeScript SDK for the client side, and
Frontend Auth for managing trusted providers in the
console.
Trusted JWKS is the right way to authenticate browser users. Do not put the deploy API key or any long-lived secret in browser code.