Vocatis API 9.0
Diese Anleitung erforder technische Vorkenntnisse.
Erfordert iSign Version >= 9.0
Vocatis API 9.0 ist ein fest in Vocatis integrierter Mikroservice, welcher auch intern verwendet wird. Die URL ist abhängig vom System. In der Regel ist sie unter der Basisadresse des Servers mit dem Pfad “VocatisApi” erreichbar (z.B. https://designo.isigncloud.de/VocatisApi/ ).
Das Datenformat der API ist JSON.
Authentifizierung
Die API erfordert eine Authentifizierung mittels Bearer-Token (Access Token).
Authorization: Bearer eyJhbGciOiJSUzI1NiIsIn...
Das Token ist von einem iSign Identitätsanbieter zu beziehen. Der Nutzer oder der Client (für Skripte) muss hierfür bei iSign registriert sein und sich beim Identitätsanbieter identifizieren. Das erstellte Token enthält dann die notwendigen Autorisierungsinformationen.
Authorisierung
VocatisApi arbeitet Scope-basiert, das heißt, die im Token enthaltenen Scopes bestimmen die verwendbaren Endpunkte.
vocatisapi:super wird für die Statistik-Endpunkte verwendet (VocatisStatisticController).
vocatisapi:admin wird für die Terminverwaltung verwendet (VocatisAppointmentController).
Für alle anderen Endpunkte reicht vocatisapi:control.
Die Vocatis-Scopes sind verknüpft mit den Vocatis-Benutzerrollen.
| Scope | Verwendung |
|---|---|
vocatisapi:control | Allgemeiner Benutzerzugriff |
vocatisapi:admin | Administrativer Zugriff |
vocatisapi:super | Zugriff aus Superuser-Funktionen |
identity:user-profile | Abrufen von Benutzerprofilen |
Für das angehängte Beispielskript wird außerdem Zugriff auf die Identity-API benötigt (um Benutzerdaten auszulesen). Hierfür wird zusätzlich der Scope identity:user-profile verlangt.
Konfiguration
Auf dem iSign-Server müssen zunächst Client-Anmeldedaten erstellt werden. Dazu muss dieser Befehl vom Server-Administrator ausgeführt werden:
Die Angaben in spitzen Klammern (wie zB <client_id>) sind Platzhalter und müssen ALLE durch folgende Werte ersetzt werden:
client_id: Der Name für die Anwendung, die Zugriff bekommen soll (frei wählbar).
secret: Das Passwort für die Anwendung, die Zugriff bekommen soll (frei wählbar).
api-scope-domain: Für welche API soll der Scope gesetzt werden? Derzeit gibt es vocatisapi oder identity
scope-name: Der Name des benötigten Scopes.
Bei mehreren benötigten Scopes wird einfach der ganze Parameter --permission wiederholt.
Für das hier verlinkte Beispielskript sind die folgenden Scopes nötig:
--permission scp:vocatisapi:control --permission scp:identity:user-profile
issrvconfig identity default app add <client_id> --permission gt:client_credentials --permission ept:token --permission scp:<api-scope-domain>:<sope-name> --client-secret <secret> --policy GrantAllScopesPolicy
Endpunkte und Datentypen
Die Endpunkte und Datentypen können aus der VocatisApi-Spezifikation (OpenApi) herausgelesen werden.