Guides

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:

  1. Configure your identity service or access proxy to issue signed JWTs for the app's audience.
  2. Add access to the instance in desired.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-----"]
}
  1. Replace the example key with the issuer's complete PEM public key. Never supply a private key.
  2. Send requests with Authorization: Bearer <JWT>.
SettingMeaning
kindjwt to require a token.
tokenThe header containing the token and its format: raw or bearer.
issuerThe exact expected iss claim.
audiencesAt least one of these values must match the token's aud claim.
algorithmThe signing algorithm: RS256, ES256 or EdDSA.
publicKeysOne 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.

On this page