Skip to main content
Version: 4.1 (2026 H2)

Single Sign-On (SSO)

primedocs signs users in automatically and without a login dialog whenever a valid Entra ID session already exists (the Windows / Microsoft 365 login on the workstation). This silent SSO works across all touchpoints — Desktop, Web and the Office / Teams add-ins — and consistently uses the primedocs IdentityServer (IdS) as a relay to Entra ID.

note

SSO is only meaningful — and only implemented — against Office 365 / Entra ID. On-premises installations without an Entra ID connection, personal Microsoft accounts (MSA) and Azure AD B2C scenarios are not supported.

How it works​

primedocs never talks to Entra ID directly; it always goes through the IdS. Two different mechanisms are used depending on the touchpoint:

TouchpointMechanismApp registration change required
Web (browser) and Desktop (WPF)OIDC redirect flow with prompt=none and login_hint against the existing Office 365 app registrationNo — the existing registration is sufficient
Office add-ins (Word, Excel, PowerPoint, Outlook) and TeamsMSAL.js Nested App Authentication (NAA): a silent Entra token from the Office host, exchanged for a primedocs sessionYes — see App registration for add-in SSO

Web and Desktop​

On start-up, the Web App and the Desktop client request a silent login from the IdS (prompt=none plus login_hint). If a valid Entra ID session already exists for the browser/host, it is reused transparently — no dialog, no click.

  • Web triggers the auto-login once per browser session, showing the FullLoadingPage while it runs.
  • Desktop resolves the UPN of the signed-in Windows user and passes it as login_hint; the silent login is triggered when the client transitions into the online-but-not-authenticated state.
  • If Entra ID cannot confirm the session without interaction (login_required, interaction_required, consent_required), primedocs falls back automatically and once to the interactive login — the user then sees the familiar, branded login page of their primedocs instance.

For the Desktop client, the automatic login is disabled by default. It is enabled via the SilentSsoAuthenticationTryOnStartup setting (MSI parameter SILENTSSOAUTHENTICATIONTRYONSTARTUP or registry value, default false); the timeout is controlled by SilentSsoAuthenticationTimeoutInSeconds (default 30 seconds). For details, GPO configuration and the prerequisites for on-premises Windows authentication, see Client installation.

This path requires no additional app registration configuration. It reuses the Office 365 registration and its redirect URIs as described in Entra ID Apps unchanged.

Office add-ins and Teams​

In embedded webviews (Office taskpane, Teams) the redirect-based silent SSO is unreliable, because embedded contexts have isolated cookie jars and restrict third-party cookies. Instead, MSAL.js Nested App Authentication (NAA) is used:

  1. The taskpane silently acquires an Entra access token from the Office / Teams host via MSAL NAA (createNestablePublicClientApplication) — first-party, with no popup and no redirect.
  2. The token is posted to the Web App (POST /api/Auth/OfficeSso, same origin as the taskpane).
  3. The Web App exchanges it at the IdS through a custom extension grant (urn:primedocs:oauth2:office-sso). The IdS validates the token (signature, audience, issuer, lifetime) and maps the claims via the PrimeDocsClaimer.
  4. The Web App issues its own first-party cookie → the user is signed in.

If any of these steps fails (missing configuration, consent required, user not mapped), the existing manual login button is shown transparently.

App registration for add-in SSO​

info

These changes apply only to add-in SSO (NAA). No app registration change is needed for Web and Desktop.

Add-in SSO extends the existing Office 365 app registration — the one whose clientId is configured in primedocs.config under <office365Auth> (see Entra ID Apps). No dedicated app is required.

Configure the following four items on this registration in the Entra admin center.

1. Authentication​

Add a Single-page application (SPA) platform and enter the following redirect URI — using the customer's primedocs Web App domain:

brk-multihub://<webapp-domain>

Example: brk-multihub://primedocs.customer.com

warning

A redirect URI in the form brk-multihub://<webapp-domain> is mandatory for NAA — the Office host acts as the broker. Without it, the silent token acquisition (acquireTokenSilent) fails. Use the customer's actual primedocs Web App domain (the same host as in the Application ID URI).

2. Expose an API​

SettingValue
Application ID URIapi://<webapp-domain>/<client-id> (e.g. api://primedocs.customer.com/2e9f66da-…)
ScopeAdd a delegated scope access_as_user (admin and user consent)

The host of the Application ID URI must match the add-in's source domain (the customer's primedocs Web App domain).

3. Authorized client applications​

So that getAccessToken does not trigger a separate consent dialog, pre-authorize the client IDs of the Microsoft Office / Teams hosts for the access_as_user scope:

HostClient ID
Office on the webea5a67f6-b6f3-4338-b240-c655ddc3cc8e
Microsoft 365 desktop/mobiled3590ed6-52b3-4102-aeff-aad2292ab01c
Outlook desktopd3590ed6-52b3-4102-aeff-aad2292ab01c
Outlook on the webbc59ab01-8403-45c6-8796-ac3ef710b3e3
Teams desktop/mobile1fec8e78-bce4-4aaf-ab1b-5451cc387264
Teams on the web5e3ce6c0-2b1f-4285-8d4b-75ee78787346
Microsoft 365 (new)0ec893e0-5785-4de6-99da-4ed124e5296c
note

Microsoft updates this list occasionally. If you run into problems, cross-check the current list in the Microsoft documentation on NAA.

4. API permissions​

Grant at least the following delegated permissions and give admin consent for the tenant:

  • openid
  • profile
  • User.Read
note

The SPA does not request access_as_user directly, but the scope <client-id>/.default. This relies on the statically configured, admin-consented permission set and avoids AADSTS65001 errors in tenants where user consent is restricted.

primedocs.config​

Add-in SSO uses the existing <office365Auth> configuration:

<providers>
  <office365Auth
    clientId="YOUR-CLIENT-ID"
    clientSecret="YOUR-CLIENT-SECRET"
    authority="https://login.microsoftonline.com/common/v2.0/"
    ... />
</providers>

clientId and authority are served to the SPA via GET /api/Auth/OfficeSsoConfig. The clientSecret is used by the IdS for the token exchange.

Behaviour and fallback​

  • On failure: if SSO fails, the familiar manual login button is shown — no error message, no popup.
  • Once per session: the silent login is attempted at most once per session (guard primedocs.autoLoginAttempted) to avoid redirect loops.
  • Logout is honoured: on logout, the short-lived marker cookie primedocs.suppressSilentSso is set. While it is present, the next login forces an interactive re-login (prompt=login) — so an explicit logout does not immediately trigger another auto-login.

Limitations​

  • Microsoft Graph: the add-ins' NAA path does not go through an OIDC auth code, so the delegated Microsoft Graph token store is not populated. Features that need a delegated Graph token for the user require a separate On-Behalf-Of exchange.
  • Conditional Access: the "Approved Client App" policy is incompatible with NAA from March 2026. Device- and location-based policies may still force interaction.
  • MFA: depending on the tenant policy, an MFA prompt may still be triggered despite SSO — this is an expected case and is handled via the interactive fallback.
  • iFrame: no auto-login takes place in an iFrame context.