Authentication setup

Installation overview · Configure the services

Set AppSettings:AuthenticationService in the API to Local, Keycloak or Azure. Local accounts remain available with either external provider. Keep provider settings and secrets in protected API configuration, not UI settings. Deploy matching API and UI versions and verify the API before using the UI.

Local accounts

Set LocalAuthentication:SetupUri on the API to the public HTTPS UI address ending in /setup-account, for example https://backup.example.com/setup-account.
After the API has applied its database migrations, run the following from the deployed API directory using the API service identity and its normal protected configuration:
```
.\API.exe provision-local-superadmin --username initial-admin --display-name "Initial administrator"
```
Share the printed setup link securely with the intended administrator. It is a credential, works once and expires after one hour. Do not put it in logs or tickets.
Open the link, choose a password and sign in. Use Configuration → Users to invite other local users; invitations are not emailed automatically.

Keep a usable local SuperAdmin even when using an external provider. The provisioning command is for the initial administrator, not for resetting a password or promoting an existing user. See User profile and administration for invitations, recovery and daily use.

Local password policy is configured under LocalAuthentication:Password. LocalAuthentication:RequireTotp requires an authenticator for local accounts; external providers manage their own MFA. Users should save the one-time recovery codes displayed during enrollment.

Protect local account recovery

The API creates a DataProtection folder beside the application directories. Back up its complete keys directory and matching protection.pfx with its private key, plus its password if configured, as one protected recovery set. The API service identity needs permission to create the folder and use the key ring and certificate. Protect the backup and store it away from the host.

To restore, stop the API, restore the complete folder at the installation root, configure the PFX password if needed, grant the service identity access and restart the API. Losing the key ring or matching private key prevents recovery of local authenticator secrets and invalidates outstanding setup links. A damaged or missing certificate with an existing key ring prevents startup; restore the matching recovery set rather than generating a replacement. Hosts sharing local users must share the same durable key ring and certificate.

External providers

For Keycloak or Microsoft Entra ID, configure the provider on the API and register the fixed public callback URLs:

ExternalAuthentication:ApiCallbackUri: HTTPS API URL ending in /api/auth/oidc/callback, registered as the sign-in redirect.
ExternalAuthentication:UiCallbackUri: HTTPS UI URL ending in /external-signin/callback, registered as the post-logout redirect.

For Keycloak, configure Keycloak:Authority, Audience, ClientId and OidcClientSecret. The client ID identifies the client whose roles the API reads. Set OidcClientId only if a separate confidential client is used for interactive sign-in.

For Entra ID, configure AzureAd:Instance, TenantId, ClientId, ApiScope and OidcClientSecret. Expose the delegated API scope, grant it to the sign-in application, and set api.requestedAccessTokenVersion to 2 in the API application's manifest. Set OidcClientId only when using a separate web-client registration.

The legacy ClientSecret setting is supported if OidcClientSecret is blank. Without either secret, external interactive sign-in is unavailable. Remove old provider settings from UI overrides when upgrading.

Configure API role mappings to match the provider's roles. Keycloak roles must be client roles for Keycloak:ClientId; Entra roles must be present in the API access token. Use lowercase names in the mappings; for example, configure AppSettings:AuthenticationRoles:ViewerRoles for read-only access. External users need a mapped Viewer, User, Editor or Admin role; SuperAdmin is local-only. A disabled user must be re-enabled in OT Backup before signing in again.

API and UI session state is held in memory: restarting either service can require users to sign in again. Multi-instance deployments need shared protected state before scaling horizontally.