How Should NATS Auth Callout Permissions Change Dynamically?

Dynamic NATS permissions with auth callout usually come down to one decision: reconnect clients so auth callout can issue a new User JWT, or use scoped signing keys and account reloads so permission templates can change without intentionally disconnecting clients.

This FAQ comes from a NATS community discussion about OAuth-backed users, project membership, and project- or device-specific subjects.

Short answer: how do dynamic auth callout permissions work?

Auth callout runs when a client connects. A reconnect also triggers auth callout again. If your callout service generates a User JWT with a complete publish and subscribe permission map, those permissions apply to the connection that was just authorized. If your application database changes later, the existing connection does not automatically receive a new generated User JWT.

That gives you two main patterns:

1. Generate full permissions in the User JWT and force reauthorization by closing the client connection when permissions change.
2. Combine auth callout with decentralized JWT auth and scoped signing keys so permission templates can be updated in the account and reloaded.

Choose based on how often permissions change, how many unique permission templates you need, whether reconnects are acceptable, and how much decentralized JWT operational complexity you want to run.

What does auth callout do when a client connects?

With auth callout, the NATS server calls your authentication service when a client connects. Your service can inspect the latest external identity state, such as an OAuth userinfo response, project membership, or an application database, and return current authorization data for that new connection.

A reconnect follows the same path: the client reconnects, auth callout runs again, and your service can make a fresh authorization decision.

The important boundary is that auth callout is not a live subscription to your application authorization database. If the callout service embeds a full permissions map in the generated User JWT, changing your external database later does not automatically rewrite the effective permissions for an already-authorized connection.

Option 1: should you generate full User JWT permissions and kick connections?

Use this pattern when reconnects are acceptable and you want the simplest dynamic authorization model.

The flow is:

1. The client connects.
2. Auth callout validates the user.
3. Auth callout returns a User JWT with explicit publish and subscribe permissions.
4. Your application records enough connection metadata to identify that user’s active NATS connections.
5. When the user’s permissions change, your application closes those connections.
6. The client reconnects.
7. Auth callout runs again and returns permissions based on the latest source of truth.

NATS provides a way to kick connections using a system-account server request. With the NATS CLI this is typically:

nats server request kick <client-id> <server-id>

You must be connected through the system account to perform this kind of server operation. The client ID and server ID identify which connection on which server should be closed; check nats server request kick --help for the exact arguments required by your installed CLI version and deployment topology.

When is reconnect-and-kick a good fit?

This pattern is often a good fit when:

• permission changes are relatively infrequent;
• clients already have reconnect logic;
• a brief reconnect is acceptable;
• your auth service can reliably map users to active connections;
• new permissions can be computed quickly on reconnect; and
• you want to avoid large or highly dynamic account JWTs.

What should you track to kick the right connections?

Track enough metadata to find and close active connections when authorization changes. In practice, teams commonly store connection identifiers, and sometimes the server identifier as well, in state owned by the auth service.

That state lets your application find the right active connections after a project membership, resource, or subject-level authorization change.

Is kicking a connection the same as banning a user?

No. Kicking a connection only closes the current connection. A normal NATS client may immediately try to reconnect.

Your auth callout service must make the authorization decision again on reconnect. If the user should no longer have access, the callout service must deny the connection or return permissions that no longer allow the removed subjects.

Option 2: should you use scoped signing keys for reloadable permission templates?

Use this pattern when permissions change frequently and you want to avoid intentionally reconnecting clients on each change.

In this model, auth callout still integrates with your external identity provider. The callout service validates the user, reads the relevant OAuth or application state, and issues a valid NATS User JWT. Instead of embedding a full per-connection permission map in every generated User JWT, the User JWT is signed by a scoped signing key whose permission template lives in the account configuration. When a User JWT is signed by a scoped signing key, the signing key’s permission template is applied, overriding any permissions embedded in the User JWT itself.

The useful property is that the permission template can be changed by updating the account JWT and propagating it to the server. That can allow permission changes to take effect without intentionally interrupting active clients.

Conceptually:

1. The account contains scoped signing keys with permission templates.
2. Auth callout authenticates the user and signs a valid User JWT using the appropriate scoped signing key.
3. The user connects normally.
4. When the user’s allowed subjects change, you update the relevant scoped signing key template in the account JWT.
5. You push the updated account JWT to the account resolver (for example with nsc push) so NATS picks up the new permission template.

This adds more moving parts than a pure reconnect-and-kick design, but it can be a better fit for high-churn authorization where frequent disconnects would be undesirable.

When are scoped signing keys a good fit?

Scoped signing keys are worth evaluating when:

• permissions change often while users are connected;
• avoiding reconnects is important;
• the number of distinct permission templates is manageable;
• your team is comfortable operating decentralized JWT auth; and
• account reloads fit your deployment workflow.

For a small or medium deployment, such as a few hundred active users with per-user or per-project subject permissions, scoped signing keys may be reasonable to evaluate. For larger systems, be careful with designs that require a separate signing key for every user, because account JWT size becomes part of the scaling limit.

Can auth callout and decentralized JWT auth be combined?

Yes. Auth callout is the mechanism that lets your service participate in authentication at connection time. Decentralized JWT auth is the model for operators, accounts, users, signing keys, and JWT-based authorization.

The callout service can create any valid NATS JWT that matches the deployment’s authentication model. That means it can use external identity information, such as an OAuth userinfo response, while still issuing NATS credentials compatible with operator-mode JWT authentication.

A practical learning path is:

1. Get familiar with operator, account, user, and signing key concepts using nsc.
2. Practice creating and editing accounts and signing keys from the command line.
3. Review an auth callout example in operator mode, such as the synadia-io/callout.go repository.
4. Implement the JWT creation logic in your callout service using an appropriate JWT library.

Operator mode generally provides more flexibility and a stronger operational model than putting all auth directly into static server configuration, but it also requires more setup.

How many scoped signing keys should you create?

For highly individualized live permission templates, one possible design is to create a scoped signing key per user. That lets each user’s permission template be updated independently.

This does not scale without limits. Signing keys are stored in the account JWT, and the account JWT should not grow much beyond a few megabytes in practice. As a rule of thumb from community guidance, this approach is more appropriate for hundreds or perhaps low thousands of users than for an unbounded population.

For very large user counts, the reconnect-and-kick pattern may be more practical unless you can group users into shared permission templates.

Can users share permission templates instead?

Yes, if your authorization model allows it. Grouping users by role, project, or resource group can reduce the number of scoped signing keys.

Shared templates make the scoped signing key model more scalable. Fully unique per-user templates provide fine-grained control, but increase account JWT size and operational complexity.

How should you choose between reconnecting and scoped signing keys?

Use generated User JWT permissions plus connection kicking when:

• permissions are straightforward to compute on each connection;
• reconnects are acceptable;
• permission changes are not extremely frequent;
• you have many users and want to avoid very large account JWTs; or
• you prefer a simpler operational design.

Use scoped signing keys when:

• permissions change often for connected users;
• avoiding reconnects is important;
• the number of distinct permission templates is manageable;
• you are comfortable operating decentralized JWT auth; and
• account reloads fit your deployment workflow.

What should you test before choosing a design?

Start by putting a number behind frequent permission changes. The best design depends on whether permissions change once in a while, several times per user session, or continuously as users create and remove resources.

Then decide whether access is truly per user, or whether it can be represented by shared roles, project-level templates, or resource groups. Shared templates can make scoped signing keys more scalable. Fully unique per-user templates provide fine-grained control, but increase account JWT size and operational complexity.

If you choose the reconnect model, make connection tracking part of the auth service design from the beginning. Store enough metadata to kick active connections when authorization changes, and make sure reconnect authorization is based on the latest source of truth.

If you choose the scoped signing key model, test the full lifecycle:

1. generate scoped signing keys in the account;
2. issue User JWTs from auth callout signed by those scoped signing keys;
3. update the permission templates on the relevant scoped signing keys;
4. push the updated account JWT to the resolver; and
5. verify that permissions change as expected without intentionally disconnecting clients.

Which pattern fits your use case?

Dynamic NATS permissions with auth callout are a tradeoff between simplicity and live authorization flexibility. Embedding full permissions in the generated User JWT is straightforward, but changes require reconnecting or kicking existing clients so auth callout can authorize them again. Combining auth callout with scoped signing keys can support reloadable permission templates, but adds decentralized JWT operational complexity and account JWT size considerations.

For frequent, fine-grained permission changes across a manageable number of users or templates, scoped signing keys are worth evaluating. For very large user populations or simpler permission lifecycles, tracking active connections and forcing reauthorization on reconnect may be the more practical design.

Want help from the NATS experts? Meet with our architects to get help tailored to your use case and environment.