Access policies
Require a signed JWT before an HTTP request can reach or wake an app.
For a Cloudflare setup, follow the Cloudflare Access guide.
Every instance must declare access. For a
public app:
"access": { "kind": "public" }To require a signed JWT:
- Configure your identity service or access proxy to issue signed JWTs for the app's audience.
- Add
accessto the instance indesired.json:
"access": {
"kind": "jwt",
"token": { "header": "Authorization", "format": "bearer" },
"issuer": "https://identity.example.com",
"audiences": ["internal-app"],
"algorithm": "RS256",
"publicKeys": ["-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"]
}- Replace the example key with the issuer's complete PEM public key. Never supply a private key.
- Send requests with
Authorization: Bearer <JWT>.
| Setting | Meaning |
|---|---|
kind | jwt to require a token. |
token | The header containing the token and its format: raw or bearer. |
issuer | The exact expected iss claim. |
audiences | At least one of these values must match the token's aud claim. |
algorithm | The signing algorithm: RS256, ES256 or EdDSA. |
publicKeys | One to eight PEM public keys, or { "url": "https://…" } for a JWKS endpoint. |
The policy covers every platform and custom hostname of the app. A missing or invalid token
receives 403 before the guest is contacted, so a rejected request cannot wake a sleeping app.
Tokens must contain iss, aud and an unexpired exp. A supplied nbf must have passed.
The issuer decides who receives tokens for the app. Your access proxy or client handles login and supplies the configured header. nibrunner verifies the token on each HTTP request, including the request that opens a WebSocket connection.
Use a JWKS endpoint
To follow the issuer's signing-key rotation, replace the PEM array with its HTTPS JWKS URL:
"publicKeys": { "url": "https://identity.example.com/.well-known/jwks.json" }Keep the expected issuer, audiences and signing algorithm explicit. Tokens must include a kid
that matches a signing key in the fetched set. A missing or unknown kid receives 403.
The host fetches keys in the background when the endpoint is configured, then every five minutes.
Failed fetches retry every 30 seconds. Previously fetched keys remain usable for at most 15
minutes after the last successful fetch. Until keys are available, or after they expire, requests
receive 503 without contacting or waking the app. Requests never fetch keys themselves.
The endpoint must use HTTPS with a trusted certificate. Redirects are refused. Each fetch has a 10-second timeout and accepts at most 256 KiB containing up to 32 keys. Empty key sets revoke all keys. Unsupported key types and keys marked for another algorithm or for encryption are ignored. Malformed sets retain the previous keys until their original expiry. URLs in token headers do not affect the configured endpoint. The cache is held in memory and is fetched again on restart.
Change or remove a policy
Edit access in desired state to change the policy. The host applies the change to new requests
without replacing the deployment or restarting the guest. Set "access": { "kind": "public" }
to allow requests without a token. Policy changes do not close connections that have already
upgraded to WebSockets.
The host keeps the policy across daemon restarts. A malformed policy refuses the new desired document and leaves the last accepted document in effect. To rotate a supplied key, publish the old and new public keys together, switch the issuer to the new signing key, then remove the old public key when its tokens no longer need to be accepted.
Upgrade existing documents
Set "access": { "kind": "public" } on every existing public instance before upgrading the
daemon. Set kind to jwt on existing JWT policies. Missing, null and untagged access values are
rejected in desired state and persisted instance records.
There is no automatic conversion for existing SQLite instance records or the last accepted document. These stored documents must also contain explicit access policies before upgrading. Incompatible persisted records are not loaded.
HTTP only
Access policies protect the hostname proxy. Explicitly exposed raw ports carry traffic without JWT verification.