7.4 KiB
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:
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.