Um alle Daten in APPRENTIO automatisiert importieren zu können (Personen, Stationen, Standortabhängige Stationsdaten, Urlaube und Abwesenheiten) wird das Add-on "automatisierter Import" benötigt. Das Add-on ermöglicht die Einrichtung von OAuth Clients mit denen Daten sicher übertragen werden können.

So gehts:

Voreinstellungen

Klicke im Menü unter „Einstellungen“ auf den Menüpunkt „OAuth2 Clients“ (Der Menüpunkt ist nur mit dem Add-On sichtbar)

OAuth 2.0 ist ein Protokoll, mit dem ein Client die Autorisierung für private Details im APPRENTIO-Konto eines Benutzers anfordern kann, ohne dessen Passwort zu erhalten. Dies wird der HTTP-Basisauthentifizierung vorgezogen, da Token auf bestimmte Datentypen beschränkt und von Benutzern jederzeit widerrufen werden können.

OAuth Clients

Der Client fragt nach bestimmten Berechtigungsbereichen (Scopes) und wird nach Zustimmung eines Benutzers mit Zugriffstoken belohnt. Du musst einen Client erstellen, bevor du beginnen kannst. Einem vorhandenen Client wird eine eindeutige Client-ID und ein Client-Secret zugewiesen, die im OAuth-Flow verwendet werden. Das Client Secret sollte nicht weitergegeben werden.

Einrichtung eines OAuth Clients

Um einen Client anzulegen, gehe auf Einstellungen → OAuth2 Clients.

Hier kannst du nun über den “+”-Button oben rechts einen neuen Client anlegen.

Auswahl des Client Typs

Du wirst im nächsten Schritt gefragt, wofür du diesen Client nutzen möchtest. Dies entscheidet auch darüber, welchen Grant Type der Client nutzen wird (siehe weiter unten). Wähle deswegen sorgfältig aus, welchen Client Typen du für deinen Anwendungsfall benötigst.

Beim Erstellen des Clients hast du die Möglichkeit einen Namen für den Client zu vergeben. Dieser sollte so gewählt sein, dass du immer weißt, wofür der Client genutzt werden soll. Du kannst weitere Details dazu aber auch noch in dem Beschreibungsfeld ergänzen.
Zusätzlich kannst du eine Homepage angeben. Das kann hilfreich sein, wenn du den Client in einer SPA verwendest. Du kannst das Feld auch leer lassen. Die Homepage wird nicht genutzt, um die Weiterleitung für den Authorization Code Flow zu vergeben.

Dafür gibt es das Feld “Redirect URL”. Dieses ist relevant, damit der OAuth Flow funktionieren kann und muss zu deiner Anwendung zeigen. Du kannst hier auch mehrere Einträge hinterlegen, indem du diese mit einem Komma trennst.

Wenn du alle Daten eingegeben hast und speicherst, wird dir auch das Client-Secret angezeigt.
Dieses solltest du dir sofort sicher abspeichern, da es beim Neuladen oder Wechseln der Seite nicht wieder angezeigt wird. Du kannst dir auch ein neues Secret generieren lassen, musst dieses dann aber bei deinen Anwendungen erneut hinterlegen.

Die OAuth Authorization Grant Types

APPRENTIO unterstützt mehrere sogenannte Grant Types. Bei der Erstellung eines OAuth2-Clients kann zwischen diesen je nach Anwendungstyp gewählt werden.

Client Credentials Grant

Der OAuth 2.0 Client Credentials Grant, manchmal auch zweistufiges OAuth genannt, wird für den Zugriff auf web-gehosteten Ressourcen unter Verwendung der Identität einer Anwendung verwendet. Diese Art der Autorisierung wird häufig für Interaktionen zwischen Servern und Maschinen genutzt, die ohne Benutzereingriff im Hintergrund ausgeführt werden müssen. Anwendungen, die den Client Credentials Grant nutzen, nehmen deshalb nicht die Identität eines Benutzers an, sondern verwenden die Client-ID und das Client-Secret als Anmeldeinformation. Deshalb müssen diese Anmeldeinformationen sicher aufbewahrt werden. Veröffentliche diese Anmeldeinformationen niemals in öffentlich einsehbarem Quellcode, wie Javascript Code auf Webseiten.

Es gibt jedoch APPRENTIO API-Endpunkte für die eine reale Benutzerinteraktion erwartet wird. Diese sind für Zugriffe mit dem Client Credentials Grant nicht verfügbar.

Um einen Access Token zu erhalten, ist das Vorgehen sehr einfach.
Schicke einen POST-Request an folgende URL:

https://tenant.apprentio.de/api/v1/oauth/token

Als POST-Parameter sollten folgende Werte übergeben werden:

grant_type → client_credentials
client_id → Eindeutige ID, welche bei der Erstellung der APP generiert wird (erforderlich)
client_secret → Das Secret, welches du beim Erstellen der Anwendung bekommen hast
scope → Berechtigungen zum Anfordern (optional)

Als Antwort vom Server erhältst du dann bei den korrekten Daten den access_token, welchen du für alle weiteren Server-Anfragen nutzen kannst.

Authorization Code Grant

Der Gewährungstyp „Authorization Code“ wird von Web- und mobilen Apps verwendet. Er unterscheidet sich von den meisten anderen Grant-Typen dadurch, dass die App zunächst einen Browser starten muss, um den Flow zu starten. Grob zusammengefasst, sieht der Ablauf folgendermaßen aus:

Die Anwendung öffnet einen Browser, um den Benutzer an den OAuth-Server (APPRENTIO) zu senden
Der Benutzer sieht die Autorisierungsaufforderung und genehmigt die Anfrage des Clients
Der Benutzer wird mit einem Autorisierungscode in der Abfragezeichenfolge zurück zur Anwendung umgeleitet
Die Anwendung tauscht den Autorisierungscode gegen ein Zugriffstoken aus

Der Ablauf des Autorisierungscodes wird am besten in Web- und mobilen Apps verwendet. Da die Erteilung des Autorisierungscodes den zusätzlichen Schritt des Austauschs des Autorisierungscodes gegen das Zugriffstoken umfasst, bietet sie eine zusätzliche Sicherheitsebene, die im Typ der impliziten Erteilung nicht vorhanden ist. Wenn du den Ablauf des Autorisierungscodes in einer mobilen App oder einer anderen Art von Anwendung verwenden möchtest, die keinen geheimen Clientschlüssel speichern kann, solltest du die PKCE-Erweiterung verwenden.

Schritt 1 – Senden von Benutzern zur Autorisierung

Deine Web- oder mobile App sollte Benutzer auf die folgende URL umleiten:

https://tenant.apprentio.de/api/v1/oauth/authorize

Als GET-Parameter sollten folgende Werte übergeben werden:

grant_type → authorization_code
client_id → Eindeutige ID, welche bei der Erstellung des Clients generiert wurde (erforderlich)
redirect_uri → URL, zu der zurückgeleitet werden soll
scope → Berechtigungen zum Anfordern (erforderlich)
state → Eindeutige Zeichenfolge, die nach Abschluss zurückgegeben werden soll (optional)

Der Scope-Parameter ist eine durch Leerzeichen getrennte Liste von OAuth-Bereichen, die angibt, auf welche Teile von APPRENTIO du mit deinem Client zugreifen darfst. Die vollständige Liste der Geltungsbereiche findest du unter "Verfügbare Scopes".

Der State-Parameter sollte verwendet werden, um Fälschungsangriffe zu vermeiden, indem ein Wert übergeben wird, der für den authentifizierten Benutzer eindeutig ist. Dieser wird zusätzlich überprüft, wenn die Authentifizierung abgeschlossen ist.

Schritt 2 – Benutzer werden mit einem Bestätigungscode auf deinen Server umgeleitet

Wenn der Benutzer deinen Client autorisiert, leitet APPRENTIO mit einem temporären Code in einem Code-GET-Parameter sowie dem State-Parameter, soweit vorher als Schritt vorgegeben, zurück zu der angegebenen redirect_uri. Wenn der State nicht übereinstimmt, wurde die Anfrage möglicherweise von einem Dritten erstellt und du solltest den Vorgang abbrechen.

Schritt 3 – Austausch eines Verifizierungscodes gegen ein Zugriffstoken

Wenn alles in Ordnung ist, tauschst du den Autorisierungscode mithilfe der API-Methode oauth.access gegen ein Zugriffstoken aus.

https://tenant.apprentio.de/api/v1/oauth/token

client_id → wird angezeigt, nachdem du den Client erstellt hast (erforderlich)

client_secret → wird angezeigt, nachdem du den Client erstellt hast (erforderlich)

code → ein temporärer Autorisierungscode (erforderlich)

redirect_uri → muss mit dem ursprünglich übermittelten URI übereinstimmen

Du erhältst eine JSON-Antwort mit einem access_token (neben anderen Details):

1 {
2    "access_token": "398475dfgdfg48xfgdfgh63-234897fdghgfhjfdgs5623103",
3    "scope": "bulk-import:write,bulk-import:read"
4 }

Du kannst diesen Zugriffstoken dann verwenden, um API-Methoden im Namen des Benutzers aufzurufen. Der Zugriffstoken funktioniert weiter, bis der Benutzer entweder den Token widerruft und/oder den Client entfernt.

Verwendung mit PKCE (Proof Key for Code Exchange)

Der Authorization Code Flow + PKCE ist ein Authorization-Flow, der speziell für die Authentifizierung von Benutzern nativer oder mobiler Anwendungen entwickelt wurde.

PKCE, ausgesprochen „Pixy“, ist ein Akronym für Proof Key for Code Exchange. Der Hauptunterschied zwischen dem PKCE-Flow und dem Standard-Autorisierungscode-Flow besteht darin, dass Benutzer kein client_secret angeben müssen. PKCE reduziert Sicherheitsrisiken für native Apps, da keine eingebetteten Geheimnisse im Quellcode erforderlich sind, wodurch die Gefahr von Reverse Engineering begrenzt wird.

Anstelle von client_secret erstellt die Client-App einen eindeutigen Zeichenfolgenwert, genannt code_verifier, den sie hasht und als code_challenge codiert. Wenn die Client-App den ersten Teil des Autorisierungscodeflusses initiiert, sendet sie eine gehashte code_challenge.

Sobald sich der Benutzer authentifiziert und der Autorisierungscode an den Client zurückgegeben wurde, fordert sie im Austausch für den Autorisierungscode ein access_token an.

In diesem Schritt muss der Client den ursprünglichen eindeutigen Zeichenfolgenwert in den Parameter „code_verifier“ aufnehmen. Wenn die Codes übereinstimmen, ist die Authentifizierung abgeschlossen und ein access_token wird zurückgegeben.

Viele OAuth2-Clientbibliotheken lösen die Codeabfrage und -überprüfung, aber wenn du deine eigene Lösung erstellst, erwartet APPRENTIO folgendes:

Erstelle zunächst eine eindeutige Zeichenfolge, die als code_verifier fungiert. Wir empfehlen den code_verified zu speichern, da er für die zweite Anforderung im Ablauf des Autorisierungscodes benötigt wird.

1 let codeVerifier = 'random-unique-string-123'
2
3 const crypto = require('crypto')
4 const base64url = require('base64url')
5
6 let hash = crypto.createHash('sha256').update(codeVerifier).digest();
7 let codeChallenge = base64url.encode(hash)

Die code_challenge sendest du mit, wenn du den anfänglichen Autorisierungscode anforderst.

Speichern von Token und Anmeldeinformationen

Bewahre die Anmeldeinformationen und Benutzertoken deiner Anwendung sorgfältig auf.

Die Client-ID ist eine Information, die verwendet wird, um deine Anwendung zu identifizieren, und erscheint häufig in OAuth-Verhandlungs-URLs und anderen Kontexten. Die Client-ID kann frei in Code und E-Mail weitergegeben werden und kann nicht allein verwendet werden, um im Namen deiner Anwendung zu handeln.

Das Client-Secret sollte vorsichtig behandelt werden. Verteile keine Client-Secrets in E-Mails, verteilten nativen Anwendungen, clientseitigem Javascript oder öffentlichen Code-Repositorys.

Zugriffstoken, wie sie beispielsweise über die Authorization Code Flow empfangen werden, können nur die Berechtigungen verwenden, die ihnen während des OAuth-Flows unter Verwendung von Scopes gewährt wurden. Bewahre diese Token sorgfältig auf und platziere sie niemals in einem öffentlichen Code-Repository oder clientseitigem Code wie Javascript.

Verwenden von Zugriffstoken

Die dem Client zugeteilten Token können in Anfragen an die APPRENTIO-API verwendet werden. Der beste Weg die Zugriffstoken, auch als Bearer-Token bekannt, zu kommunizieren, besteht darin, sie im Authorization-HTTP-Header einer Anfrage zu verwenden:

1 GET /api/v1/import-profiles/1/file
2 Authorization: Bearer TgyODFkZWE4MTU2NzZkYmVl...

Scopes verwenden

Mit Scopes kannst du genau angeben, welche Art von Zugriff du benötigst. Scopes beschränken den Zugriff für OAuth-Token. Sie gewähren keine zusätzliche Berechtigung, die über die des Benutzers hinausgeht.

Verfügbare Scopes

Jeder Scope ist an bestimmte Endpunkte geknüpft und definiert damit, welche Teile der APPRENTIO API eingeschränkt werden können. Werden beim Erstellen des OAuth-Tokens keine Scopes mit angegeben, werden automatisch alle zu diesem Zeitpunkt verfügbaren Scopes dem Token zugeteilt.

Folgende Scopes können aktuell genutzt werden:

Nächster Artikel: Warum kommt beim Import eine Fehlermeldung?

Automatisierter Import (Add-on): Authentifizierung über OAuth Clients