Connected Services

Ein Connected Service ist ein konfigurierter externer Dienst, gegen den sich primedocs im Namen des Benutzers authentifiziert (z.B. via OAuth-Login). Statt Zugangsdaten in einzelnen Konfigurationen zu hinterlegen, referenzieren die Funktionen einen Connected Service über dessen ConnectedServiceKey. Die Anmeldung erfolgt einmal pro Benutzer und Dienst und wird anschliessend wiederverwendet.

Connected Services werden durch den Datasource-Administrator verwaltet (Name, Schlüssel, Endpunkte). Jeder Dienst hat einen eindeutigen Key, einen Anzeigenamen und einen benutzerbezogenen Anmeldestatus.

Konfiguration in der DataSourceAdminApp

Connected Services werden in der DataSourceAdminApp (Dashboard) unter Settings → Connected Services verwaltet. Pro Dienst werden folgende Angaben gepflegt:

Feld	Beschreibung
Name	Anzeigename des Dienstes.
Key	Eindeutiger Schlüssel, über den Funktionen den Dienst referenzieren (ConnectedServiceKey).
Description	Optionale Beschreibung.
Active	Aktiviert bzw. deaktiviert den Dienst.
Configuration	XML-Konfiguration des Dienstes (siehe OAuth-Konfiguration).

OAuth-Konfiguration

Die Configuration eines Connected Service ist ein <OAuth>-Element. Es unterstützt folgende Attribute:

Attribut	Pflicht	Beschreibung
authorizeUri	Ja	Autorisierungsendpunkt des externen Dienstes (Basis-URL für die Login-Weiterleitung).
tokenUri	Ja	Token-Endpunkt für den Austausch des Autorisierungscodes gegen ein Access-Token sowie für die Token-Erneuerung.
clientId	Ja	OAuth-Client- bzw. Anwendungs-ID.
clientSecret	Nein	OAuth-Client-Secret. Wird nur mitgesendet, wenn gesetzt (Public-/PKCE-Clients ohne Secret werden unterstützt).
scope	Nein	Angeforderte Scopes als durch Leerzeichen getrennte Zeichenkette (z.B. email openid profile People.Read).

Zusätzlich kann das <OAuth>-Element ein oder mehrere <UrlPattern>-Kindelemente enthalten. Ein UrlPattern ist ein URL-Muster (z.B. https://graph.microsoft.com/*), das festlegt, für welche ausgehenden Anfragen das Token dieses Dienstes verwendet wird.

<OAuth
  authorizeUri="https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize"
  tokenUri="https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token"
  clientId="00000000-0000-0000-0000-000000000000"
  clientSecret="…"
  scope="email openid profile People.Read">
    <UrlPattern>https://graph.microsoft.com/*</UrlPattern>
</OAuth>

hinweis

response_type=code, code_challenge_method=S256 (PKCE), redirect_uri und der state werden zur Laufzeit von primedocs erzeugt und sind keine Attribute des <OAuth>-Elements.

Funktionsweise (OAuth 2.0)

Connected Services nutzen den OAuth-2.0-Authorization-Code-Flow:

1. Eine Funktion (z.B. HttpDataProvider oder ein InvokeUrl-Command) referenziert einen Connected Service über ConnectedServiceKey.
2. Ist der Benutzer für diesen Dienst noch nicht angemeldet, leitet primedocs Web ihn zum Autorisierungsendpunkt des externen Dienstes weiter.
3. Nach erfolgreicher Anmeldung ruft der Dienst die Rücksprungadresse von primedocs auf, primedocs tauscht den Code gegen ein Access-Token und legt es pro Benutzer und Dienst serverseitig ab.
4. Bei späteren Aufrufen wird das gespeicherte Token automatisch wiederverwendet (bzw. erneuert).

Registrierung beim externen Dienst

Bei der Registrierung der primedocs-Anwendung im externen Dienst (z.B. als App-Registrierung) muss folgende Rücksprung-/Redirect-URI hinterlegt werden:

https://{instanz}/app/connectedservices/oauthcallback

Die URI ist fix pro Instanz (nicht pro Connected Service): Sie setzt sich zusammen aus der Basis-URL der primedocs Web App (üblicherweise https://{instanz}/app) und dem festen Pfad /connectedservices/oauthcallback. Genau dieser Wert wird zur Laufzeit als redirect_uri an den Autorisierungsendpunkt gesendet und muss beim externen Dienst exakt so hinterlegt sein.

Der OAuth-state transportiert dabei intern die Zuordnungsinformationen (angemeldeter Benutzer/Login, betroffener Connected Service und Datasource), damit primedocs den Rücksprung dem richtigen Kontext zuordnen kann.

hinweis

Nach der Verarbeitung des Rücksprungs leitet primedocs den Browser intern auf eine Statusseite (.../app/web/connectedservices/connectedservice-oauthcallback) weiter. Diese interne Weiterleitung ist nicht die beim externen Dienst zu registrierende Redirect-URI.

«Login erforderlich»

Greift eine Funktion auf einen Connected Service zu, für den der Benutzer noch nicht angemeldet ist, zeigt primedocs Web einen Anmelde-Banner an. Erst nach erfolgreicher Anmeldung wird die Aktion (z.B. Dokumentgenerierung oder Datenabruf) ausgeführt.

Verwendung

Ein Connected Service wird über das Attribut ConnectedServiceKey referenziert. Folgende Stellen unterstützen Connected Services:

Einsatzort	Beschreibung
InvokeUrl-Command	Authentifiziert die mehrstufigen HTTP-Aufrufe nach der Dokumentgenerierung.
HttpDataProvider	Authentifiziert den Datenabruf aus einer HTTP-/REST-API.
Connect Session / Connect Session Templates	Authentifiziert Initializer und InvokeUrl-Commands einer Session — die Ausführung (/Execute) erfolgt im Kontext des angemeldeten Benutzers.

<HttpDataProvider DisplayName="CRM" ConnectedServiceKey="Crm.OAuth">
  ...
</HttpDataProvider>

Zugriffstoken verwenden

Innerhalb einer Konfiguration, die einen Connected Service referenziert, kann das Access-Token über den Platzhalter {__ConnectedService.AccessToken__} eingesetzt werden — typischerweise im Authorization-Header. primedocs ersetzt den Platzhalter zur Laufzeit durch das gültige Token des angemeldeten Benutzers:

<HttpDataProvider DisplayName="CRM" ConnectedServiceKey="Crm.OAuth">
  <Configuration>
    <Step>
      <Request Method="Get">
        <Url>https://crm.example.com/api/contacts</Url>
        <Header Name="Authorization" Value="Bearer {__ConnectedService.AccessToken__}" />
      </Request>
    </Step>
  </Configuration>
</HttpDataProvider>

System-reservierte Dienste

Bestimmte Dienste sind vom System reserviert und tragen das Präfix _System. (in der Oberfläche mit einem «System»-Badge gekennzeichnet). Aktuell:

Key	Zweck
_System.MIP	Microsoft Information Protection — Abruf der Vertraulichkeitsbezeichnungen.
_System.MIP.Protection	MIP-Rechteschutz (Rights Management); Voraussetzung für EnableProtection der Dokumentfunktion MIP.