Using finAPI as authentication provider

NOTE: If you need an English version of this article, please let us know.

Nutzerverwaltung und Authentifizierung über finAPI

Bei Verwendung von finAPI hat eine Applikation die Möglichkeit, ihre Nutzerverwaltung und -Authentifizierung an finAPI zu delegieren. Damit fällt für die Applikation die Implementierung von Registrierungs- und Login-Prozessen, oder die Speicherung der Nutzerdaten oder Tokens größtenteils weg. Die Logik der Applikation beschränkt sich im Wesentlichen auf das Durchreichen der Anmeldedaten bzw. –anfragen der Nutzer an finAPI, sowie andersherum auf das Durchreichen der Antwortdaten von finAPI an den Nutzer. Es werden keinerlei Passwörter oder Authentifizierungs-Tokens der Nutzer in der Applikation persistiert. Dies verringert nicht nur den Aufwand für die Entwicklung der Applikation, sondern erhöht auch die Sicherheit der Nutzerdaten.

Die Authentifizierung eines Nutzers über eine einfache Weiterleitung seiner eingegebenen Daten an finAPI impliziert, dass die Anmeldedaten für die Applikation denen für finAPI gleichen. Nutzer X auf Seiten der Applikation ist also auch immer Nutzer X auf Seiten von finAPI. Völlig ohne eigene „Nutzerentität“ kommt die Applikation jedoch trotzdem nicht aus. Sie muss sich in jedem Fall die Nutzerkennungen speichern, d.h. die von den Nutzern bei ihrer Registrierung gewählten Nutzernamen – allerdings nicht die dazugehörigen Passwörter. Die Nutzerkennungen müssen der Applikation bekannt sein um bestimmte nutzerbezogene Anfragen an finAPI stellen zu können, z.B. zur Nutzer-Aktivierung oder Passwortwiederherstellung. Neben der Nutzerkennung sollte die Applikation auch Kontaktdaten zu den Nutzern speichern (z.B. E-Mail-Adresse oder Telefonnummer), um eine Verifizierung der Nutzer vornehmen zu können (finAPI hat keinerlei direkten Kontakt zu den Nutzern, und kann daher nicht selbst eine Verifizierung vornehmen). Allerdings könnte die Applikation auch die Nutzerkennung selbst dafür verwenden, also die Nutzer sich z.B. mit Ihrer E-Mail-Adresse registrieren lassen. Damit müsste die Applikation neben der Nutzerkennung keine zusätzlichen Datensätze über die Nutzer speichern.

finAPI trennt die Daten unterschiedlicher Mandanten komplett voneinander. Darüber hinaus können jedoch innerhalb eines Mandanten mehrere verschiedene Applikationen ("Clients") auf Nutzer innerhalb eines Mandanten zugreifen. Das bedeutet, dass die Nutzer sowie ihre Daten über verschiedene Applikationen („Clients“) hinweg „geteilt“ werden. Damit kann ein Mandant seinen Nutzern mehrere unterschiedliche Applikationen anbieten, die der Nutzer alle nutzen kann sobald er sich einmal bei einer beliebigen dieser Applikationen registriert hat. Der Nutzer hat dasselbe Nutzerkonto (d.h. denselben Login) für alle Applikationen eines Mandanten, und alle Applikationen haben über finAPI den Zugriff auf die (selbe) geteilte Datenbasis des Nutzers. Für den Nutzer fällt also die mehrfache Registrierung sowie das Verwalten mehrerer Logins weg, und in den Applikationen muss keine applikationsübergreifende Synchronisierung der Nutzerdaten vorgenommen werden, weil dies durch finAPI automatisch realisiert ist. Diese Art der „geteilten“ Nutzer setzt jedoch voraus, dass eine finAPI Nutzerkennung innerhalb eines Mandanten eindeutig sein muss; ein Nutzer kann sich also nicht mit derselben Kennung bei verschiedenen Applikationen eines Mandanten registrieren. Hat er sich bereits bei Applikation A1 registriert, und würde dann versuchen sich mit derselben Kennung auch bei Applikation A2 zu registrieren, würde finAPI der zweiten Applikation melden, dass ein Nutzer mit der angegebenen Nutzerkennung bereits existiert. Da ein Nutzer stets in allen Applikationen sichtbar ist, macht es Sinn, dass ein Nutzer auch von jeder beliebigen Applikation heraus aktiviert oder gelöscht werden kann. Dies hat einige Implikationen bezüglich der Datenkonsistenz zwischen den Applikationen untereinander, sowie auch zwischen den Applikationen und finAPI, was weiter unten im Abschnitt "Nutzer-Registrierung, -Aktivierung, und -Löschung" genauer erläutert wird.

Nachfolgend werden nun die einzelnen Prozesse (Client-Authentifizierung, Nutzer-Registrierung, -Aktivierung, und -Löschung, Nutzer-Login / Nutzer-Session / Nutzer-Logout, sowie die Passwortwiederherstellung) genauer beschrieben. Die folgende Grafik zeigt eine Übersicht darüber, welche Daten auf welcher Seite (Applikation vs. finAPI) gespeichert werden:

Client Authentifizierung

Die Authentifizierung des Clients (d.h. der Applikation) bei finAPI erfolgt über die Client Credentials (client_key und client_secret). Aus Sicherheitsgründen wird empfohlen, diese Credentials verschlüsselt in der Datenbank zu halten. Alternativ könnten die Credentials auch in den Konfigurationen des Application Server hinterlegt sein. Oder es wird eine Kombination von beidem gewählt, z.B. client_key in der Datenbank, und client_secret in der Server-Konfiguration. Nicht zu empfehlen ist dahingegen das Hinterlegen der Credentials im Source Code der Applikation, vorallem vor dem Hintergrund dass dieser in der Regel auf diversen Entwickler-Computern ausgecheckt ist, welche meist nicht sonderlich gut gesichert sind.

finAPI antwortet auf eine Client-Authentifizierung mit einem access_token für den Aufruf von Client-basierten Services (z.B. Nutzer anlegen). Dieses Token sollte nur in der Datenbank der Applikation gespeichert werden, und nicht z.B. auf dem mobilen Endgerät des Nutzers.

Neben den Authentifizierungs-Credentials erhält jede Applikation auch einen „Data Decryption Key“. Dies ist ein spezieller Schlüssel welchen die Applikation benötigt um bestimmte von finAPI gesendete Daten zu entschlüsseln (siehe den weiter unten folgenden Abschnitt „Passwortwiederherstellung“). Genauso wie die Credentials sollte auch dieser Key in der Datenbank oder in den Konfigurationen des Application Servers hinterlegt sein. Für zusätzliche Sicherheit sollte der "Decrpytion Key" ebenfalls verschlüsselt werden.

 

Nutzer-Registrierung, -Aktivierung, und -Löschung

Der Prozess der Registrierung und Aktivierung eines Nutzers läuft wie folgt ab:

  1. Nutzer registriert sich mit selbst gewählter Nutzerkennung, Passwort, und eventuellen Kontaktdaten (z.B. E-Mail-Adresse) bei der Applikation.
  2. Die Applikation leitet Nutzerkennung und Passwort an finAPI weiter und legt dort einen entsprechenden Nutzer an – die Nutzerdaten werden in finAPI verschlüsselt gespeichert. Zu diesem Zeitpunkt ist der Nutzer in finAPI noch nicht aktiviert, d.h. eine Authentifizierung bzw. Login ist noch nicht möglich.
  3. Wenn der Nutzer erfolgreich bei finAPI angelegt ist, speichert sich die Applikation auch ihrerseits die Nutzerkennung (aber nicht das Passwort!), sowie die Kontaktdaten (sofern zusätzliche Kontaktdaten zur Nutzerkennung auf Seiten der Applikation erforderlich sind).
  4. Die Applikation verifiziert den Nutzer auf ihrer Seite. Ist dies erfolgreich, so aktiviert die Applikation den Nutzer seitens finAPI (über Angabe der Nutzerkennung). Ab diesem Zeitpunkt kann sich der Nutzer bei finAPI authentifizieren bzw. einloggen.

finAPI bietet der Applikation nebem den Services zum Anlegen und Aktivieren eines Nutzers auch Services zum Abfragen des Aktivierungs-Status eines Nutzers, sowie zum Löschen eines noch nicht aktivierten Nutzers.

Zum Passwort ist anzumerken, dass dieses seitens finAPI aus mindestens 6 Zeichen bestehen muss. Weitere Restriktionen kann eine Applikation natürlich auf ihrer Seite implementieren.
Der Nutzername wird von finAPI stets case-insensitive gehandelt. D.h. Die Nutzernamen "Nutzer", "NuTZer" oder "NUTZER" werden von finAPI als gleicher Nutzername angesehen. Der Nutzername darf nur aus alphanumerischen Zeichen sowie den Sonderzeichen - _ . + @ bestehen.

Die Nutzerdaten in finAPI werden über mehrere Applikationen hinweg innerhalb eines Mandanten geteilt, was folgende Implikationen hat:

  • Wenn sich ein Nutzer bei einer Applikation registriert, kann er sich nicht mehr bei weiteren Applikationen des gleichen Mandanten mit den selben Daten registrieren. Bei einem entsprechenden Versuch wird finAPI den anderen Applikationen melden, dass der Nutzer bereits existiert
  • Umgekehrt bedeutet dies auch, dass ein Nutzer sich in einer Applikation einloggen kann, obwohl er in dieser Applikation noch gar nicht existiert. Sofern ein Mandant mehrere Applikationen betreibt, sollte ein Login-Versuch eines Nutzers also stets an finAPI weitergeleitet werden - sollte sich herausstellen, dass der Nutzer in finAPI existiert, kann die Applikation den Nutzer nachträglich in ihrer Datenbank eintragen
  • Ein Nutzer kann - zumindest soweit es finAPI betrifft - von jeder beliebigen Applikation aktiviert werden. Seitens finAPI ist also nicht sichergestellt dass ein Nutzer von derjenigen Applikation aktiviert wird, von der er registriert wurde. Dies bedeutet für eine Applikation, dass beim Versuch einen Nutzer in finAPI zu aktivieren die Antwort von finAPI kommt, dass der Nutzer bereits aktiviert ist. Die Applikation sollte diesen Fall also auch in ihrer Implementierung berücksichtigen.
  • Was gerade über die Nutzer-Aktivierung gesagt wurde, gilt auch für das Löschen eines noch nicht aktivierten Nutzers. Jede Applikation kann einen noch nicht aktivierten Nutzer löschen, wodurch es zu einer Situation kommen kann, dass in einer Applikation ein Nutzer existiert, der in finAPI aber nicht mehr existiert (da er über eine andere Applikation gelöscht wurde). Auch diesen Fall sollten die Applikationen berücksichtigen.
  • Da finAPI Nutzer in verschiedenen Applikationen eines Mandanten gelöscht werden können, müssen die Nutzerdaten zwischen den Applikationen synchronisiert werden. Hierfür bietet finAPI einer Applikation die Möglichkeit, über das Löschen eines Nutzers informiert zu werden. finAPI bietet dafür einen Service an, bei dem eine Applikation eine Callback-URL hinterlegen kann, an die finAPI eine Nachricht sendet, wenn ein Nutzer gelöscht wird. Diese Nachricht enthält den Nutzernamen, anhand dessen die Applikation ihren eigenen Nutzerbestand entsprechend anpassen kann (d.h. sofern es diesen Nutzer in ihrer Datenbank gibt, kann sie ihn löschen). Die folgende Grafik illustriert diesen Vorgang der Synchronisierung von gelöschten Nutzern zwischen mehreren Applikationen:

Als letztes sei angemerkt, dass die Funktionsweise der "shared user accounts" nicht nur bei der Entwicklung der Applikationen bedacht werden muss, sondern von den Applikationen auch klar an ihre Nutzer kommuniziert werden sollte. Es sollte einem Nutzer also klar sein, dass wenn er sein Konto in irgendeiner Applikation löscht, seine Daten in allen Applikationen gelöscht sind.

Nutzer-Login / Nutzer-Session / Nutzer-Logout

Ist ein Nutzer bei finAPI aktiviert, kann er sich authentifizieren bzw. einloggen:

  1. Nutzer meldet sich mit seiner Nutzerkennung und Passwort bei der Applikation an.
  2. Die Applikation leitet die Anmeldedaten an finAPI weiter.
  3. Bei erfolgreichem Login erhält die Applikation von finAPI ein access_token und refresh_token zum Aufruf von nutzergebunden Services.
  4. Die Applikation sollte die Tokens aus Sicherheitsgründen nicht persistieren, sondern lediglich in der Web-Session bzw. bei mobilen Anwendungen im Arbeitsspeicher halten.

Nach erfolgtem Login können access_token und refresh_token verwendet werden um Anfragen an finAPI zu stellen bzw. neue Tokens zu generieren. Die Gültigkeitsdauer von finAPI generierten refresh_tokens kann über die Client Konfiguration gesetzt werden.

Beim Logout sollte die Applikation die Tokens stets aus der Session bzw. dem Arbeitsspeicher löschen, und die Tokens in finAPI invalidieren. Bei einem neuen Login muss der Nutzer dadurch erneut seine Anmeldedaten eingeben.

Passwort-Wiederherstellung

finAPI bietet der Applikation die Möglichkeit, das Passwort eines Nutzers wiederherzustellen bzw. zu ändern. Aus Sicherheitsgründen erfolgt dies innerhalb von finAPI in einem Zwei-Schritt-Verfahren, bei dem die Applikation eine spezielle Datenentschlüsselung vornehmen muss, um sich bei finAPI als rechtmäßiger Antragsteller zu identifizieren. Der gesamte Prozess hat folgenden Ablauf:

  1. Nutzer beantragt Passwortwiederherstellung in der Applikation.
  2. Die Applikation verifiziert den Nutzer als den Antragsteller der Passwortänderung (z.B. über die E-Mail-Adresse, vgl. Prozess der Nutzer-Aktivierung).
  3. Nutzer gibt neues Passwort in der Applikation ein.
  4. Applikation sendet eine Anfrage auf Passwortänderung an finAPI (Aufruf eines speziellen Services unter Angabe der Nutzerkennung).
  5. finAPI antwortet mit einem verschlüsselten Datensatz.
  6. Die Applikation entschlüsselt den erhaltenen Datensatz mittels ihres Data Decryption Key.
  7. Die Applikation ruft den Passwort-Ändern-Service in finAPI auf, unter Angabe der Nutzerkennung, des neuen Nutzer-Passworts, sowie dem entschlüsselten Datensatz.
  8. Sofern der übergebene entschlüsselte Datensatz von finAPI als gültig befunden wird, wird das Passwort des Nutzers geändert. Außerdem werden alle eventuell vergebenen access_tokens und refresh_tokens dieses Nutzers invalidiert. Er muss sich nach der Passwortänderung also erneut einloggen (dies gilt für alle Applikationen!)

Sie haben Fragen zu diesem Konzept oder brauchen Unterstützung?

Bitte kontaktieren Sie uns, falls wir Sie bei der Umsetzung dieser Richtlinien unterstützen können (z.B. in Form eines SDK oder in Form von Beratung).

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk