This guide covers the settings of your workspace’s certificate authority (CA): how long certificates last, where they may be used, and how to replace the CA’s keys. If the word is new to you, read Certificates in plain words first.
Every workspace has exactly one CA. It is created with the workspace, with defaults that work, and it signs for every server. You only need this page when you want to change something. Changing the CA needs the admin role and a recent sign-in.
Open Certificate authority in the web app. Everything on this page is set there.
Pick a certificate lifetime
The CA has two lifetimes for user certificates:
- Default is what
nkgets when it asks for a certificate. - Longest allowed is the upper limit for anyone who asks for a different one.
nk renews certificates on its own right before ssh needs them, so a short lifetime costs your team nothing. Two things pull in different directions:
- Shorter limits how long a certificate is good for if it ever leaks, and how long removed access lingers on a daemon server that was offline.
- Longer keeps people working while the core is unreachable, since renewing needs the core.
A new value applies to certificates signed from then on. Certificates people already hold keep their old expiry.
Some certificates are kept shorter whatever the CA says: those of a service account, and those for a server without the daemon, which never hears about a removal.
Host certificates have a lifetime of their own. Daemons renew theirs on their own, so it rarely needs a change.
Limit where certificates work
The CA can hold a source list: the addresses or networks people may log in from, like your office or VPN. It goes on every certificate a person gets, the browser terminal included. The server refuses a login from anywhere else.
Service accounts don’t use this list. Each one has its own forced command and source list, so an office list never blocks a CI runner. See Automation and CI.
What a session may do on a server, like port or agent forwarding, is not a CA setting. For a server with the daemon, see Session rules. A server set up with nk sync follows its own sshd_config.
Roll over the CA
The CA’s keys don’t expire. They change only when you roll them over, like OpenSSH’s own CA keys. Do it when the keys may have leaked, for example after the core’s secret and a database backup got out.
A rollover replaces both keys at once, and nothing trusts the old ones after it. There is no grace period, because it would be one for whoever holds the old keys too.
What happens next:
- Servers with
nokkudtake the new keys at their next sync, which is quick, and close the sessions that started on the old ones. A login can fail in that short window. nknotices its certificates were signed by the old key and fetches new ones at the next connection. Nobody has to do anything.- Servers set up with
nk synckeep trusting only the old key. Nobody gets in there through Nokku until you runnk syncon each of them. The CA page lists the ones that still need it.
Have a way in that isn't Nokku
Run nk sync on every server without the daemon right after a rollover. If
you can’t reach one, you need another way in, like the console of your cloud
provider or a key that isn’t managed by Nokku.
Under the hood
- Its private keys are encrypted at rest, and the core decrypts them only to sign. A KMS keeps them safe at rest, not from a compromised core. That is what a rollover is for.
- A daemon renews its host certificate at the next sync after a rollover. Until then,
sshcan refuse it.