Zum Hauptinhalt springen
Version: 4.1 (2026 H2)

Single Sign-On (SSO)

primedocs meldet Anwender automatisch und ohne Login-Dialog an, sofern bereits eine gültige Entra-ID-Sitzung besteht (Windows-/Microsoft-365-Login am Arbeitsplatz). Dieses Silent SSO funktioniert in allen Touchpoints — Desktop, Web und den Office-/Teams-Add-Ins — und nutzt durchgehend den primedocs IdentityServer (IdS) als Relay zu Entra ID.

hinweis

SSO ist ausschliesslich gegen Office 365 / Entra ID sinnvoll und implementiert. On-Prem-Installationen ohne Entra-ID-Anbindung sowie persönliche Microsoft-Konten (MSA) und Azure-AD-B2C-Szenarien werden nicht unterstützt.

Funktionsweise​

primedocs spricht Entra ID nie direkt an, sondern immer über den IdS. Je nach Touchpoint kommen zwei unterschiedliche Mechanismen zum Einsatz:

TouchpointMechanismusApp-Registration-Anpassung nötig
Web (Browser) und Desktop (WPF)OIDC-Redirect-Flow mit prompt=none und login_hint über die bestehende Office-365-App-RegistrationNein — die bestehende Registration genügt
Office-Add-Ins (Word, Excel, PowerPoint, Outlook) und TeamsMSAL.js Nested App Authentication (NAA): stiller Entra-Token aus dem Office-Host, eingetauscht gegen eine primedocs-SessionJa — siehe App Registration für Add-In-SSO

Web und Desktop​

Beim Start fordert die Web-App bzw. der Desktop-Client beim IdS einen stillen Login an (prompt=none plus login_hint). Besteht beim Browser/Host bereits eine Entra-ID-Sitzung, wird diese transparent wiederverwendet — kein Dialog, kein Klick.

  • Web löst den Auto-Login einmal pro Browser-Session aus, während der FullLoadingPage angezeigt wird.
  • Desktop ermittelt die UPN des angemeldeten Windows-Benutzers und übergibt sie als login_hint; der stille Login wird beim Übergang in den nicht-authentifizierten Online-Zustand ausgelöst.
  • Kann Entra ID die Sitzung nicht ohne Interaktion bestätigen (login_required, interaction_required, consent_required), fällt primedocs automatisch und einmalig auf den interaktiven Login zurück — der Anwender sieht dann die gewohnte, gebrandete Login-Seite seiner primedocs-Instanz.

Beim Desktop-Client ist der automatische Login standardmässig deaktiviert. Er wird über die Einstellung SilentSsoAuthenticationTryOnStartup aktiviert (MSI-Parameter SILENTSSOAUTHENTICATIONTRYONSTARTUP bzw. Registry-Wert, Standard false); das Timeout steuert SilentSsoAuthenticationTimeoutInSeconds (Standard 30 Sekunden). Details, GPO-Konfiguration und Voraussetzungen für die On-Premises-Windows-Authentifizierung unter Client-Installation.

Dieser Pfad benötigt keine zusätzliche App-Registration-Konfiguration. Er nutzt die in Entra ID Apps beschriebene Office-365-Registration und deren Redirect-URIs unverändert weiter.

Office-Add-Ins und Teams​

In eingebetteten Webviews (Office-Taskpane, Teams) ist der redirect-basierte Silent SSO unzuverlässig, weil eingebettete Kontexte isolierte Cookie-Jars haben und Drittanbieter-Cookies einschränken. Stattdessen kommt MSAL.js Nested App Authentication (NAA) zum Einsatz:

  1. Das Taskpane bezieht über MSAL NAA (createNestablePublicClientApplication) still einen Entra-Access-Token aus dem Office-/Teams-Host — first-party, ohne Popup und ohne Redirect.
  2. Der Token wird an die Web-App gepostet (POST /api/Auth/OfficeSso, gleicher Origin wie das Taskpane).
  3. Die Web-App tauscht ihn beim IdS über einen Custom Extension Grant (urn:primedocs:oauth2:office-sso) ein. Der IdS validiert den Token (Signatur, Audience, Issuer, Gültigkeit) und mappt die Claims über den PrimeDocsClaimer.
  4. Die Web-App stellt ein eigenes First-Party-Cookie aus → der Anwender ist angemeldet.

Schlägt einer dieser Schritte fehl (fehlende Konfiguration, Consent erforderlich, Benutzer nicht zugeordnet), wird transparent der bestehende manuelle Login-Button angezeigt.

App Registration für Add-In-SSO​

info

Diese Anpassungen betreffen ausschliesslich das Add-In-SSO (NAA). Für Web und Desktop ist keine Änderung an der App Registration nötig.

Das Add-In-SSO erweitert die bestehende Office-365-App-Registration — jene Registration, deren clientId in der primedocs.config unter <office365Auth> hinterlegt ist (siehe Entra ID Apps). Es wird keine dedizierte App benötigt.

Im Entra Admin Center an dieser Registration die folgenden vier Punkte konfigurieren.

1. Authentication​

Eine Plattform Single-page application (SPA) hinzufügen und folgende Redirect-URI eintragen — mit der primedocs-Web-App-Domain des Kunden:

brk-multihub://<webapp-domain>

Beispiel: brk-multihub://primedocs.kunde.com

warnung

Die Redirect-URI im Schema brk-multihub://<webapp-domain> ist für NAA zwingend — der Office-Host agiert als Broker. Ohne sie schlägt der stille Token-Bezug (acquireTokenSilent) fehl. Als Domain die tatsächliche primedocs-Web-App-Domain des Kunden eintragen (derselbe Host wie in der Application ID URI).

2. Expose an API​

EinstellungWert
Application ID URIapi://<webapp-domain>/<client-id> (z. B. api://primedocs.kunde.com/2e9f66da-…)
ScopeDelegierten Scope access_as_user hinzufügen (Admin- und Benutzer-Consent)

Der Host der Application ID URI muss der Quelldomain des Add-Ins entsprechen (die primedocs-Web-App-Domain des Kunden).

3. Authorized client applications​

Damit getAccessToken keinen separaten Consent-Dialog auslöst, die Client-IDs der Microsoft-Office-/Teams-Hosts für den Scope access_as_user vorautorisieren:

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
hinweis

Microsoft aktualisiert diese Liste gelegentlich. Bei Problemen die aktuelle Liste in der Microsoft-Dokumentation zu NAA gegenprüfen.

4. API Permissions​

Mindestens die folgenden delegierten Berechtigungen vergeben und Admin-Consent für den Tenant erteilen:

  • openid
  • profile
  • User.Read
hinweis

Die SPA fordert nicht access_as_user direkt an, sondern den Scope <client-id>/.default. Das stützt sich auf den statisch konfigurierten, admin-bewilligten Berechtigungssatz und vermeidet AADSTS65001-Fehler in Tenants, in denen der Benutzer-Consent eingeschränkt ist.

primedocs.config​

Das Add-In-SSO nutzt die bestehende <office365Auth>-Konfiguration:

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

clientId und authority werden der SPA über GET /api/Auth/OfficeSsoConfig bereitgestellt. Das clientSecret wird vom IdS für den Token-Eintausch verwendet.

Verhalten und Fallback​

  • Fehlerfall: Schlägt SSO fehl, wird ohne Fehlermeldung und ohne Popup der gewohnte manuelle Login-Button angezeigt.
  • Einmal pro Session: Der stille Login wird pro Sitzung höchstens einmal versucht (Guard primedocs.autoLoginAttempted), um Endlosschleifen zu vermeiden.
  • Logout wird respektiert: Beim Logout wird das kurzlebige Marker-Cookie primedocs.suppressSilentSso gesetzt. Solange es vorhanden ist, erzwingt der nächste Login einen interaktiven Re-Login (prompt=login) — ein expliziter Logout führt also nicht sofort zum erneuten Auto-Login.

Einschränkungen​

  • Microsoft Graph: Der NAA-Pfad der Add-Ins durchläuft keinen OIDC-Auth-Code, daher wird der delegierte Microsoft-Graph-Token-Store nicht befüllt. Features, die einen delegierten Graph-Token des Benutzers benötigen, erfordern einen separaten On-Behalf-Of-Austausch.
  • Conditional Access: Die «Approved Client App»-Policy ist ab März 2026 mit NAA inkompatibel. Geräte-/standortbasierte Policies können weiterhin eine Interaktion erzwingen.
  • MFA: Je nach Tenant-Policy kann trotz SSO eine MFA-Abfrage ausgelöst werden — das ist ein erwarteter Fall und wird über den interaktiven Fallback abgewickelt.
  • iFrame: Im iFrame-Kontext findet kein Auto-Login statt.