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

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. 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. Keinen JSON-Antwortkörper voraussetzen.
Das mitgegebene Token besteht die Validierung nicht	HTTP 401 mit einem JSON-Antwortkörper mit error: "invalid_token" und error_description. Die Beschreibung hängt vom Validierungsfehler ab und ist kein stabiler Fehlercode.

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 und invalid_token nicht gleichzeitig im Antwortheader und im Antwortkörper voraussetzen: Es handelt sich um unterschiedliche Antwortpfade.

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