Authentifizierung

Die primedocs Web API verwendet OAuth 2.0 mit Bearer Tokens zur Authentifizierung. Clients müssen in der primedocs.config registriert sein, bevor sie Access Tokens anfordern können.

Übersicht

Die Authentifizierung erfolgt über den im primedocs enthaltenen Identity Server (IdS). Nach der Registrierung eines Clients kann dieser ein Access Token über den client_credentials Grant Type anfordern.

Das Access Token muss dann im Authorization-Header aller API-Aufrufe mitgegeben werden:

Authorization: Bearer <access_token>

Client-Registrierung

Um einen Client zu registrieren, muss ein Eintrag in der primedocs.config vorgenommen werden. Siehe primedocs.config für Details.

Token-Anfrage

Access Tokens werden vom Token-Endpunkt angefordert:

POST https://{instanz}/ids/connect/token

Der Request-Body muss folgendes enthalten:

• client_id: die registrierte Client-ID
• client_secret: das Client-Secret
• grant_type: muss client_credentials sein
• scope: der benötigte Scope (z.B. pd_AdminWebApi oder pd_ConnectWebApi)

API-Scopes

Scope	Beschreibung
pd_AdminWebApi	Zugriff auf die Admin API für administrative Operationen
pd_ConnectWebApi	Zugriff auf die Connect API und Connect Session API für die Dokumentgenerierung

Rollen für die Admin API

Für die Admin API genügt der Scope allein nicht: Jeder Bereich verlangt zusätzlich eine Rolle. Ein Client erhält seine Rollen über das Attribut roles seiner Registrierung in der primedocs.config, zum Beispiel roles="SysAdmin" oder roles="TemplateAdmin, SnippetAdmin". Ohne Attribut gelten die Standardrollen ohne SysAdmin und Developer. Welche Rolle welcher Bereich verlangt, steht unter Admin API: Rollen des API-Clients. Fehlt die Rolle, antwortet die API mit HTTP 403.

Ende-zu-Ende-Beispiel

1. Access Token anfordern (client_credentials-Grant am Token-Endpunkt):

POST https://{instanz}/ids/connect/token
Content-Type: application/x-www-form-urlencoded

client_id=CustomApiClient&client_secret=CustomClient_Secret_123&grant_type=client_credentials&scope=pd_ConnectWebApi

2. Beispiel-Antwort des Token-Endpunkts:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "pd_ConnectWebApi"
}

3. Access Token verwenden: Das access_token wird bei jedem API-Aufruf im Authorization-Header mitgegeben:

GET https://{instanz}/webapi/api/v3/{datasourceId}/Admin/Users?page=1&pageSize=10
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...

hinweis

Läuft ein Token ab (401 Unauthorized), wird über Schritt 1 einfach ein neues angefordert. Die Gültigkeitsdauer richtet sich nach der Konfiguration des Identity Servers.

Authentifizierungsfehler

Die folgenden Antworten gelten für die über den Identity Server geschützten Endpunkte der Admin API, Connect API und Connect Session API. Aufrufe ohne gültiges Access Token antworten mit HTTP 401 Unauthorized und einem Problem-Dokument mit code Unauthorized. SCIM-Endpunkte prüfen ihre Tokens separat und verwenden SCIM-Fehlerantworten. Bei der Fehlerbehandlung folgende Antworten unterscheiden:

Situation	Antwort
Kein Bearer Token mitgegeben	HTTP 401 mit einer Bearer-Challenge im Header WWW-Authenticate.
Das mitgegebene Token besteht die Validierung nicht	HTTP 401 mit dem Header WWW-Authenticate: Bearer error="invalid_token". Den Grund der Ablehnung nennt die Antwort nicht. Er steht unter der correlationId im Server-Log.
Der Identity Server ist für die Prüfung des Tokens nicht erreichbar	HTTP 503 mit code AuthenticationUnavailable. Das Token ist nicht ungültig. Den Aufruf später mit demselben Token wiederholen.

Zuerst den HTTP-Status auswerten. Bei einem abgelaufenen Token ein neues Token anfordern und den Aufruf damit wiederholen. Bei anderen Tokenfehlern Token und Authentifizierungskonfiguration prüfen. Nicht unbegrenzt mit demselben ungültigen Token wiederholen.

Beispiele

Vollständige PowerShell-Beispiele zur Anforderung und Verwendung von Access Tokens stehen auf den einzelnen API-Seiten:

• Admin API
• Connect API
• Connect Session API