Manage Access

Access is granted by assigning a subject to a principal on a target.

A subject is a user, team, or service account.
A target is a registered server or resource.
A principal is a Linux username on that target, such as root, ubuntu, or deploy.

Assign access

Select a target and its required Linux principal.
Add the users, teams, or service accounts that should use that principal.
Have the subject refresh nk state and connect with the same Linux username.

For example, assigning a team to ubuntu on web-01 allows members of that team to run:

ssh ubuntu@web-01

What the certificate contains

The SSH certificate principal is the Nokku user’s stable UUID, not the requested Linux username. The server checks both:

The certificate is valid and signed by the trusted SSH CA.
The certificate principal is authorized for the requested Linux username.

This allows multiple people to use root while keeping their Nokku identities distinct.

Daemon-managed targets

For a daemon-managed target, assignments are synchronized to the daemon’s local cache over the control stream. The login check reads that cache locally.

If the core or control stream is unavailable, the target uses the last synchronized assignments. A recent access change therefore cannot be applied until the daemon reconnects.

Manual targets

For a manual target, update the relevant file under /etc/ssh/auth_principals/ after changing an assignment. The core does not edit that file for you.

Teams

Use teams when several people need the same access. Assign the team to a principal once, then manage membership in the team rather than editing every target assignment.

Service accounts

Use service accounts for automation. Assign them to principals like users and provide their token to nk through NK_TOKEN.

Removing access

Remove the subject from the principal, or remove the subject from the workspace or team. This changes future authorization and certificate issuance. An already-issued SSH certificate remains cryptographically valid until its expiry; access behavior also depends on when the target receives the updated assignment.