# Principals

> How Nokku ties every certificate to one person, one server and the Linux accounts they were given there.

This page explains the one idea that makes Nokku's access model work. It builds on [Certificates in plain words](/docs/learn/certificates).

## Two questions, one answer

Every SSH login answers two questions:

1. **Who are you?** For example Alice, `alice@acme.com`.
2. **Which Linux account do you want?** For example `root` or `ubuntu`.

Plain OpenSSH usually writes only the second answer into a certificate: "the holder may log in as `ubuntu`". That certificate works on every server that trusts the CA, and it doesn't say which of five colleagues is holding it.

Nokku writes the whole answer down. A certificate is made for **one person on one server**. It lists the Linux accounts that person was given there, and nothing else. Alice's certificate for `web-01` says "Alice, on `web-01`, as `ubuntu`". It opens nothing on `db-01`.

## Accounts and principals

Two words come up here:

- An **account** is a Linux account on a server, like `ubuntu` on `web-01`. In the web app you give people access by **granting** them an account.
- A **principal** is an entry inside the certificate. OpenSSH reads them to decide who the holder is. Nokku writes one per granted account, and each one names the user, the server and the account.

## What the server checks at login

When Alice runs `ssh ubuntu@web-01`, the server checks:

1. **Is the certificate genuine?** Signed by the workspace CA, not expired.
2. **Is Alice allowed on `ubuntu` here?** The certificate must name Alice, this server and `ubuntu`. A server with `nokkud` also checks that entry against its own list for the `ubuntu` account.

```mermaid
flowchart LR
  login["Alice logs in<br>as ubuntu"] --> genuine{"Genuine and<br>not expired?"}
  genuine -- yes --> allowed{"Alice allowed<br>on ubuntu here?"}
  allowed -- yes --> shell["Shell as ubuntu"]
  genuine -- no --> deny["Denied"]
  allowed -- no --> deny
```

Both must pass. Neither check needs the core. The server works from the certificate, and with the daemon from a list it keeps locally.

## Access is checked twice

On a server with `nokkud`, a grant is looked at in two places:

- **When the certificate is signed.** The core only signs a certificate for a server you have a grant on, and only for the accounts you were granted.
- **At every login.** The server looks at its own list, which the core keeps up to date.

The list makes removing access immediate. The certificate covers a server that missed the change, and a server [without the daemon](/docs/servers/without-daemon), which has no list. [Revoking access](/docs/learn/certificates#revoking-access) has the details.

## Why this is so handy

- **A certificate opens one server.** A copy that leaks is useless everywhere else.
- **Shared accounts stay personal.** Five people can all use `ubuntu`, and every login still shows exactly who it was.
- **Teams just work.** Grant a team an account and every member is allowed. Nokku turns the team into its members, both in the server's list and when it signs.
- **Nothing for you to do.** `nk` gets the certificate for a server the first time you connect to it, and a new one when you're given another account there.
- **Nothing to rename.** The IDs of a user and a server never change, even if the email address or the server's name does.

**Under the hood**

- A certificate principal has the form `<user or service account ID>@<server ID>:<account>`. Only the core builds it. Servers compare it as a whole string and never take it apart.
- A certificate for a server without the daemon also carries `<server ID>:<account>`. That server's `sshd` accepts it through an `AuthorizedPrincipalsCommand` that names the server and the requested account. Who logged in is in the certificate's key ID, which `sshd` logs.
- Team IDs are never put into certificates. A team grant shows up as one entry per member.
- The core pushes a new list to daemons whenever a grant, a team or a member changes.
- The core signs nothing for a server whose daemon isn't approved.
- Removing a member, team or service account also removes all of its grants.
