From 13276e71e630a3ce72c1dca438b3e7b8fd6517a5 Mon Sep 17 00:00:00 2001 From: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> Date: Wed, 30 Sep 2026 20:06:19 -0400 Subject: [PATCH] docs(fleet-manager): add operators and make a credential request in the web UI Two task pages for the web UI's credential flows: an admin requesting, completing, recording and denying operator certificates, and the anonymous page where a future operator makes their own key, key backup and CSR and later builds their PKCS#12. The web UI page's Operators section and login section link to them. Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> --- .../make-a-credential-request.md | 64 +++++++++++ .../fleet-manager/web-operator-credentials.md | 108 ++++++++++++++++++ docs/fleet-manager/web-ui.md | 11 +- sidebars.ts | 2 + 4 files changed, 181 insertions(+), 4 deletions(-) create mode 100644 docs/fleet-manager/make-a-credential-request.md create mode 100644 docs/fleet-manager/web-operator-credentials.md diff --git a/docs/fleet-manager/make-a-credential-request.md b/docs/fleet-manager/make-a-credential-request.md new file mode 100644 index 0000000..7dacdd4 --- /dev/null +++ b/docs/fleet-manager/make-a-credential-request.md @@ -0,0 +1,64 @@ +--- +title: "🙋 Make a credential request" +--- + +# 🙋 Make a credential request + +:::info[In flight] +This page is new in the web UI. Your admin needs a Fleet Manager that serves operator credential requests to file the CSR you make here. +::: + +This page covers one task: making your own Fleet Manager operator key and certificate signing request (CSR), then building your `.p12` file once your admin sends back the signed certificate. It is for someone who doesn't have an operator certificate yet. + +The **Make a credential request** page runs entirely in your browser. It needs no login and sends nothing anywhere: the key, its backup and the passphrase stay on your machine. Only the CSR goes to your admin, who files it as described in [Adding operators in the web UI](./web-operator-credentials.md). + +:::caution[Before you start] +You need the Fleet Manager's address, and the access level your admin agreed to give you: `viewer`, `operator` or `admin`. +::: + +## Make your key and CSR + +1. Open the Fleet Manager's address. Under **Log in**, select **No operator certificate yet? Make a credential request**. The page is at `/request-credential`. +2. Enter your **Full name**, your **Email** and the **Access level**. Your email becomes your certificate's common name. +3. Select **Make my key and CSR**. The browser makes a P-384 key and a CSR, then shows a generated passphrase and **Download key backup**. + + :::danger[The passphrase is shown once] + The passphrase appears only on this screen. Download the key backup (`fleetos--.key.pem`, your private key encrypted with that passphrase) and store the passphrase in a password manager before you go on. Without both, your key is lost and you have to start again. **Continue** stays disabled until you have downloaded the backup and ticked **I have saved the passphrase**. + ::: + +4. Select **Continue**. The page shows your **CSR**. Copy it, or download it as `fleetos--.csr`. +5. Send the CSR to your admin with your name and the level you need. Never send the key backup or the passphrase. + +:::tip[Expected output] +The CSR is a PEM block that begins `-----BEGIN CERTIFICATE REQUEST-----`. Its subject is `CN=`, and it asks for your level's profile. +::: + +## Build your PKCS#12 + +Your admin gets the CSR signed at the operator CA, records it, and sends you the signed certificate. You can build the `.p12` file on the same page, in any browser: + +1. Open `/request-credential` again and go to **2. Build your PKCS#12**. +2. Choose **Your key backup file**. +3. Paste **Your signed certificate (PEM)**. Optionally paste the **Operator CA certificate** your admin sent, to include it as the chain. +4. Enter the **Key backup passphrase** and select **Build my PKCS#12**. + +:::tip[Expected output] +The browser downloads `.p12`. It opens with the same passphrase as the key backup. +::: + +If the page says `The certificate does not match the key in this backup`, the certificate was signed from a different CSR. Check with your admin. If it says `The passphrase is wrong or the key file is damaged`, check the passphrase. + +You can build the same file with OpenSSL instead. It asks for the key backup passphrase, then for a passphrase for the `.p12` file: + +```bash +openssl pkcs12 -export -inkey fleetos--.key.pem -in .crt -certfile operator-ca.crt -name "FleetOS ()" -out .p12 +``` + +## Install it + +Install the `.p12` file in your browser's certificate store and log in, as in [Logging in](./web-ui.md#logging-in). Then keep the key backup somewhere safe, or delete it once the certificate is installed. + +## Where to go next + +- [The web UI](./web-ui.md): logging in and every page. +- [Adding operators in the web UI](./web-operator-credentials.md): what your admin does with your CSR. diff --git a/docs/fleet-manager/web-operator-credentials.md b/docs/fleet-manager/web-operator-credentials.md new file mode 100644 index 0000000..c3ce8ca --- /dev/null +++ b/docs/fleet-manager/web-operator-credentials.md @@ -0,0 +1,108 @@ +--- +title: "🪪 Adding operators in the web UI" +--- + +# 🪪 Adding operators in the web UI + +:::info[In flight] +These screens are new in the web UI and need a Fleet Manager that serves operator credential requests. An older manager refuses them. +::: + +This page covers one task: giving someone an operator certificate, and taking it away, from the web UI's **Operators** page. The Fleet Manager never signs operator certificates. Your external operator CA does (see [The operator CA and revocation](./operator-ca.md)). The web UI files a **credential request**, you get the request signed at the CA, and the web UI records the signed certificate. + +If the person who needs the certificate can make their own key, have them use [Make a credential request](./make-a-credential-request.md) and send you the CSR. Their key then never leaves their machine. + +:::caution[Before you start] +You need an `admin` operator certificate and a working login (see [Logging in](./web-ui.md#logging-in)). The manager needs an operator CA and `database_url`. You need someone who can sign at the operator CA, with the CA's OpenSSL config. +::: + +## What the Operators page shows + +The **Credentials** tab lists every operator certificate the manager knows: + +| Column | What it shows | +|---|---| +| **Holder** | The certificate's common name (the holder's email) and, when recorded, their name. | +| **Level** | `viewer`, `operator` or `admin`. | +| **Kind** | How the manager learned of it: `first_admin`, `requested`, `recorded`, `observed` (seen logging in, never recorded) or `legacy_node` (from a CryptOS node before operator CAs became external; it can't log in). | +| **Issuer** | The start of the operator CA's SHA-256 fingerprint. | +| **Denylisted** | `denylisted` when it is on the manager's denylist. | +| **CRL** | `CRL-revoked` when the operator CA's CRL lists it. | +| **Last seen** | When it last logged in, for credentials the manager has seen in use. | + +The **Pending requests** tab lists the requests waiting for a signed certificate, with who filed each one and when it expires. A request expires after 30 days. + +## Request a credential + +1. On **Operators**, select **Request credential…**. +2. Enter the holder's **Full name**, their **Email** and the **Access level**. The email becomes the certificate's common name. +3. Choose where the key is made, then select **Next**: + - **Make the key here**: this browser makes a P-384 key and a CSR. + - **Upload a CSR from the holder**: paste the holder's CSR or choose its file. Its subject must be exactly `CN=`. The web UI refuses a CSR for anyone else. +4. With **Make the key here**, the next screen shows a generated passphrase and **Download key backup**. The key backup is the private key, encrypted with that passphrase, saved as `fleetos--.key.pem`. + + :::danger[The passphrase is shown once] + The passphrase appears only on this screen, and the manager never sees it or the key. Download the key backup and store the passphrase in a password manager before you go on. Without both the key is lost, and the request has to start again. **Continue** stays disabled until you have downloaded the backup and ticked **I have saved the passphrase**. + ::: + + Hand the key backup and the passphrase to the holder over separate channels, or keep them until you complete the request. + +5. The request is filed. The screen shows the **CSR** (copy it, or download it as `fleetos--.csr`, the name the signing command reads), the **OpenSSL extension section** for the level, and the **Signing command**. + +:::tip[Expected output] +`Request filed for (). It expires