2026-09-02 01:05:41 +08:00
commit 04bac1f6e2
2200 changed files with 489415 additions and 0 deletions
@@ -0,0 +1,52 @@
---
title: "Create the first administrator"
description: "Securely claim a new private OpenWork deployment without enabling public signup."
---
A private deployment should start with public signup disabled. Configuring an email in the owner or platform-admin allowlist authorizes that identity after authentication; it does not create an account, choose a password, or generate a default administrator password.
Releases that include initial-administrator bootstrap provide a dedicated setup page at:
```text
https://<your-den-web-host>/setup
```
<Warning>
  Chart versions without `/setup` do not support this private bootstrap flow. Upgrade before attempting first-user setup. Entering an allowlisted email on the normal sign-in page cannot create a missing account.
</Warning>
## Before installing
1. Configure the initial administrator email as an eligible singleton-organization owner.
2. Add the same email to the platform-admin allowlist only if that person also needs deployment-wide `/admin` access.
3. Generate a unique one-time setup code.
4. Inject the code through a Kubernetes Secret or your platform's secret store as `DEN_INITIAL_ADMIN_BOOTSTRAP_CODE`, or mount it from a file and set `DEN_INITIAL_ADMIN_BOOTSTRAP_CODE_FILE`.
5. Keep public signup disabled.
The setup code is a plain secret string, not a hash or token generated by OpenWork. Never place the real setup code in a committed Helm values file, ConfigMap, container image, source-control file, support ticket, screenshot, logs, or PR.
## Complete setup
1. Wait until Den web, Den API, and the migration Job are healthy.
2. Open `/setup` on the Den web hostname.
3. Enter the configured administrator email and the one-time setup code.
4. Choose the administrator's name and password.
5. Confirm that OpenWork signs the administrator in and opens the singleton organization.
The setup flow uses the existing Better Auth password and session protections. Successful setup creates the first account, creates or claims the singleton organization, grants the configured owner and platform-admin roles, and makes setup unavailable because the deployment now has a user.
## Verify the boundary
After setup:
- revisiting `/setup` reports that setup is complete or unavailable;
- the one-time code cannot create another administrator;
- unknown users still cannot sign up;
- the administrator can sign out and use normal password sign-in;
- restarting or scaling Den API does not re-enable setup.
If the deployment already contains a user, bootstrap remains unavailable even if its setup Secret still exists. Rotating or restoring the Secret does not reopen setup unless an operator deliberately changes the database outside OpenWork.
## Configure SSO next
Use the first owner as a break-glass account, then configure SAML or OIDC SSO and SCIM for normal workforce access. Protect the break-glass identity and recovery material according to your organization's access-control policy.