Die User-Management-API (UMA) stellt eine Schnittstelle für die Bibliotheken zur Verfügung um Nutzer von HDS zu verwalten. Sie stellt folgende drei Funktionen zur Verfügung:

  1. Abfrage der von HDS gespeicherten Informationen eines/r Nutzers/in um dem Recht auf Auskunft nachzukommen
  2. Löschen aller in HDS gespeicherten Informationen eines/r Nutzers/in um dem Recht auf Löschung nachzukommen
  3. Umziehen aller Nutzerinformationen (Merklisten, gespeicherte Suchen) von einer alten zu einer neuen Nutzerkennung

Einrichtung

Für die Nutzung sind prinzipiell nur zwei Absprachen zu treffen. Zum einen muss dem HDS Team ein IP-Bereich mitgeteilt werden, in dem die API erreichbar sein soll und zum anderen muss ein Access-Token erstellt werden (siehe "Authentifizierung").

Es sollte dann möglich sein, die API automatisch in Prozessen wie Löschen von Nutzern oder Erstellen eines neuen Bibliotheksausweises einzubinden. Siehe "Nutzung" für eine Beschreibung der API.

Bei Fragen helfen wir natürlich gerne weiter.

Authentifizierung

Um die API benutzen zu können benötigt man ein Access-Token. Dieses kann direkt über den Adminbereich (Pfad "/Admin/UMAToken") in HDS beantragt und nach Ausstellung abgerufen werden.

  1. Falls ein neues Token benötigt wird, kann das über den "Token beantragen" Button gemacht werden.

    Daraufhin nehmen wir dann Kontakt auf um zu prüfen, ob wirklich ein Token benötigt wird und die Anfrage valide ist.

    Wir können das ganze natürlich auch direkt per Mail oder in einem Treffen machen.

  2. Das Token wird dann bereitgestellt und kann über die selbe Seite abgefragt werden.




    Dieses Token ist nur für einen kurzen Zeitraum verfügbar und sollte direkt an einem sicheren Ort abgespeichert werden.


Dieses Token muss dann als Authorization-Header bei allen Fragen an die API mitgeschickt werden.

Nutzung

Die API ist unter https://hds2test.hebis.de/uma/<instanz>/swagger/ definiert und kann ausgetestet werden.

Hinweise:

  • Mit "username" ist jeweils die Nutzerkennung gemeint, die über den IdP geliefert wird. Das ist in der Regel der Barcode.
  • Die API sollte mit äußerster Vorsicht genutzt werden. Änderungen werden direkt live genommen und können nicht einfach wieder zurückgenommen werden. Bevor das ganze im Produktivsystem genutzt wird, sollte die Nutzung auf dem Testsystem getestet werden. Das Token sollte möglichst sicher aufbewahrt werde.
  • Unterschiedlich Nutzerkennungen bedeuten in HDS unterschiedliche logische Nutzer. Wir können nicht erkennen, ob zwei Kennungen zu einem realen Nutzer gehören. Wenn ein Nutzer Merklisten und Suchen mit zwei unterschiedlichen Kennungen gespeichert hat, können sie trotzdem noch umgezogen werden. Allerdings werden Merklisten mit gleichem Namen nicht gemerged. Sie tauchen dann jeweils getrennt auf.
  • No labels
Write a comment...