Configure single sign-on

Erde always accepts local email-and-password sign-in. On top of that you can enable Windows single sign-on, OpenID Connect (OIDC) single sign-on — for example Microsoft Entra ID — or both. This guide covers what to set up on your side (the identity provider or Windows domain) and in Erde for each method. For the plain settings reference, see System settings → Authentication.

Before you start

• Role required: Administrator (System Settings is Administrator-only), plus access to your identity provider or Active Directory domain.
• Prerequisites: Erde is installed with first-run setup complete and is reachable over HTTPS at its public URL.

How sign-in works in Erde

A few things hold for every method — worth knowing before you start:

• Local password sign-in is always available. You can't turn it off; it is the fallback that keeps an installation from locking itself out. Windows and OIDC are added alongside it — see Manage your account for the local password each user still holds.
• One setting picks the external methods: ExternalAuth:Mode in Administration → System Settings → Authentication — None, Windows, Oidc, or Both. Enabling a method adds its button to the sign-in page, labeled by its Display Name setting.
• Accounts are never created automatically. For every method you create the Erde user first; single sign-on links an external identity to an existing account — it never provisions a new one. An unmatched identity is refused with "Your account has not been provisioned. Contact your administrator."
• The failed-attempt lockout (5 attempts, then 15 minutes) applies whichever method a user signs in with.

Set up OpenID Connect (OIDC / Entra ID)

There are two halves: register an application with your provider, then enter its details in Erde.

1. Register an application with your provider

The steps below name the Microsoft Entra ID controls; any OIDC provider (AD FS, Okta, and others) works the same way.

• Register a web application that uses the authorization code flow. Erde authenticates with a client secret, so this must be a confidential/web app — not a single-page or public client.

• Set the redirect URI (also called reply URL or callback URL) to your Erde public address followed by /signin-oidc:

  https://<your-erde-host>/signin-oidc

  It must exactly match the public HTTPS URL users reach Erde at (your Application:PublicBaseUrl). If Erde sits behind a reverse proxy, confirm that URL is set correctly — see Put Erde behind a reverse proxy for HTTPS — or the provider rejects the redirect.

• Ensure the app can request the scopes openid, profile, and email (Erde asks for these).

• Create a client secret and copy its value now — you paste it into Erde and won't be able to read it back from the provider later.

• Note three values: the Authority (issuer / discovery URL), the Application (client) ID, and the client secret.

  • Entra Authority: https://login.microsoftonline.com/<tenant-id>/v2.0.
  • Any provider that publishes <authority>/.well-known/openid-configuration is supported.

• Verified-email claim (Entra). Erde links a first-time SSO user to the Erde account with the same, verified email address. Entra does not send the standard email_verified claim — its equivalent is xms_edov. In the app registration's Token configuration, add the xms_edov optional claim so Entra asserts the address is verified. If your provider never asserts verification (for example AD FS), you'll turn on a trust toggle in Erde instead — see the next step.

2. Enter the details in Erde

1. Go to Administration → System Settings → Authentication and select Edit.

2. Set Mode to Oidc (OIDC only) or Both (OIDC and Windows).

3. Fill in the OIDC fields:

   Field	What to enter
   Provider URL (Authority)	The discovery/issuer URL — must be https. Entra: https://login.microsoftonline.com/<tenant-id>/v2.0
   Client ID	The application (client) ID from the registration
   Client Secret	The secret value you copied. Stored encrypted and write-only — it shows Configured afterward, never the value
   Display Name	The sign-in-page button label (default Corporate SSO)
   Trust email addresses the provider has not marked as verified	Leave off when your provider sends a verification claim (email_verified or xms_edov). Turn on only for providers that never do — AD FS, or Entra without the xms_edov claim

4. Select Save.

5. Restart the Erde server. The Authority, Client ID, and Client Secret bind at startup, so they take effect only after a restart — the Authentication panel shows a restart-required banner until you do. (Mode, Display Name, and the trust toggle apply immediately, no restart needed.)

3. Provision and test

Create each Erde user with the email address the provider will send (see Manage users and roles). On their first SSO sign-in Erde matches that email — verified per the rule above — and links the accounts permanently.

To test, open the sign-in page, select your OIDC button (its Display Name), and complete sign-in at the provider; you should return already signed in.

Set up Windows single sign-on

Windows SSO authenticates users by their domain account over Kerberos/NTLM — no passwords and no provider registration, but it requires a Windows domain.

1. Confirm the prerequisites

• The Erde server and the users' computers are joined to the same Active Directory domain (or trusted domains). Windows SSO relies on Kerberos/NTLM and is not available for off-domain clients. (A workgroup install can still match a local MACHINE\username, but there is no domain-wide SSO.)
• Erde runs on a supported host — the Windows Service (Kestrel) or IIS shape both work. You do not need to enable the IIS site's own Windows Authentication feature: Erde's built-in Negotiate handler performs the challenge itself.
• For seamless (no-prompt) sign-in, users' browsers must be allowed to send Windows credentials to the Erde site. On domain networks this usually means adding the site to the Local Intranet zone (Edge and Chrome follow Windows Internet settings; Firefox needs the site in network.negotiate-auth.trusted-uris). Without it, the browser prompts for Windows credentials rather than signing in silently.

2. Enable it in Erde

1. Go to Administration → System Settings → Authentication and select Edit.
2. Set Mode to Windows or Both.
3. (Optional) Set the Display Name for the Windows sign-in button (default Windows Sign-in).
4. Select Save. Windows sign-in has no secrets to bind, so it takes effect without a restart.

3. Provision and test

For each user, set their Windows Logon Name to their down-level domain account — DOMAIN\username (for example CONTOSO\jdoe) — on the Erde account; see Manage users and roles → Windows single sign-on. Matching is case-insensitive, one logon name per account, and accounts are never created automatically. If a Windows user is refused with "Your account has not been provisioned," the exact logon name they tried is recorded in the audit log — copy it onto their account.

To test, open the sign-in page and select the Windows button; a domain user on a trusted browser returns signed in.

Result

The sign-in page shows local email and password plus a button for each enabled method. Users sign in with their organization identity, which Erde links to the account you provisioned, and local sign-in stays available as a fallback for everyone.

Troubleshooting

Symptom	Cause	Resolution
OIDC sign-in fails right after saving the settings	Authority, Client ID, or Client Secret changed but the server hasn't restarted	Restart the Erde server; the Authentication panel shows a restart-required banner until you do
Provider reports a redirect-URI mismatch	The registered redirect URI doesn't exactly match https://<host>/signin-oidc	Register the exact public HTTPS URL plus /signin-oidc; behind a proxy, confirm Application:PublicBaseUrl is the public URL (see reverse proxy)
First OIDC sign-in refused: "not provisioned"	No Erde account has that email, or the provider didn't assert the email is verified	Create the user with the exact email; make the provider send email_verified/xms_edov, or enable Trust email addresses the provider has not marked as verified
OIDC returns to the sign-in page with an SSO error	The user cancelled at the provider, or the provider returned an error	Retry; check the provider-side registration (scopes granted, secret still valid)
Windows sign-in prompts for credentials every time	The browser isn't configured to send Windows credentials to the site	Add the Erde site to the Local Intranet zone (Edge/Chrome) or network.negotiate-auth.trusted-uris (Firefox)
Windows user refused: "not provisioned"	The account has no Windows Logon Name, or it doesn't match the account they signed in with	Set Windows Logon Name to the DOMAIN\username shown in the audit log for the failed attempt
A method's button doesn't appear on the sign-in page	Mode doesn't include that method	Set Mode to the method (or Both) in System Settings → Authentication

Related

• System settings → Authentication — the full settings reference.
• Manage users and roles — provisioning users and the Windows Logon Name field.
• Manage your account — the local password each user keeps as a fallback.
• Put Erde behind a reverse proxy for HTTPS — getting the public URL right so OIDC redirects match.