Zur Homepage www.HI-Tier.de OAuth / OpenID
Zurück Home Nach oben
Öffentlicher Bereich für Entwickler

 

zuständigRP
DatumNov 2024
Standfunktional

OAuth / OpenID Connect als Zentraler Anmeldedienst HIT/ZID

Stand Sept 2024

bulletDie OIDC-Schnittstelle ist funktional fertig und kann im Testsystem getestet werden.
bulletDie Abnahme der Funktion und Freigabe für die Produktion durch unseren Auftraggeber (die Bund-Länder-Arbeitsgemeinschaft BLAG/DZ) ist erfolgt.
bulletDie Nutzung der Schnittstelle ist vorbehaltlich der Genehmigung durch den Vertreter des Landes in der BLAG/DZ.
bulletWenn Sie den zentralen HIT / ZID-Anmeldedienst in Ihrer Anwendung nutzen möchten, ist eine Registrierung Ihrer Anwendung in Form einer ClientID erforderlich. Dazu sind unten die Hinweise zu beachten und das Formular auszufüllen.

Kurz und bündig

Bevor eine OAuth-Anfrage durchgeführt werden kann, müssen die Clients bei der Zentralen Datenbank registriert worden sein. Jeder Client (nicht der Benutzer!) wird durch seine Kennung, seine Antwort-URIs und ein Passwort authentifiziert. Dann kann damit nach dem OpenID Connect-Verfahren (kurz OIDC) zunächst eine Nutzerautorisierung und schließlich ein Access Token angefordert werden:

  1. Anfrage via Webbrowser per HTTPS-GET-Request am HIT/ZID-Anmeldedienst mit Client-Kennung
  2. Wird Client-Kennung akzeptiert, Anzeige des Formulars "Zentralen Anmeldedienst"es im HIT3-Web, bei dem sich der Nutzer authentifiziert.
  3. Nach erfolgreicher Anmeldung Weiterleitung (ohne die PIN des Nutzers) zum anfragenden Client mit einem sehr kurz gültigen Authorization Code.
  4. Im Anschluss direkte HTTPS-POST-Anfrage des Clients am HIT/ZID-Anmeldedienst mit in 3) erhaltenem Authorization Code, um das eigentliche Access Token und optional ein Refresh Token zu erhalten. Neben diesen Token wird auch ein Payload in Form eines JWT übermittelt, das neben OAuth-Standardclaims auch die Betriebsnummer und Mitbenutzerkennung enthält. Je nach vergebenem Recht für den Client werden weitere Angaben im Payload geliefert, wie z.B. Name und Adresse.
  5. optional: ist ein Authorization Code abgelaufen, kann über eine weitere direkte HTTPS-POST-Anfrage des Clients am HIT/ZID-Anmeldedienst mit dem Refresh Token ein neues Access Token angefordert werden. Falls nicht oder falls der Client kein Refresh Token angefordert hat, dann muss der Prozess von neuem bei 1) begonnen werden, wenn der Nutzer sich authentifizieren muss
  6. optional, wenn für den Client das Recht eingeräumt wurde: zusammen mit Betriebsnummer und Mitbenutzerkennung kann das Access Token zur Anmeldung am HIT3-REST-Service genutzt werden

Neben diesen kann über OIDC Discovery in Erfahrung gebracht werden, welche URIs und Parameter die OIDC-Schnittstelle versteht: z.B. für Test-System.

Es ist neben OIDC Core lediglich OIDC Session Management implemeniert. Keine der beiden Channel Logout-Mechanismen sind vorhanden.

Registrierung Client

Wichtiger Hinweis: Nur registrierte Clients können sich mit OAuth verbinden. Für eine Registrierung ist vorab eine Genehmigung durch den Vertreter des Landes in der BLAG/DZ erforderlich!

Da wir (derzeit) eine Client-Registrierung weder per Webseite, noch per HIT-Protokoll, noch per OpenID Connect Dynamic Registration unterstützen, bitte formlos eine Email an technik@hi-tier.de mit folgenden Angaben senden (einfach Tabelle ausfüllen, dann den "Email-Text erzeugen"-Knopf klicken und das erzeugte in die Email einfügen):

System
Für welches der folgenden Systeme soll der Client registriert werden:
bulletTest (für bekannte Testbetriebe)
bulletProduktion (für echte Betriebsstätten und Unternehmen, auch gültig für Clone)
bulletWartung (für selbstverwaltete Testbetriebe)

Wichtig:
Sie benötigen eine Genehmigung zur Registrierung durch den Vertreter Ihres Bundeslandes
in der BLAG/DZ! Das gilt im Prinzip auch für das Test- und Wartungssystem.

Name
Name des Clients für die Anzeige, z.B. beim Login des "Zentralen Anmeldediensts" bei uns (max 99 Zeichen).
Client ID , alternativ
gewünschte Client-Kennung für den OAuth-Prozess (max 10 Zeichen, ggf. mehrere angeben falls bereits belegt).
Sollte ein-/zweistelliges Länderkürzel enthalten.
Weiterleitungs-URI Authorization
ein oder mehrere Weiterleitungs-URIs, an die der OAuth-Prozess die Autorisierungsbestätigung
per HTTP-Request zurücksenden darf
Weiterleitungs-URI Session Logout
ein oder mehrere Weiterleitungs-URIs, zu denen der OAuth-Prozess nach dem expliziten Logout
der Session per HTTP-Request zurückkehren darf
Gültigkeitszeitraum von bis (Format TT.MM.JJJJ)
Gültigkeitszeitraum, in dem der Client gültig ist. Bei "bis" kann auch "offen" angegeben werden.
Der Zeitraum gilt auch für sämtliche Weiterleitungs-URIs.
Lebensdauer AUC Sekunden
gewünschte Lebensdauer des Authorization Code in Sekunden (Standard: 20 Sekunden, max: 300 = 5 Minuten)
Lebensdauer ACT Sekunden
gewünsche Lebensdauer des Access Token in Sekunden (Standard: 1200 Sekunden = 20 Minuten, max: 3600 = 1 Stunde).
Innerhalb dieses Zeitraums ist der Nutzer bei HIT/ZID authentifiziert, ohne dass eine Anmeldung erforderlich ist.
Wichtig: Access Tokens haben eine absolute Lebensdauer, d.h. die Lebensdauer verlängert
sich im Gegensatz zu Session-Cookies nicht bei jedem Zugriff!
Lebensdauer RET Sekunden
gewünschte Lebensdauer des Refresh Token in Sekunden (Standard: 43200 Sekunden = 12 Stunden, max: 86400 = 24 Stunden).
Innerhalb dieses Zeitraums können Access Tokens erneuert werden. Ist kein Refresh Token erwünscht, ist 0 anzugeben.

Ein Refresh Token ist nur nötig, wenn das Access Token auch zur Anmeldung verwendet werden darf. Für eine reine Authentifizierung nicht.

Anmelde-Nutzergruppe
Dürfen sich alle Betriebsnummern am ZAD für den Client authentifizieren oder nur bestimmte Nutzergruppen? Möglich sind derzeit:
bullet#0 - wie bisher alle
bullet#1 - nur Rinderhalter (Typen 1, 2, 3, 4, 200, 301, 401, 501, 600, 601)
bullet#2 - nur InVeKoS-Antragsteller (Typen 17, 1001 bis 1019)

Siehe auch Codeset OI_C_BTYP.

Wenn nur bestimmte Betriebstypen autorisiert sein sollen, die nicht in einer der o.g. Nutzergruppen (außer #0) abgebildet sind,
dann bitte mit uns abstimmen! Es gibt eine erweiterte Möglichkeit, das zu bewerkstelligen.

Daten/Rechte-Freigabe
Welche Daten dürfen maximal mit einer Autorisierung durch den Anwender an den Client zurückgesendet und/oder
ist eine Anmeldung an HIT/ZID mit dem ACT erlaubt? Möglich sind derzeit:
bullet#0 - wie bisher unbeschränkt: Autorisieren, Anmelden mit ACT*,
        Betriebsnummer und Betriebstypen im Payload (kein Name, keine Adresse)
bullet#1 - Autorisieren, keine weiteren Rechte,
        nur Betriebsnummer im Payload
bullet#2 - Autorisieren, keine weiteren Rechte,
        Betriebsnummer und Betriebstypen im Payload
bullet#3 - Autorisieren, keine weiteren Rechte,
        Betriebsnummer, Betriebstypen und Namen im Payload
bullet#4 - Autorisieren, keine weiteren Rechte,
        Betriebsnummer,Betriebstypen, Namen und Adresse im Payload
bullet#99 - Autorisieren, Anmelden mit ACT*,
          nur Betriebsnummer im Payload

Siehe auch Codeset OI_C_RECHT.

*) Anmelden mit ACT bedeutet Anmelden mit dem erhaltenen Access Token im Rechtekontext des Betriebes
(analog einer Anmeldung mit PIN, damit können innerhalb der Kompetenzen des Benutzers alle HIT und ZID Daten gelesen und geändert werden)

Weitere Daten/Rechte-Freigaben werden eventuell noch durch die BLAG/DZ festgelegt.

Pflicht Zweiter Faktor
Wie darf eine Zwei-Faktor-Authentifizierung seitens des Clients verwendet werden? Möglich sind derzeit:
bullet#0 - keine Zwei-Faktor-Authentifizierung verwenden, auch wenn das Land/der Nutzer eigentlich eine verwenden soll (analog ZFA_LIGHT=1)
bullet#1 - wie bisher Zwei-Faktor-Authentifizierung für Nutzer mit Betriebstypen 960 (= "darf") oder 961 (="muss")
bullet#2 - Zwei-Faktor-Authentifizierung freiwillig für alle/im Land
bullet#3 - Zwei-Faktor-Authentifizierung Pflicht für alle/im Land, Opt-out durch Betrieb und Betriebstyp möglich (analog ZFA_LIGHT=2)
bullet#4 - Zwei-Faktor-Authentifizierung Pflicht für alle/im Land, Opt-out nur durch Betriebstyp möglich (analog ZFA_LIGHT=3)
bullet#5 - Zwei-Faktor-Authentifizierung Pflicht für alle/im Land, Opt-out weder durch Betrieb noch Betriebstyp möglich (analog ZFA_LIGHT=4)

Für die Optionen #0 und #3 - #5 wurde für OIDC ein Sonderkonstrukt geschaffen, um die Anmeldung mit einem zweiten Faktor abzuschwächen oder zu erzwingen.

Siehe auch Codesets OI_C_ZFA und ZFA_LIGHT.

fachlich zuständig
Muss ausgefüllt werden!
Name und Kontaktdaten für den fachlich Verantwortlichen des Clients und fachlicher Unterstützung bei Problemen bei der Authentifizierung.
Die Angabe einer Hotline oder Ansprechadresse in Form einer Telefonnummer oder Mailadresse ist zwingend!
Die Angabe wird beim Login des "Zentralen Anmeldediensts" angezeigt.
technisch zuständig
Muss ausgefüllt werden!
Name und Kontaktdaten für den technisch Verantwortlichen des Clients und technischer Unterstützung bei Problemen bei der Authentifizierung.
Die Angabe einer Hotline oder Ansprechadresse in Form einer Telefonnummer oder Mailadresse ist zwingend!
Die Angabe wird beim Login des "Zentralen Anmeldediensts" angezeigt.

Der Klick auf den Knopf erzeugt dynamisch einen Email-Text, der in die Zwischenablage kopiert wird.
Diesen dann einfach in die Email an uns als Text einfügen.

  →  

(Javascript muss dafür aktiv sein. Falls das nicht funktionieren sollte, tut es auch ein Screenshot der ausgefüllten Tabelle)

Sollten die Angaben nicht stimmen, kann jederzeit korrigiert und ein neuer Email-Text erzeugt werden, um den richtigen dann in die Email einfügen zu können.

Wir tragen die per Email zugesandten Angaben manuell bei uns ein und Sie erhalten dann von uns einen zufällig generierten String, der als client_secret (zusammen mit der client_id) beim Autorisieren des Clients (beim Authentifizieren eines Nutzers und beim Abholen eines Access Tokens) angegeben werden muss.

Neu ab Februar 2022: die Schnittstelle wurde um eine Anmelde-Nutzergruppe, eine Daten/Rechte-Freigabe und Angaben von Verantwortlichen erweitert (siehe die letzten vier Felder im Formular oben). Diejenigen, die vor Februar 2022 einen Client registriert haben (egal ob für Test, Prodution oder Wartung), melden bitte die Angaben aus den vier genannten Feldern formlos per Email unter der Angabe des Systems und der client_id nach!

Schaubild OIDC

Details zur Implementierung

Ablauf

Die OAuth-Autorisierung nach OIDC läuft in zwei Stufen ab (Schema "Authorization Code Flow"):

  1. Validiert zum einen den Client gegenüber dem Anmeldedienst (bei Schritt 1) und zum anderen den Benutzer des Clients (bei Schritt 2). Ist beides erfüllt, bekommt der Client einen Authorization Code (Schritt 3)
  2. Client verwendet diesen Authorization Code, um ihn durch das eigentliche Access Token einzutauschen (Schritte 4 und 5).

Dadurch, dass der Authorization Code eingetauscht wird, ist sichergestellt, dass mögliche PIN-Angaben im Browser (in Schritt 2) dort verbleiben und der Client in Schritt 3 (und folgenden) keine Angaben zur Nutzer-PIN kennt.

Es wird ein klassisches Session-Cookie mitgeführt, um mehrfache Authentifizierungen innerhalb kurzer Zeit zu ermöglichen, ohne sich jedesmal erneut anmelden zu müssen. Erkennt der ZAD ein erhaltenes Session-Cookie, wird sofort ein neuer Authorization Code an den Client zurückgesendet, ohne die Anmeldemaske des ZAD anzuzeigen. Ein explizites Abmelden des Anwenders ist daher auch implementiert, Details dazu siehe unten.

Domains für OIDC-Anfragen

Die Webserver von HIT sind unter der zentralen Domain www.hi-tier.de erreichbar, die mehrere IP-Adressen besitzt. Daher kann ein Webbrowser eines Clients den Authorization Request auf mehreren Servern durchführen, weil die Namensauflösung des DNS mal eine und mal andere IP-Adressen liefern kann. Dadurch kann es passieren, dass eine bestehende autorisierte Sitzung trotz gleichem Domainnamen plötzlich nicht mehr existiert, weil sich intern die IP-Adresse geändert hat. Dies betrifft sowohl den Authorization Request als auch das Anmeldeformular des Zentralen Anmeldedienstes.

Damit der Client sicher nur mit einer IP-Adresse arbeitet, muss dieser mit einer der folgenden Domainnamen arbeiten:

bulletwww1.hi-tier.de
bulletwww2.hi-tier.de
bulletwww3.hi-tier.de
bulletwww4.hi-tier.de

Es ist dringend anzuraten, im Client, der OIDC handhabt, alle genannten Domainnamen zu hinterlegen und bei jedem Authorization Request zufällig eine Domain auszuwählen und in sämtlichen URLs dieser Session zu verwenden.

Der Tokentausch (Authorization Code zum Access Token) muss mit der gleichen ausgewählten Domain wie beim Authorization Request vorgenommen werden. In den Beispielaufrufen der einzelnen Stufen unten ist somit der Platzhalter DOMAIN durch den ausgewählten Domainnamen zu ersetzen.

Systeme

In den folgenden beschriebenen Stufen wird die URI für unser Testsystem angegeben. Für die anderen Systeme lautet die Pfadangabe in der URI wie folgt:

Test https://DOMAIN/HitTest3/zad_oauth/...
Produktionhttps://DOMAIN/HitCom3/zad_oauth/...
Wartung https://DOMAIN/HitWart3/zad_oauth/...
Clone https://DOMAIN/HitClone3/zad_oauth/...

(zum Platzhalter DOMAIN siehe Abschnitt davor)

Eine Eintragung Ihres Clients in eines der Systeme setzt voraus, dass ein Vertreter des Landes in der Bund.-Länder-Arbeitsgruppe Direktzahlungen (BLAG/DZ) die Nutzung von OIDC genehmigt.

Stufe 1: Authorization Code [AUC]

Client-Anfrage an den HIT/ZID-Anmeldedienst mit HTTP GET

Die URI für die Client-Anfrage (Schritt 1) ist https://DOMAIN/HitTest3/zad_oauth/auth_req?querystring

Der querystring besteht aus scope=openid&response_type=code&client_id=XXX&redirect_uri=YYY&state=ZZZ

Die Angaben für scope und response_type sind seitens OIDC verpflichtend und müssen exakt so lauten.

Die client_id und die redirect_uri sind bei der Registrierung Ihres Clients bei uns hinterlegt worden und müssen case-sensitive(!) exakt genauso angegeben werden (natürlich URL-codiert).

Der state ist zur Absicherung der Anfrage gegenüber dem Client notwendig (Schutz vor XSRF) und muss aus den Antworten vom Client extrahiert und abgeglichen werden. Ein Phishing-Aufruf beispielsweise läuft so ins Leere, weil der Client einen ihm nicht (mehr) bekannten state erhält und so die Antwort ignorieren muss.

Optional: nonce. Die Angabe ist eine vom Client mitgegebene Sitzungskennung, um die Anfrage in der Clientanwendung nachverfolgen zu können. Falls der Parameter angegeben wird, wird er durch die Schritte 1 bis 3 durchgeschleift und auch in der Datenbank hinterlegt.

Technisch gesehen wird z.B. aus einer Webanwendung heraus ein Redirect an unseren Autorisierungsendpunkt (Schritt 1) abgesetzt:

HTTP/1.1 302 Found
Location: /HitTest3/zad_oauth/auth_req?
   scope=openid
   &response_type=code
   &client_id=45678R
   &redirect_uri=https%3A%2F%2Fwww.ihr-client.de%2Froute%2Fendpunkt
   &nonce=client.session.id
   &state=xsrf.blocker
Host: www.hi-tier.de

(Location ist eine Zeile, wird hier der Lesbarkeit halber in Zeilen aufgesplittet)

Überprüfung der QueryString-Parameter

Unser Endpunkt überprüft auf Vorhandensein der übergebenen Parameter. Wenn nicht ausreichend, dann wird eine entsprechende JSON-Fehlerantwort gesendet.

OIDC erlaubt weitere Angaben im Authentication Request, von denen manche (z.B. display, prompt, request_uri) von uns unterbunden werden, da sie nicht unterstützt werden. Sie erhalten statt dessen eine JSON-Fehlerantwort.

Zuerst wird die Client-Angabe client_id gegen den HitServer geprüft. Wenn Client unbekannt oder nicht zulässig, dann wird eine entsprechende JSON-Fehlerantwort gesendet (Schritt 3).

Wenn Client gültig, dann wird client_id zusammen mit redirect_uri gegen den HitServer geprüft (Client- und URI-Prüfung geht seitens HitServer nicht in einer Anfrage, daher nacheinander). Wenn Redirect-URI unbekannt oder nicht zulässig, dann wird eine entsprechende JSON-Fehlerantwort gesendet (Schritt 3).

Wenn Client und Redirect-URI gültig, dann wird zusammen mit einem internen Token zur Anmeldemaske des Zentralen Anmeldedienstes weitergeleitet, auf der sich der Nutzer des Clients als HIT/ZID-Anwender authentifizieren muss (Schritt 2).

Schlägt die Anmeldung fehl, kann der Anwender die Anmeldung wie bei der klassischen HIT-Webanwendung wiederholen, bis er angemeldet ist (weiterhin Schritt 2). Kann er sich aufgrund einer falschen PIN nicht anmelden oder ist er gesperrt, muss er über den Knopf "Abbrechen" zu OAuth zurückkehren. In dem Fall wird eine entsprechende JSON-Fehlerantwort gesendet (Schritt 3).

Ist das Passwort eines Nutzers abgelaufen oder muss dieses wegen Neuzuteilung sofort geändert werden, dann wird der Nutzer auf eine Passwort-Änderungsseite weitergeleitet, auf dieser er sich unter Angabe seines bisherigen Passwortes ein neues Passwort vergeben kann. Ist dieser Vorgang erfolgreich, dann ist der Nutzer authorisiert und wird zu OAuth zurückgeleitet.

TODO: evtl. eine automatische Weiterleitung einrichten, wenn der Nutzer nichts unternimmt - der Client wartet sonst "ewig"

Beispiel Fehlerantwort, wenn Client nicht autorisiert (Schritt 3):

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Cache-Control: private
Pragma: no-cache

{
   "error": "invalid_request",
   "error_description": "OAuth-Anmeldung fehlgeschlagen - CLIENT_ID nicht gefunden",
   "nonce": "client.session.id",
   "state": "xsrf.blocker"
}

Erfolgreiche Anmeldung am HIT/ZID-Anmeldedienst

Nach erfolgreicher Anmeldung erzeugt der HitServer auf der selben Datenbankverbindung den Authorization Code für diesen Client und dessen Nutzer.

Die Antwort-URI wird anhand redirect_uri und den QueryString-Parametern code und state zusammengestellt. Mit HTTP-Status 302 ("Moved Temporarily") wird dieser als Antwort über den eingebetteten HTTP-Client oder dem Webbrowser an den Endpunkt des Clients weitergeleitet, der im Parameter code den gewünschten Authorization Code vorfindet (Schritt 3).

Beispiel Fehlerantwort, wenn Client autorisiert, aber Nutzeranmeldung abgebrochen (Schritt 3): es wird ein Redirect an den von Ihnen registrierten Endpunkt veranlasst:

https://www.ihr-client.de/route/endpunkt?
   error=unauthorized_client
   &error_description=Anmeldung+fehlgeschlagen:+Falsche+oder+fehlende+PIN
   &error_hit=224
   &nonce=client.session.id
   &state=xsrf.blocker

Im Schlüssel error_hit erhält man die HIT-Plausinummer(n), die den Fehler auslösten (Semikolon-separierte Liste).

Beispiel Antwort nach erfolgreicher Anmeldung des Nutzers (Schritt 3): es wird ein Redirect an den von Ihnen registrierten Endpunkt veranlasst:

HTTP/1.1 302 Found
Location: https://www.ihr-client.de/route/endpunkt?code=ich.bin.der.lange.kurzlebige.auth.code&nonce=client.session.id&state=xsrf.blocker

An keiner Stelle wird die PIN des Nutzers aus der Anmeldemaske des Zentralen Anmeldedienstes an den Client übermittelt. Da aber der Authorization Code und die PIN über HTTP-Client oder Webbrowser tranferiert wurden, muss dieser im nächsten Schritt ohne diese Clients durch einen Access Token ersetzt werden.

 

Stufe 2: Access Token [ACT]

Client-Anfrage an den HIT/ZID-Anmeldedienst mit HTTP POST

Die URI für die Client-Anfrage (Schritt 4) ist https://DOMAIN/HitTest3/zad_oauth/token

Da eine HTTP POST-Anfrage zwingend ist, enthält der HTTP-Content (nicht die URI) dieser Anfrage einen querystring, der aus  grant_type=authorization_code&code=XXX&redirect_uri=YYY besteht.
Der Content-Type dafür ist application/x-www-form-urlencoded.

Als code wird der in der ersten Stufe erhaltene Authorization Code angegeben. Die redirect_uri ist die selbe, die im ersten Schritt angegeben wurde. Dorthin wird das neu erhaltene Access Token übermittelt.

Der HTTP POST-Request muss autorisiert sein, d.h.

bulletentweder einen HTTP-Header Authorization mit dem Schema Basic und Base64-encodetem client_id:client_secret mitsenden
bulletoder client_id und client_secret als Teil des querystring mitliefern

Letzteres ist laut OAuth zulässig, wenn die Verbindung mit TLS verschlüsselt ist, was sie bei HIT/ZID grundsätzlich ist.

Eine POST-Anfrage mit Authorization-Header (Schritt 4) sähe so aus:

POST /HitTest3/zad_oauth/token HTTP 1.1
Host: www.hi-tier.de
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64base64base64base64base64

grant_type=authorization_code
&code=ich.bin.der.lange.kurzlebige.auth.code
&redirect_uri=https%3A%2F%2Fwww.ihr-client.de%2Froute%2Fendpunkt

Überprüfung der Autorisierung und QueryString-Parameter

Die Angaben der Autorisierung werden geprüft. Im Fehlerfall wird eine entsprechende JSON-Fehlerantwort gesendet (Schritt 5).

Der Parameter grant_type muss authorization_code lauten. Falls nicht, wird eine entsprechende JSON-Fehlerantwort gesendet (Schritt 5).

Wenn soweit korrekt, werden sämtliche Angaben gegen den HitServer geprüft. Bei fehlerhaften Angaben erhält man eine entsprechende JSON-Fehlerantwort (Schritt 5).

Eine Fehlerantwort bei falscher Client-ID (Schritt 5) sähe z.B. so aus:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Cache-Control: private
Pragma: no-cache

{
   "error": "invalid_client",
   "error_description": "Falsche Client-Credentials"
}

Wenn erfolgreich, liefert der HitServer das Access Token ACT, optional das Refresh Token (RET), und für den Payload in Form eines ID-Token die Betriebsnummer und ggf. weitere Angaben je nach Daten-/Rechtefreigabe.

Antwort an anfragenden Client

Aus diesen Angaben wird eine Datenstruktur (=Payload) für ein ID-Token befüllt und als JWT (=JSON Web Token) codiert,
dieses als id_token zusammen mit dem access_token, ggf. dem refresh_token und weiteren Angaben
als JSON-Antwort an den Client zurückgesendet (Schritt 5).

Der Client erhält im ID-Token zusätzlich zu den vorgegebenen Schlüsseln lediglich bnr und mbn, da aus Sicherheitsgründen gegenüber dem HitServer mit einer sehr beschränkten Kompetenz auf der HIT-Datenbank gearbeitet wird. Möchte man mehr Daten zum Betrieb erhalten, dann kann dies unter Zuhilfenahme des Access Token z.B. über unsere REST-Schnittstelle abgefragt werden.

Eine erfolgreiche Antwort auf die Anforderung eines Access Tokens sieht so aus:

HTTP/1.1 200 OK
Cache-Control: private
Pragma: no-cache
Content-Type: application/json; charset=utf-8

{
   "token_type": "Bearer",
   "access_token": "mit.mir.kann.man.sich.bei.HIT.autorisieren",
   "expires_in": 1200,
   "expires_at": 1576760000,
   "refresh_token": "wenn.ACT.abgelaufen.nimm.mich",
   "id_token": "eyJhbGciOiJub25lIn0=.codiertesJWT."
}

Die Angabe expires_at (=Anzahl Sekunden seit Unix Epoch am 01.01.1970 0 Uhr UTC) ist die einzige ausserhalb der OIDC-Spezifikation, korreliert aber direkt mit expires_in: es ist der Zeitpunkt, an dem das ACT abgelaufen sein wird.

ID-Token

Das gelieferte ID-Token (der Payload) enthält in jedem Fall die Standard-OIDC-Claims "iss" (Issuer), "sub" (Subject), "aud" (Audience), "iat" (Issued at), "exp" (Expires at) und wenn vorhanden auch "nonce".

HIT/ZID-spezifisch werden immer "bnr" und "mbn" geliefert und je nach Daten-/Rechte-Freigabe zusätzlich: "typ_betr" (als Array), "name_betr", "adresse_betr". Siehe Formular oben zu den Details.

Nutzung des Access Tokens [ACT]

Der Inhalt von Feld access_token kann nun für die Dauer von expires_in Sekunden als Identifikation, als PIN-Ersatz oder als Session-Key verwendet werden.

Als Identifikation genügt der bloße "Besitz" dieses Tokens - damit lässt sich ein Benutzer eindeutig identifizieren.

Darüber hinaus kann das Token -derzeit nur im Test!- in Kombination mit Betriebsnummer und Mitbenutzerkennung zur Anmeldung verwendet werden.
Beispiel: Login mit Access Token statt PIN

*1:XS:LOGON/BNR15;MELD_WG;TIMEOUT;OI_C_ID;OI_TOKEN:09 000 000 0001;3;1200;45678R;mit.mir.kann.man.sich.bei.HIT.autorisieren

Die Angabe des Clients OI_C_ID ist hierbei zusätzlich erforderlich, um alle von diesem Client zur Betriebsnummer vergebenen Access Token zu löschen, falls jemand mehrmals durch Ausprobieren dieses Token "erraten" möchte. Damit wird verhindert, dass der Betrieb für die PIN-Anmeldung gesperrt wird.

Im REST-Interface von HIT3 gibt des optional die Parameter cid (für die Client ID) und act (für das Access Token), die statt der Angabe einer Nutzer-PIN verwendet werden können. Auf die Angabe des act kann verzichtet werden, wenn das Token als HTTP-Header Authorization und dem Schema Bearer (und nicht als klassisches Basic-Schema) mitgesendet wird.

 

Optionale Stufe: Refresh Token [RET]

Die Clients, die bei der Registrierung (siehe oben) angegeben haben, dass sie ein refresh_token nutzen wollen, erhalten dieses auch in Stufe 2 zusammen mit dem Access Token geliefert.

Das Refresh Token dient dazu, ein abgelaufenes oder auch noch gültiges Access Token zu erneuern.

Client-Anfrage an den HIT/ZID-Anmeldedienst mit HTTP POST

Die URI für die Client-Anfrage (Schritt 4) ist https://DOMAIN/HitTest3/zad_oauth/token

Da eine HTTP POST-Anfrage zwingend ist, enthält der HTTP-Content (nicht die URI) dieser Anfrage einen querystring, der aus  grant_type=refresh_token&refresh_token=XXX&scope=openid besteht.
Der Content-Type dafür ist application/x-www-form-urlencoded.

Der HTTP POST-Request muss autorisiert sein, d.h.

bulletentweder einen HTTP-Header Authorization mit dem Schema Basic und Base64-encodetem client_id:client_secret mitsenden
bulletoder client_id und client_secret als Teil des querystring mitliefern

Letzteres ist laut OAuth zulässig, wenn die Verbindung mit TLS verschlüsselt ist, was sie bei HIT/ZID grundsätzlich ist.

Eine POST-Anfrage mit Authorization-Header (Schritt 4) sähe so aus:

POST /HitTest3/zad_oauth/token HTTP 1.1
Host: www.hi-tier.de
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64base64base64base64base64

grant_type=refresh_token
&scope=openid
&refresh_token=wenn.ACT.abgelaufen.nimm.mich

Überprüfung der Autorisierung und Parameter

Die Angaben der Autorisierung werden geprüft. Im Fehlerfall wird eine entsprechende JSON-Fehlerantwort gesendet (Schritt 5).

Der Parameter grant_type muss refresh_token lauten, auch scope ist vorgegeben. Falls nicht, wird eine entsprechende JSON-Fehlerantwort gesendet (Schritt 5).

Wenn soweit korrekt, werden sämtliche Angaben gegen den HitServer geprüft. Bei fehlerhaften Angaben erhält man eine entsprechende JSON-Fehlerantwort (Schritt 5). Auch, wenn das Refesh Token selbst bereits abgelaufen ist.

Wenn erfolgreich, wird mit dem neuen Access Token (das bisherige wird gelöscht, wenn noch gültig) eine Antwort gebildet.
Weitere Angaben für z.B. ein neues ID-Token werden nicht ermittelt (also kein "frisches" Payload).

Eine Fehlerantwort bei falscher Client-ID (Schritt 5) sähe so aus:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Cache-Control: private
Pragma: no-cache

{
   "error": "invalid_client",
   "error_description": "Falsche Client-Credentials"
}

Antwort an anfragenden Client

Eine einfache JSON-Antwort mit dem neuen Access Token, dem bekannten Refresh Token und dessen Gültigkeitsdauer wird erzeugt und geliefert (Schritt 5).

Beispiel:

HTTP/1.1 200 OK
Cache-Control: private
Pragma: no-cache
Content-Type: application/json; charset=utf-8

{
   "token_type": "Bearer",
   "access_token": "ich.bin.ab.jetzt.zustaendig.fuer.HIT",
   "expires_in": 1200,
   "expires_at": 1576777777,
   "refresh_token": "wenn.ACT.abgelaufen.nimm.mich"
}

Optionale Stufe: Session Logout

Nach erfolgreicher Anmeldung in der Anmeldemaske des Zentralen Anmeldedienstes wird ein klassisches Session-Cookie gesetzt, das einen Nutzer für die nächsten 20 Minuten authentifiziert. Nach einem erfolgreichen Austausch des Authorization Code in ein Access Token ändert sich diese Laufzeit auf die bei der Registrierung des Clients gewünschte Laufzeit des Access Tokens.

Wird in der Zeit, in der die Session besteht, ein neuer Authorization Request versendet, erhält man einen neuen Authorization Code, ohne sich neu anmelden zu müssen. Damit diese Session vorzeitig beendet werden kann, z.B. wenn die Sitzung nicht mehr benötigt wird oder ein anderer Nutzer sich anmelden möchte, gibt es den end_session_endpoint mit der URI: https://DOMAIN/HitTest3/zad_oauth/let_me_go

Die URI besitzt drei Parameter, keiner davon ist zwingend:

bulletid_token_hint: das erhaltende ID-Token kann als Hinweisgeber für eine Sitzung mitgesendet werden, um inbesondere nach Ablauf der Session dennoch geordnet per Redirect zurückkehren zu können
bulletpost_logout_redirect_uri: dies ist das gewünschte Ziel zum Rückkehren per Redirect. Dieses muss angegeben werden, wenn bei der Registrierung mehr als nur ein Rückkehrziel angegeben wurde!
bulletstate: ein für den Client zum Schutz vor XSRF interessanter Status, der durchgeschleift wird. Sollte state nicht zum Client gehören, weil ein Dritter den Logout durchführt, findet der Logout dennoch statt.

Weder das OpenID Connect Front-Channel Logout noch das OpenID Connect Back-Channel Logout sind hier implementiert!

Stimmen Parameter nicht oder passt das ID-Token nicht zur Session oder kann die Weiterleitungs-URI nicht eindeutig bestimmt werden, erhält man eine JSON-Antwort als Fehlermeldung.

 

 

 

..