109 lines
7.4 KiB
Markdown
109 lines
7.4 KiB
Markdown
# Operator access
|
||
|
||
Use a separate personal key for each human. Viewer reads protected evidence; operator can additionally
|
||
perform permitted operational actions and previews; administrator controls configuration apply,
|
||
credentials, destructive lifecycle and recovery. The API enforces every route's declared role.
|
||
Project `mfsvc_`, node `mfnode_` and enrollment keys never unlock the Console.
|
||
|
||
## Deployment-owned personal identities
|
||
|
||
In a private local terminal run:
|
||
|
||
```sh
|
||
python scripts/operator_identity.py --subject alice --role viewer --days 30
|
||
```
|
||
|
||
Save `one_time_key` in your password manager and give it only to that person through your approved
|
||
private channel. Add **only** `deployment_record` to the JSON array in `MODELFORGE_OPERATOR_IDENTITIES`.
|
||
The array must contain 1–100 records. A `.env` assignment uses single quotes around the JSON array.
|
||
Never put the complete command output in `.env`, Git, a ticket, an export or a release artifact.
|
||
The stored record contains a credential ID, subject, role, digest and timezone-aware expiry; it does
|
||
not contain the usable key. Configuration reads redact the entire registry.
|
||
|
||
Apply the deployment setting using the normal controlled API recreation procedure. On the next
|
||
request the API uses the new registry. Enter the personal key in the Console's Operator API key
|
||
field. Verify the displayed subject and role before acting. `GET /api/v1/operator/identity`, with
|
||
`X-ModelForge-Admin-Token` supplied from your private credential store, provides the same information.
|
||
There is no API for reading a key back.
|
||
|
||
## Deployment-owned rotation, revocation and recovery
|
||
|
||
Generate a replacement record with the same subject and role and a new credential ID. Add it alongside
|
||
the old record, recreate the API, and verify the replacement login and role. Remove the old record
|
||
and recreate the API again to end the overlap. The old key then receives 401. To revoke immediately,
|
||
remove the record and recreate the API without an overlap. Record the subject, credential IDs,
|
||
approver, reason and application time in the private deployment change record; never record keys.
|
||
These deployment operations do not currently produce online identity-lifecycle audit events.
|
||
|
||
Changes require recreation, not just editing the host environment. In-flight operations already
|
||
authorized may finish. The expiry itself is checked on every request without a restart. Retain an
|
||
independent administrator or controlled recovery credential during rotation. Conflicting roles for
|
||
one subject are rejected; change every overlapping record together when changing a role.
|
||
|
||
The legacy `MODELFORGE_OPERATOR_API_KEY` remains the `legacy-operator` administrator. Once a personal
|
||
administrator is proven, clear that setting and recreate the API to disable shared access. Production
|
||
startup refuses an installation without either a valid bootstrap key or an unexpired named admin.
|
||
Keep recovery material outside the database backup and protect it according to your deployment policy.
|
||
Managed database identities do not replace this independent startup/recovery requirement.
|
||
|
||
## Managed personal identities
|
||
|
||
The RC personal-key provider also supports online identity administration. An administrator can
|
||
list identity metadata, create a managed identity, rotate its key, change its role or enabled state,
|
||
and revoke its credentials. Deployment-owned entries remain read-only in this interface. Managed
|
||
subjects use `managed:<slug>` and keys use the distinct `mfopm_` namespace. Existing `mfop_`
|
||
deployment keys retain their authentication and recreation behavior.
|
||
|
||
Create the first managed identity as an administrator. Choose the minimum necessary role and a
|
||
key lifetime of 1–365 days. Issuance returns the key once; save it in an approved private credential
|
||
store before leaving the page. A lost response cannot be recovered from the database: rotate to
|
||
issue another key. Only a digest is persisted. Never paste the issuance response into a ticket,
|
||
audit reason, repository, configuration export or diagnostic bundle.
|
||
|
||
Rotation accepts an overlap of 0–900 seconds. Verify the replacement key promptly; zero overlap
|
||
invalidates the predecessor immediately. Revocation requires the exact canonical subject and a
|
||
reason. These mutations use the displayed version, recheck administrator authority, and record an
|
||
attributed audit event in the same transaction. A stale version requires refresh and a new review.
|
||
Once initialized, administration cannot remove the last currently usable managed administrator.
|
||
Expiry can still exhaust access later; maintain the independent deployment recovery authority.
|
||
|
||
The Console requires at least 120 seconds of overlap when rotating your own key, and at least
|
||
120 seconds remaining before both the current key expiry and local Console lock. Re-unlock first
|
||
if the local deadline is too close; use another administrator or the recovery authority when the
|
||
key itself is near expiry. The replacement is displayed for 60 seconds without a follow-up read
|
||
that could invalidate the issuance response. Save it, then lock and unlock with the replacement
|
||
before the overlap ends. Navigation, form changes and locking clear the displayed key.
|
||
|
||
The metadata endpoint is `GET /api/v1/operator/managed-identities`. Creation uses POST to that
|
||
collection; rotation and revocation use POST to `/{slug}/rotate` and `/{slug}/revoke`, and role or
|
||
enabled-state changes use PATCH to `/{slug}`. All require administrator authority. Keys never appear
|
||
in metadata, and a managed-key lookup failure cannot fall back to the deployment administrator.
|
||
|
||
## Managed keys after database recovery
|
||
|
||
Supported recovery restores the authoritative identity and credential history, then clears managed
|
||
credential activations during reconciliation. Validation independently checks that these current
|
||
activation rows are absent. A restored key is therefore quarantined even if the backup predates
|
||
its later revocation. Do not reopen access to a raw `pg_restore` result: use the complete isolated
|
||
ModelForge recovery workflow and its validation gate.
|
||
|
||
After validated recovery, authenticate using the independent deployment administrator and issue a
|
||
fresh managed administrator key by rotation or creation. Verify that new key before resuming
|
||
ordinary identity administration. Restored keys remain unusable; preserving their metadata is not
|
||
permission to reactivate them. Keep the restored environment isolated until these checks complete.
|
||
|
||
## Console locking and limitations
|
||
|
||
The Console displays identity, role, key expiry and its local lock time. It locks at the earlier of
|
||
fifteen minutes after unlock or key expiry. Lock console and reload both clear the memory-only key.
|
||
Public liveness and version remain visible while locked. A 403 keeps the session and reports a
|
||
forbidden operation; a database/service outage also keeps the key. A 401 clears it. No credential is
|
||
stored in cookies, localStorage, sessionStorage or a URL, and protected API responses are not cached.
|
||
|
||
The local lock is not a server-issued session or key revocation: a copied key remains usable until
|
||
its expiry or removal. OIDC/Authentik and SSO logout are not implemented; personal header keys are
|
||
the explicitly supported RC provider. Deployment-secret lifecycle is a separate feature.
|
||
Use HTTPS outside an explicitly trusted private lab, and protect the deployment
|
||
registry so an untrusted user cannot replace roles or credential digests. The full RC authentication
|
||
and secret-lifecycle acceptance remains open until those documented decisions and journeys close.
|