Integrations with VBG BG UF throw REST APIs

1) Einleitung

Die bei der Verwaltungs-Berufsgenossenschaft (VBG) eingerichtete Qualitätssicherungsstelle Erste-Hilfe (QSEH) ist für die „Ermächtigung von Stellen für die Aus- und Fortbildung in der Ersten Hilfe“ zuständig. Die jeweiligen Ausbildungsbetriebe müssen geplante und durchge- führte Lehrgänge melden. Hierfür steht unter https://meine.bg-qseh.de/Lehrgang eine Web- oberfläche zur Verfügung. Für eine automatische Meldung an die QSEH aus externen Lehr- gangsverwaltungssystemen steht zusätzlich eine Schnittstelle zur Verfügung, die in diesem Dokument beschrieben wird.

---

2) Authentifizierung

Alle nicht allgemeingültigen Endpunkte der Schnittstelle erfordern eine Authentifizierung des Aufrufers mit den Anmeldedaten eines Unterkontos. In diesem Kapitel wird zunächst die initiale Einrichtung beschrieben, bis ab einschließlich Abschnitt 2.4 die technischen Schritte erläutert werden.
Falls Sie noch über Zugangsdaten der alten SOAP-Schnittstelle verfügen: Diese können nicht mit der in dieser Dokumentation beschriebenen Schnittstelle verwendet werden.

2.1) Haupt- und Unterkonten

Jede ermächtigte Stelle verfügt über ein Hauptkonto, welches sie für die Selbstverwaltung unter meine.bg-qseh.de („meineQSEH“) verwendet und das über umfangreiche Berechtigun- gen verfügt. Ein solches Konto kann nicht für die Kommunikation mit der Schnittstelle verwen- det werden. Stattdessen muss mit dem Hauptkonto ein Unterkonto erstellt werden.
Falls Sie über Zugangsdaten für ein Konto verfügen und nicht sicher sind, ob es ein Haupt- oder Unterkonto ist, melden Sie sich mit den Daten bei meineQSEH an. Wenn im „Mein Konto“-Bereich der Navigationspunkt „Unterkonten verwalten“ angezeigt wird (oder über diesen Direktlink zugänglich ist), handelt es sich um ein Hauptkonto, weil Unterkonten nicht erneut Un- terkonten anlegen dürfen.

Falls Sie als separater Dienstleister für eine ermächtigte Stelle tätig sind und die Zugangsdaten für das Hauptkonto erhalten haben sollten, empfehlen wir Ihnen, diese zu löschen, sowie die ermächtigte Stelle zu einem Passwortwechsel und der Anlage eines Unterkontos aufzufordern. Mit einem Hauptkonto sind Aktionen mit weitreichenden Konsequenzen möglich, die nur einem begrenzten Personenkreis zugänglich sein sollten.

2.2) Unterkonto erstellen

Dieser Teilschritt kann nur mit einem Hauptkonto durchgeführt werden. Als solches angemel- det können im in Abbildung 3 gezeigten „Unterkonten verwalten“-Bereich neue Unterkonten erstellt und bestehende bearbeitet werden. Letzteres schließt die Änderung der Kontoinforma- tionen, das Zurücksetzen des Passworts, die Neuzuweisung von Berechtigungen und die Lö- schung des Unterkontos ein.

Um das für den Zugriff auf die Schnittstelle erforderliche Unterkonto anzulegen, nutzen Sie die „Neues Unterkonto anlegen“-Schaltfläche, um zum entsprechenden Formular zu gelangen (Abbildung 4). Beim Ausfüllen bitte darauf achten, dass am Ende die Berechtigung „Ermäch- tigte Stelle REST-API“ ausgewählt ist, weil nur Unterkonten mit dieser Berechtigung die Schnittstelle verwenden können.
Direkt nach der Anlage des Unterkontos werden Ihnen eine generierte Benutzerkennung und ein initiales Passwort angezeigt. Beides wird für die Verwendung der Schnittstelle benötigt. Falls Sie die Daten nicht mehr haben sollten, können Sie die Benutzerkennung auf der „Un- terkonten verwalten“-Seite nachschauen und dort das Passwort zurücksetzen.
Bei Bedarf können mehrere Unterkonten für den Schnittstellenzugriff erstellt oder – etwa bei einem Dienstleisterwechsel – alte Unterkonten gelöscht und neue erstellt werden. Es gibt bei der Schnittstelle keine Unterkonto-spezifischen Einschränkungen beim Datenzugriff: Bei- spielsweise, wenn ein Unterkonto über die notwendige Berechtigung für die Schnittstellennut- zung verfügt, darf es alle bestehenden Lehrgänge einsehen und bearbeiten – nicht nur die mit diesem Unterkonto erstellten.

2.3) Unterkonto verifizieren

Bevor das Unterkonto für den Schnittstellenzugriff verwendet werden kann, muss zunächst die E-Mail-Adresse verifiziert werden. Zusätzlich schaltet dies die „Passwort vergessen?“-Funktionalität frei, ohne die ansonsten nur vom Hauptkonto aus das Passwort des Unterkontos zu- rückgesetzt werden könnte.
Nachdem Sie sich mit den Daten des Unterkontos bei meineQSEH angemeldet haben, können Sie eine Verifizierungs-E-Mail anfordern (siehe Abbildung 5). Bei Bedarf können Sie hierbei die dem Unterkonto zugeordnete E-Mail-Adresse ändern.
Nach kurzer Zeit sollten Sie bei der hinterlegten E-Mail-Adresse eine Nachricht mit einem Be- stätigungslink erhalten. Sobald Sie diesen Link geöffnet haben, ist die Verifikation des Unter- kontos abgeschlossen. Überprüfbar ist dies auf der „Persönliche Daten verwalten“-Seite.

2.4) Authentifizierungstoken anfordern

Nachdem die initiale Anlage eines entsprechend berechtigten Unterkontos abgeschlossen ist, kann die Authentifizierung für die Schnittstellennutzung erfolgen. Die Authentifizierung ist im einfachsten Fall ein zweistufiger Prozess: Anforderung eines Authentifizierungstokens und die anschließende Verwendung des Tokens beim Schnittstellenaufruf. In diesem Abschnitt wird der erste Schritt – die Tokenabfrage – erläutert; in den nachfolgenden Abschnitten wird auf den zweiten Teil eingegangen.

2.4.1) Allgemeines

Die Verwaltung aller Benutzerkonten für meineQSEH und die zugehörige Schnittstelle ist über ein lokales Active Directory mit, unter der Domäne adfs.bghm.de, ins Internet veröffentlichten Active Directory Federation Services (AD FS) realisiert. Alle Anmeldevorgänge werden an die AD FS gerichtet, welche – nach erfolgreicher Prüfung der Anmeldedaten durch das Active Di- rectory – ein Authentifizierungstoken erstellen und zurückgeben.
Anders als bei der Anmeldung für meineQSEH, ist nur eine nicht interaktive Anmeldung für die Verwendung mit der Schnittstelle sinnvoll. Für dieses Szenario sehen wir den OAuth 2.0 re- source owner password credentials grant flow vor. Bei dieser Authentifizierungsmethode be- nötigt Ihre Anwendung die Benutzerkennung und das Passwort des Unterkontos und kann damit das Authentifizierungstoken in Form eines JSON Web Token anfragen.

2.4.1) Allgemeines

Unabhängig von der genauen Umsetzung sind für die Anforderung eines Authentifizierung-tokens folgende Parameter notwendig: