Skip to main content

Configure external sign-in and recovery

This page is for server operators. The public core supplies password login and an external-login extension interface. Provider implementations, including a company's OIDC provider, come from a separate plugin. Installing dtxWiki alone does not create a Google or company SSO button.

Configure an installed provider​

Install the trusted plugin in the same Python environment as the API, worker and CLI. Enable its dtxwiki.plugins entry point name, not merely the package name. This fictional example assumes company_login supplies company.oidc:

DTXWIKI_PLUGINS=company_login
DTXWIKI_AUTH_PROVIDERS_FILE=/etc/dtxwiki/auth-providers.toml
DTXWIKI_PUBLIC_BASE_URL=https://wiki.example.com
DTXWIKI_AUTH_PASSWORD_LOGIN_ENABLED=true
[[providers]]
slug = "company"
method = "company.oidc"
display_name = "Company SSO"
issuer = "https://idp.example.com/tenant"
client_id = "dtxwiki"
client_secret_ref = "file:/etc/dtxwiki/oidc-client-secret"
jit_provisioning = true
link_policy = "confirm"
trust_email_verified = false

Replace identifiers with values verified by your plugin and IdP. Keep the secret in a service-readable protected file; an env: secret reference is also supported. Register https://wiki.example.com/api/v1/auth/sso/company/callback as this example's redirect URI. The canonical URL requires HTTPS apart from loopback HTTP development in solo_local.

jit_provisioning defaults to false. The example explicitly enables it to allow a new account at first sign-in. With it off, an unknown user sees This provider does not allow account creation; create or link the account through the intended process. Account creation alone does not grant existing workspace access. A plugin's login hook can request memberships only within the operator's provisioning_workspace_roles allowlist: canonical workspace UUIDs map to permitted viewer or editor roles. This supports controlled provisioning, not arbitrary Owner grants, and existing roles are preserved. Without an authorized provisioning request, add membership separately.

Restart API and worker with the same plugin/provider/secret settings. Test new sign-in, linking an existing account, sign-out and sign-in again with fictional accounts.

Choose identity, email and network policy​

Accounts use a UUID and a verified (issuer, subject) identity and can exist without email, SMTP or a password. A profile address becomes the unique account email only when trust_email_verified=true and the IdP verifies it. Otherwise it does not reserve an account email.

A trusted email already registered to another account requires sign-in and explicit linking; accounts never merge automatically. For an unverified address collision, default email_collision_policy="admin_approval" lets the administrator decide Release the address or Keep the existing account under Settings → User accounts. Release deactivates the old account and revokes credentials while preserving data. "auto_release" requires trusted verified email and never releases a server-admin account automatically. The sign-in action This isn’t my account — ask a server admin uses a 10-minute ticket; an expired requester must sign in with the provider again.

allowed_email_domains requires trust_email_verified=true and an IdP-verified email. Optional company directory lookup requires directory_enabled=true, a validated directory_tenant, and a requesting Owner with that same provider/tenant identity. Verify UUIDs and trusted organization information; unverified profile addresses are not account-email member lookup keys.

The public OIDC helper requires explicit allow_private_network=true for a private-network IdP; the IdP URL still uses HTTPS. Plugin-specific environment fields use DTXWIKI_PLUGIN_<ENTRY_POINT_NAME>_<FIELD> and must be declared by that enabled plugin's settings model. Unknown fields or an unavailable entry point prevent startup. Consult the installed plugin for its declared field names instead of guessing them.

Preserve administration and recovery​

Before disabling password login, link and test an available provider for every required administrator. With password login off and no active provider, the server refuses to start. Grant server administration to an email-less active account with dtxwiki admin grant --user-id USER_UUID in the installation's maintenance environment. It does not grant workspace membership. Account → User ID → Copy user ID supplies the UUID.

Recent confirmation normally lasts 60 minutes and can be adjusted with DTXWIKI_AUTH_REAUTHENTICATION_MAX_AGE_SECONDS. Session renewal does not extend it. An emailed one-time confirmation expires in five minutes and is tied to the same browser and account/admin purpose; SSO confirmation is not proof of fresh IdP MFA.

For an email-less identity, recover the IdP account first. After independent ownership verification, the administrator uses Settings → User accounts → Reconnect SSO identity to rebind the existing user UUID. dtxwiki users rebind-identity --help describes the CLI alternative. Recovery retains UUID, data and roles while revoking sessions, pending confirmations and API/OAuth credentials. Block the old identity at the IdP when appropriate; removing a mapping alone does not prevent later just-in-time signup.

Account tools also cover retained deletion, restore, held-workspace administration and the Server audit log. Add account email and email confirmation need the relevant mail configuration; SMTP does not repair an unavailable sole IdP.

Sources: operator SSO configuration, provider defaults and allowlist, constrained provisioning, identity recovery, administrator labels.