Console sign-in

The console has three roles:

Role	May
Viewer	See the monitoring grid, nodes, configuration, alerts and reports. Change nothing.
History viewer	Also search the history, the dead letters, quarantine, reconciliation queue, AI jobs and HL7 messages, which hold patient names and IDs. Every search and opened study is written to the audit log.
Administrator	Change the configuration, drain and resume nodes, act on queues and dead letters. Administrators are history viewers too.

Choose how people sign in with Authentication: Windows, OpenIdConnect or Local.

Windows sign-in (the default on Windows)

Users are signed in with their Windows account, through Kerberos or NTLM; browsers do it without asking on intranet sites. Roles come from Windows groups or user names, ; separated:

• AdminGroups (default BUILTIN\Administrators), such as CONTOSO\PACS-Admins;
• ViewerGroups: empty means administrators only (never every user the domain signs in);
• OperatorGroups: people who run things without changing the configuration (drain, retry, resend, work the queues), such as a PACS team or a helpdesk; they may view too. Empty means administrators only;
• HistoryGroups: empty means administrators only.

The installer asks for them; they are kept under HKLM\SOFTWARE\Routes\Central. A change to someone’s groups takes effect at their next Windows sign-in.

On a server outside a domain, local accounts lose BUILTIN\Administrators when signing in over the network, so list the user by name (CENTRAL01\alice) as an administrator instead.

An identity provider (OpenID Connect)

The console can send users to Entra ID, Okta, Keycloak, ADFS or any OpenID Connect provider:

msiexec /i Routes.Central.msi /qn AUTHENTICATION=OpenIdConnect OIDCAUTHORITY="https://login.microsoftonline.com/<tenant>/v2.0" OIDCCLIENTID="<application ID>" OIDCCLIENTSECRET="<secret>" ADMINGROUPS="<admin group ID>" VIEWERGROUPS="<viewer group ID>" HISTORYGROUPS="<history group ID>"

• Register the console at the provider as a web application, with the redirect URI https://<server>:5080/signin-oidc (one for each name users open, or the load-balanced name) and the sign-out URI https://<server>:5080/signout-callback-oidc. Without a client secret it is used as a public client, with PKCE only, where the provider allows that.
• Roles come from the groups and roles claims of the ID token (OidcRoleClaims): the administrator, viewer and history settings then hold group IDs or names, or app roles, exactly as the provider sends them. In Entra ID, add the groups claim (or app roles) to the token in the app registration.
• The user’s name comes from preferred_username (OidcNameClaim), falling back to email, upn, name and sub.
• Sessions last 8 hours without use (OidcSessionHours), and 12 hours at most however busy (SessionMaxHours). Sign out in the console also signs out at the provider. Sessions are accepted by every central server sharing the database, so they can sit behind a load balancer.
• The client secret is stored in the registry next to the connection string, readable only by SYSTEM and Administrators.

Use HTTPS with a certificate browsers trust. Each sign-in is written to the audit log.

Local accounts (the default on Linux and Docker)

The central service keeps its own accounts, with hashed passwords and optional two-factor sign-in. It works on Windows too (Authentication=Local).

• The first administrator: on first start the service creates admin, with a random password in initial-admin-password.txt in its data folder (readable by the service only, never written to the log). Sign in with it and choose your own password.
• More accounts: under Configuration › Users. Each is a viewer, an operator (either with history access or without) or an administrator, and gets a temporary password to change at its first sign-in.
• Two-factor sign-in: anyone can set it up from Account with an authenticator app; Configuration › Settings can require it for everyone.
• Passkeys: anyone can add one under Account (the password is asked again), on a laptop, phone or security key. Sign in with a passkey then needs no user name, password or code: the device checks a PIN, fingerprint or face, so a passkey counts as two-factor sign-in too. Passkeys need the console to be opened over HTTPS (or on localhost), and a passkey works only at the address it was made at: use the same host name each time.
• Lockout: five wrong passwords or codes lock an account for 15 minutes (resetting its password lifts the lock); ten attempts a minute from one address are let through.
• Disabling an account or changing its password ends its sessions.

Scripts and the API

Everything the console does goes through the central service’s API, described at /openapi/v1.json (the API link in the console’s header). Scripts sign in the same way as the console, and send the header X-Routes-Console: 1 with every change.

Never in production: development mode

With ASPNETCORE_ENVIRONMENT=Development, the central service signs everyone in as an administrator without asking. It only starts that way when every address it listens on is local, but never set it on a real server.