# Access policies (/docs/guides/access)



For a Cloudflare setup, follow the [Cloudflare Access guide](/docs/guides/cloudflare-access).

Every instance must declare [`access`](/docs/reference/desired#desiredinstance-access). For a
public app:

```json
"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`](/docs/reference/desired#desiredinstance-access) to the instance in `desired.json`:

```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-----"]
}
```

3. Replace the example key with the issuer's complete PEM public key. Never supply a private key.
4. Send requests with `Authorization: Bearer <JWT>`.

| Setting                                                | Meaning                                                                        |
| ------------------------------------------------------ | ------------------------------------------------------------------------------ |
| [`kind`](/docs/reference/desired#jwt-kind)             | `jwt` to require a token.                                                      |
| [`token`](/docs/reference/desired#jwt-token)           | The header containing the token and its format: `raw` or `bearer`.             |
| [`issuer`](/docs/reference/desired#jwt-issuer)         | The exact expected `iss` claim.                                                |
| [`audiences`](/docs/reference/desired#jwt-audiences)   | At least one of these values must match the token's `aud` claim.               |
| [`algorithm`](/docs/reference/desired#jwt-algorithm)   | The signing algorithm: `RS256`, `ES256` or `EdDSA`.                            |
| [`publicKeys`](/docs/reference/desired#jwt-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 [#use-a-jwks-endpoint]

To follow the issuer's signing-key rotation, replace the PEM array with its HTTPS JWKS URL:

```json
"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 [#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 [#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.

<Callout title="HTTP only">
  Access policies protect the [hostname proxy](/docs/guides/https). Explicitly exposed
  [raw ports](/docs/guides/raw-ports) carry traffic without JWT verification.
</Callout>
