Configuring OAuth / OIDC Authentication

udServer uses the OAuth 2.0 Authorization Code flow with OpenID Connect (OIDC) for all user authentication. There is no built-in username/password login — every user authenticates through a configured identity provider (IdP).

At least one provider must be registered before anyone can log in. Until one is configured, /_user/whoami will return "needsAuthProvider": true and the server portal will prompt for initial setup.

How It Works

The browser visits /_oauth/login?provider=<id> and is redirected to the IdP's authorisation endpoint.
After the user authenticates with the IdP, they are redirected back to {serverURL}/api/_oauth/redirect with an authorisation code.
udServer exchanges the code for tokens at the IdP's token endpoint, decodes the returned id_token (JWT), and reads the email and name claims.
If a user with that email address already exists they are logged in; otherwise a new account is created automatically.
A session cookie (apikey) is set and the browser is sent to the portal.

Prerequisites

You need an OAuth 2.0 / OIDC-compliant identity provider. Any provider that supports the Authorization Code flow and returns an id_token with email and name claims will work. Common choices include:

Microsoft Entra ID (formerly Azure AD)
Google Workspace
Okta
Keycloak
Auth0
Any OIDC-compliant provider

Registering an Application in Your IdP

Before adding a provider to udServer you must register udServer as an application (sometimes called a "client") in your IdP. The exact steps differ per IdP but you always need to configure:

Redirect URI

https://<your-udserver-hostname>/api/_oauth/redirect

The URI is case-sensitive and must match exactly, including the scheme (https://). If your server runs on a non-standard HTTPS port (e.g. 8443) include it:

https://<your-udserver-hostname>:8443/api/_oauth/redirect

The serverURL setting in udServer's configuration must resolve to the same base URL, because udServer constructs the redirect URI from it at runtime.

Required Scopes

Request (or ensure the application is permitted to receive) the following scopes:

openid
profile
email
offline_access

udServer requests all four during the authorisation redirect. If email or profile (which provides name) are not present in the returned id_token, user creation and login will fail.

Grant Type

The application must be configured for the Authorization Code grant type. Implicit flow is not supported.

Note the Following Values

After registering the application you will need:

Value	Where to find it
Client ID	Provided by the IdP after app registration
Client Secret	Generated during or after app registration
Authorisation Endpoint	From the IdP's OIDC discovery document (`authorization_endpoint`)
Token Endpoint	From the IdP's OIDC discovery document (`token_endpoint`)

Most IdPs publish a discovery document at https://<idp-domain>/.well-known/openid-configuration that lists both endpoints.

Provider Field Reference

Field	Description
`id`	Internal identifier used in API calls and login URLs. Lowercase, no spaces (e.g. `entra`, `google`). Minimum 3 characters.
`name`	Display name shown to users in the portal login screen (e.g. `Contoso Azure AD`). Minimum 3 characters.
`authendpoint`	Full URL of the IdP's authorisation endpoint
`tokenendpoint`	Full URL of the IdP's token endpoint
`client_id`	The client/application ID from the IdP
`client_secret`	The client secret from the IdP

First-Time Setup (Bootstrapping)

When no providers are configured the /_auth/providers/add endpoint is publicly accessible to avoid a chicken-and-egg problem where you cannot log in to configure login. Once the first provider is successfully added this bootstrap access closes permanently; subsequent providers require the Server Config Edit global permission.

Via the Portal

On first launch the udServer portal will detect that no auth provider is configured (needsAuthProvider: true) and present a setup form. Fill in the fields and submit.

Via the API

Send a POST to https://<your-udserver-hostname>/api/_auth/providers/add:

{
  "id": "entra",
  "name": "Contoso Azure AD",
  "authendpoint": "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize",
  "tokenendpoint": "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token",
  "client_id": "<application-client-id>",
  "client_secret": "<application-client-secret>"
}

On success the server returns { "success": true }. You can now log in at:

https://<your-udserver-hostname>/api/_oauth/login?provider=entra

Managing Providers (After Initial Setup)

All provider management after first setup requires the Server Config Edit global permission. Use an account that already has that permission (typically the first admin user created during initial setup).

List Providers

GET /api/_auth/providers/list

Without the Server Config Edit permission, only id and name are returned. With it, clientid, authendpoint, and tokenendpoint are also included (the client_secret is never returned).

Add Another Provider

POST /api/_auth/providers/add

Same body as the bootstrap call above.

Remove a Provider

POST /api/_auth/providers/remove

{ "id": "entra" }

Warning: If you remove the only configured provider, no one will be able to log in until the server is restarted.

Multiple Providers

Multiple providers are fully supported. Each must have a unique id. The portal login page will present a button for each configured provider. API clients specify which provider to use with the provider query parameter on /_oauth/login.

Provider-Specific Setup Notes

Microsoft Entra ID (Azure AD)

Register a new app in Entra ID > App registrations.
Under Authentication, add a platform of type Web and set the redirect URI.
Under Certificates & secrets, create a new client secret and note its value.
Under API permissions, ensure openid, profile, email, and offline_access delegated permissions are granted.
Find your endpoints under Endpoints in the app overview — or use the discovery document at:
```
https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration
```

Google Workspace

In Google Cloud Console, create an OAuth 2.0 client ID under APIs & Services > Credentials.
Set the application type to Web application and add the redirect URI.
Use the following endpoints:
- Auth: https://accounts.google.com/o/oauth2/v2/auth
- Token: https://oauth2.googleapis.com/token

Keycloak

Create a new client in the target realm with Client authentication enabled.
Set the Valid redirect URIs to include the udServer redirect URI.

Retrieve the endpoints from:

https://<keycloak-host>/realms/<realm>/.well-known/openid-configuration

Troubleshooting

Users are redirected to `/#error=oauthfailure`

This indicates the token exchange failed. Check that:

The tokenendpoint URL is correct.
The client_id and client_secret are correct and the secret has not expired.
The redirect URI registered in the IdP exactly matches {serverURL}/api/_oauth/redirect.
The serverURL configuration in udServer does not have a trailing slash and matches the scheme/host/port the browser used.

Users cannot log in but the OAuth flow completes

If the redirect completes but no session is established, check the server logs for oauthfailure or nosession. This can occur if:

The id_token returned by the IdP does not contain an email claim — ensure the email scope is granted.
The email claim is present but the account is deactivated in udServer.

`"message": "malformed"` on `/_auth/providers/add`

All six fields (id, name, authendpoint, tokenendpoint, client_id, client_secret) are required and must each be at least 3 characters long.

`"message": "notallowed"` on `/_auth/providers/add`

At least one provider is already configured and the request was made without a valid session that has the Server Config Edit global permission.

Setting up on an Amazon EC2 instance

Admin Console