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 Clients (Desktop, Web und den Office-/Teams-Add-Ins) und nutzt durchgehend den primedocs IdentityServer (IdS) als Relay zu Entra ID.

hinweis

Das hier beschriebene Silent SSO setzt eine Anbindung an Office 365 / Entra ID voraus und läuft in allen Clients über den IdS. Persönliche Microsoft-Konten (MSA) und Azure-AD-B2C-Szenarien werden nicht unterstützt.

Davon zu unterscheiden ist die On-Premises-Windows-Authentifizierung: Sie läuft ohne Entra ID über Windows/Negotiate am on-premises betriebenen Windows-Identity-Server. Ist sie konfiguriert, erscheint sie als zusätzliche Anmeldeoption auf der Anmeldeseite des IdS. Automatisch (also ohne Anmeldeseite) nutzt diesen Pfad nur der Desktop-Client, über die client-seitige Einstellung SilentSsoAuthenticationTryOnStartup (Konfiguration und Voraussetzungen siehe Client-Installation). Web und Office-Web-Add-Ins bieten keine automatische Windows-Anmeldung.

Funktionsweise

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

Client	Mechanismus	App-Registration-Anpassung nötig
Web (Browser) und Desktop (WPF)	OIDC-Redirect-Flow mit prompt=none und login_hint über die bestehende Office-365-App-Registration	Nein, die bestehende Registration genügt
Office-Add-Ins (Word, Excel, PowerPoint, Outlook) und Teams	MSAL.js Nested App Authentication (NAA): stiller Entra-Token aus dem Office-Host, eingetauscht gegen ein Zugriffstoken von primedocs	Ja, 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. Das Taskpane übergibt den Token an primedocs Web (gleicher Origin wie das Taskpane).
3. primedocs Web tauscht ihn beim IdS gegen Tokens von primedocs ein. Der IdS prüft den Token (Signatur, Audience, Issuer, Gültigkeit) und ordnet ihn dem Benutzer zu.
4. primedocs Web gibt die Tokens an das Taskpane zurück, und der Anwender ist angemeldet. Das Taskpane erneuert die Anmeldung danach selbst, mit denselben Laufzeiten wie primedocs Web im Browser (siehe Authentifizierung).

Verlangt Entra ID eine Zustimmung oder eine zusätzliche Anmeldung wie MFA, öffnet der Office- bzw. Teams-Host einmalig ein Anmeldefenster. Schlägt einer der Schritte fehl (fehlende Konfiguration, Anmeldefenster abgebrochen, Benutzer nicht zugeordnet), erscheint die gewohnte Schaltfläche für die manuelle Anmeldung.

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, 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 mit der primedocs-Web-App-Domain des Kunden eintragen:

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, denn 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, nur den Origin ohne Pfad.

2. Expose an API

Einstellung	Wert
Application ID URI	api://<client-id> (Entra-Standardwert nach Klick auf Set)
Scope	Delegierten Scope access_as_user hinzufügen (Admin- und Benutzer-Consent)

Die Add-Ins fordern einen Token auf diese App-Registration selbst an (Scope <client-id>/.default, siehe unten). Dafür muss die Registration eine API mit mindestens einem Scope exponieren. Die Application ID URI kann dabei den Standardwert behalten. Der IdS akzeptiert als Audience <client-id> und api://<client-id>. Weicht die Application ID URI davon ab, ist sie zusätzlich in der primedocs.config zu hinterlegen (siehe primedocs.config).

3. Authorized client applications

Die Client-IDs der Microsoft-Office-/Teams-Hosts für den Scope access_as_user vorautorisieren. Damit ist der Scope für die Office-Hosts, die den Token-Bezug vermitteln, ohne zusätzlichen Consent-Dialog freigegeben:

Host	Client ID
Office on the web	ea5a67f6-b6f3-4338-b240-c655ddc3cc8e
Microsoft 365 Desktop/Mobile	d3590ed6-52b3-4102-aeff-aad2292ab01c
Outlook Desktop	d3590ed6-52b3-4102-aeff-aad2292ab01c
Outlook on the web	bc59ab01-8403-45c6-8796-ac3ef710b3e3
Teams Desktop/Mobile	1fec8e78-bce4-4aaf-ab1b-5451cc387264
Teams on the web	5e3ce6c0-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, also einen Token auf die App-Registration selbst. 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.

Das optionale Attribut applicationIdUri wird nur gebraucht, wenn die App-Registration eine vom Standardwert api://<client-id> abweichende Application ID URI trägt. Dann diesen Wert eintragen, damit der IdS auch Tokens mit dieser Audience akzeptiert.

Verhalten und Fallback

• Fehlerfall: Schlägt SSO fehl, erscheint ohne Fehlermeldung die gewohnte Schaltfläche für die manuelle Anmeldung. In den Add-Ins öffnet der Host vorher nur dann ein Anmeldefenster, wenn Entra ID eine Zustimmung oder eine zusätzliche Anmeldung verlangt.
• Einmal pro Fenster: Der stille Login wird pro Browser-Tab bzw. Taskpane höchstens einmal versucht, um Endlosschleifen zu vermeiden.
• Logout wird respektiert: Der Logout widerruft die Tokens dieser Anmeldung beim IdS. Die Anmeldung beim IdS und bei Entra ID bleibt bestehen. Damit primedocs nicht sofort wieder automatisch anmeldet, erfolgt im Browser der nächste Login in den folgenden 10 Minuten interaktiv (prompt=login). In den Add-Ins unterbleibt die stille Anmeldung danach im selben Taskpane einmal.

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.

Weiterführende Links

• Entra ID Apps: Grundkonfiguration der Office-365-App-Registration
• Client-Installation: Silent-SSO-Einstellung des Desktop-Clients
• Office Web Add-In
• Microsoft Teams Add-In
• Anwendungsfälle: SharePoint, Teams, CMI