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 clients (Desktop, Web and the Office / Teams add-ins) and consistently uses the primedocs IdentityServer (IdS) as a relay to Entra ID.

note

The silent SSO described here requires a connection to Office 365 / Entra ID and runs through the IdS across all clients. Personal Microsoft accounts (MSA) and Azure AD B2C scenarios are not supported.

Separate from this is on-premises Windows authentication: it runs without Entra ID via Windows/Negotiate against the on-premises Windows Identity Server. Where it is configured, it appears as an additional sign-in option on the IdS login page. Only the Desktop client uses this path automatically (that is, without a login page) via the client-side SilentSsoAuthenticationTryOnStartup setting (for configuration and prerequisites, see Client installation). Web and Office web add-ins offer no automatic Windows sign-in.

How it works​

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

ClientMechanismApp 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 with 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 because the Office host acts as the broker. Without it, the silent token acquisition (acquireTokenSilent) fails. Use the customer's actual primedocs Web App domain, origin only, without a path.

2. Expose an API​

SettingValue
Application ID URIapi://<client-id> (the Entra default after clicking Set)
ScopeAdd a delegated scope access_as_user (admin and user consent)

The add-ins request a token for this app registration itself (scope <client-id>/.default, see below). The registration therefore has to expose an API with at least one scope. The Application ID URI can keep its default value. The IdS accepts <client-id> and api://<client-id> as audience. If the Application ID URI deviates from this, it must additionally be configured in primedocs.config (see primedocs.config).

3. Authorized client applications​

Pre-authorize the client IDs of the Microsoft Office / Teams hosts for the access_as_user scope. This releases the scope for the Office hosts that broker the token acquisition without an additional consent dialog:

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, i.e. a token for the app registration itself. 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.

The optional applicationIdUri attribute is only needed if the app registration carries an Application ID URI that deviates from the default api://<client-id>. In that case, enter that value so that the IdS also accepts tokens with this audience.

Behaviour and fallback​

  • On failure: if SSO fails, the familiar manual login button is shown without an error message or 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.