8.2 OAuth 2 - Schnittstelle

PhoenixII (PII) verwendet OAuth 2.0, um Webanwendungen und Web-APIs den Zugriff auf Daten in Ihrem PII-Mandanten zu erhalten. Der OAuth 2.0-Autorisierungscodefluss wird in Abschnitt 4.1 der OAuth 2.0-Spezifikationbeschrieben. Er wird zur Authentifizierung und Autorisierung verwendet.

Registrieren der Anwendung beim PII-Mandanten

Zuerst müssen Sie Ihre Anwendung in den PII Systemeinstellungen Ihres Mandanten registrieren. Hierbei erhalten Sie eine Client-ID, ein Client-Secret sowie einen Bearer-Token für die Anwendung.

  • Melden Sie sich beim PhoenixII an.

  • Klicken Sie anschließend auf das Navigationselement „System“ und dann „OAuth2 Clients“

  • Klicken Sie nun auf das „+“ (Plus) Symbol

  • Geben Sie alle relevanten mit (*) markierten Werte ein

    • App Name ist der Anwendungsname und beschreibt Ihre Anwendung für den Endbenutzer.

    • App URL ist die URL auf die direkte Seite Ihrer Anwendung

    • App Vendor ist der Anbieter oder das Unternehmen der Anwendung

    • App Vendor URL ist die URL auf die Webseite des Anbieters oder des Unternehmens

    • App Privacy URL ist die URL zu Ihrer Datenschutzerklärung

    • Stellen Sie eine Redirect URI bereit. Dies ist die Basis-URL ihrer Anwendung, unter der sich die Benutzer anmelden können. Beispiel: https://myapp.de/login.

  • Nach Abschluss der Registrierung weist PhoenixII Ihrer Anwendung eine eindeutige Client-ID (die Anwendungs-ID) zu. Diesen Wert benötigen Sie in den nächsten Abschnitten.

  • Außerdem wird ein einmaliger „Bearer-Token“ generiert. Diesen müssen Sie sich notieren, da er kein weiteres Mal angezeigt wird. Dieser Token wird für jede Anfrage an den PII-Webservice in Form der Autorisierung Ihrer Nachricht verwenden.

Anfordern eines Autorisierungscodes

Der Autorisierungscodefluss beginnt damit, dass der Client den Benutzer auf den /oauth2/authorize -Endpunkt leitet. In dieser Anforderung gibt der Client die Berechtigungen an, die er vom Benutzer abrufen muss.

Beispiel Endpunkt
1 2 3 4 5 6 GET https://{mandant}.it4sport.de/oauth2/authorize? client_id=cc69ef07-6b5b-43c6-bf5d-35a290d198e4 &response_type=code &state=12345 &redirect_uri=https://myapp.de/login



Parameter



Beschreibung

Parameter



Beschreibung

mandant

required

Gibt den Mandanten an

client_id

required

Die Anwendungs-ID, die Ihrer App zugewiesen wird, wenn Sie sie bei PhoenixII registrieren. Diese finden Sie unter dem Menüpunkt System.

response_type

required

Muss code für den Autorisierungscodefluss enthalten.

state

empfohlen

Ein in der Anforderung enthaltener Wert, der ebenfalls in der Tokenantwort zurückgegeben wird. Ein zufällig generierter eindeutiger Wert wird normalerweise verwendet, um eine falsche Anforderung zu verhindern. Der Status wird auch verwendet, um Informationen über den Status des Benutzers in der App zu codieren, bevor die Authentifizierungsanforderung aufgetreten ist, z. B. Informationen zu der Seite oder Ansicht, die der Benutzer besucht hat.

redirect_uri

empfohlen

Der Umleitungs-URI der App, in dem Authentifizierungsantworten gesendet und von der App empfangen werden kann. Er muss genau mit einer der Umleitungs-URIs übereinstimmen, die Sie im Portal registriert haben, mit dem Unterschied, dass er URL-codiert sein muss.



Nun wird der Benutzer zur Eingabe der Anmeldeinformationen und zur Zustimmung zu den Berechtigungen in PhoenixII aufgefordert, die von der App angefordert werden. Nach der Authentifizierung und der Zustimmung durch den Benutzer versendet  PhoenixII eine Antwort an Ihre App unter der redirect_uri -Adresse in Ihrer Anforderung mit dem Code.

Erfolgreiche Antwort

Eine erfolgreiche Antwort sieht wie folgt aus:

1 2 3 4 GET https://myapp.de/login? code=OTg2OTQxODRhOTEzNTQ2ZDRmMTMyODc4MzhhNjMxNzI0NjMxNTk0OGZlMDIyZTVkYjAwZmIwZTAxZDM3ZWJlMw &state=12345



Parameter

Beschreibung

Parameter

Beschreibung

code

Der Autorisierungscode, den die App angefordert hat. Die Anwendung kann den Autorisierungscode zum Anfordern eines Zugriffstokens für PhoenixII verwenden.

state

Wenn ein Statusparameter in der Anforderung enthalten ist, sollte der gleiche Wert in der Antwort angezeigt werden. Es hat sich bewährt, wenn die Anwendung überprüft, ob die Statuswerte in der Anforderung und in der Antwort identisch sind, bevor die Antwort verwendet wird. Dies trägt zur Erkennung von Angriffen vom Typ „websiteübergreifende Anforderungsfälschung“auf den Client bei.

Fordern Sie ein Zugriffstoken mithilfe des Autorisierungscodes an

Wenn Sie einen Autorisierungscode erworben und die Berechtigung vom Benutzer erhalten haben, können Sie den Code für ein Zugriffstoken auf PhoenixII einlösen, indem Sie eine POST-Anforderung an den oauth2/access_token -Endpunkt senden:



1 2 3 4 5 6 7 8 9 POST https://{mandant}.it4sport.de/oauth2/access_token? Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIU... Content-Type: application/json grant_type=authorization_code &client_id=cc69ef07-6b5b-43c6-bf5d-35a290d198e4 &code=OTg2OTQxODRhOTEzNTQ2ZDRmMTMyODc4MzhhNjMxNzI0NjMxNTk0OGZlMDIyZTVkYjAwZmIwZTAxZDM3ZWJlMw &redirect_uri=https://myapp.de/login &client_secret=zR6cebHdJFTZ6yI+jsAErcNxIOvMUpgLrTZc4AYL9UQ=

Im Header müssen folgende Parameter gesetzt werden:

Parameter

Beschreibung

Parameter

Beschreibung

Authorization

Das ist der Bearer-Token, der Ihnen einmalig angezeigt wird. Als Wert "Bearer" gefolgt von dem Token

Content-Type

Mit dem Wer "application/json"



Parameter



Beschreibung

Parameter



Beschreibung

mandant

required

Gibt den Mandanten an

grant_type

required

Muss authorization_code für diesen Autorisierungscodefluss sein.

client_id

required

Die Anwendungs-ID, die Ihrer App zugewiesen wird, wenn Sie sie bei PhoenixII registrieren. Diese finden Sie unter dem Menüpunkt System.

code

required

Der authorization_code, den Sie im vorherigen Abschnitt abgerufen haben.

redirect_uri

required

Ein redirect_uri für die Clientanwendung registriert.

client_secret

required

Das Anwendungsgeheimnis, das Sie für Ihre App in PhoenixII unter System erstellt haben.

Erfolgreiche Antwort

Eine erfolgreiche Antwort vom PhoenixII Server liefert folgende Daten:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 { "token_type": "Bearer", "expires_in": 1561881711, "access_token": "o9fv9oU6TiYfRijO65WP2TVLyv/CKwh+uliTU769Lao=", "refresh_token": "kOUR6RbdEuYA1Rd8EccflUDlNlnRsk/b0Kvu5Ziw6xQ=", "data": { "id": "8366eb42-ddac-49f9-b0e4-e25164d782d3", "user": { "id": "8366eb42-ddac-49f9-b0e4-e25164d782d3", "firstname": "Max", "lastname": "Mustermann", "birthday": "1987-01-01 00:00:00.000", "email": "max@mustermann.de" }, "organisation": { "id": "1", "full_name": "Tricept Verband Württemberg", "short_name": "Tricept AG", "internal_name": "bowb" }, "licenses": [ { "license_number_dosb": "", "license_number_organisation": "1231 Lizenz Nr.", "license_number_organisation_sf": "567567 WLSB", "first_issue_date": "2019-06-03 00:00:00.000", "issue_date": "2019-06-19 00:00:00.000", "valid_until": "2020-06-30 00:00:00.000", "training_course": "SR-Lizenz", "training_course_short": "SRL" } ], "functions": [ { "id": "96fc343d-01ea-41a9-aca0-9f87f7c9d29f", "function_since": "2019-06-27 00:00:00.000", "function_id": "a1f60eb6-3c11-4a22-84b7-8fe47633194c", "function_name_male": "Lizenzinhaber", "function_name_female": "Lizenzinhaberin" } ] } }



Parameter

Beschreibung

Parameter

Beschreibung

token_type

Gibt den Wert des Tokentyps an. Bearertoken ist der einzige Typ, den PhoenixII unterstützt. Weitere Informationen zu Bearertoken finden Sie unter OAuth 2.0-Autorisierungsframework: Verwendung von Bearertoken (RFC 6750).

expires_in

Gibt den Zeitstempel an, wie lange das Zugriffstoken gültig ist.

access_token

Das angeforderte Zugriffstoken als signiertes JSON-Webtoken (JWT). Die App kann dieses Token zur Authentifizierung auf geschützten Anforderungen verwenden.

refresh_token

Ein Aktualisierungstoken von OAuth2. Die App kann dieses Token verwenden, um nach Ablauf der aktuellen Zugriffstoken zusätzliche Zugriffstoken zu erhalten. Aktualisierungstoken sind langlebig und können verwendet werden, um den Zugriff auf Anfragen für längere Zeit beizubehalten.

data

Unter Data werden alle nötigen Daten, die in Ihrer Anwendung definiert wurden zurückgeliefert.

data.id

Das ist die eindeutige ID des Benutzers in PhoenixII.

data.user

Enthält weitere Daten zu dem angefragten Benutzer.

data.organisation

Enthält Daten zu Ihrem Verband.

data.licenses

Enthält eine Liste von allen Lizenzen die Sie abfragen wollen.

data.functions

Enthält eine Liste von allen Funktionen die Sie abfragen wollen.

Benutzer-Daten abrufen

Mit dem erhaltenen access_token können im Anschluss auch weitere bzw. aktualisierte Personen-Daten nachgeladen werden.

Der Aufruf hier als Beispiel:

Response-JSON
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 GET https://{mandant}.it4sport.de/api/userinfo? Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIU... Content-Type: application/json Response: { "id": "8366eb42-ddac-49f9-b0e4-e25164d782d3", "user": { "id": "8366eb42-ddac-49f9-b0e4-e25164d782d3", "firstname": "Max", "lastname": "Mustermann", "birthday": "1987-01-01 00:00:00.000", "email": "max@mustermann.de" }, "organisation": { "id": "1", "full_name": "Tricept Verband Württemberg", "short_name": "Tricept AG", "internal_name": "bowb" }, "licenses": [ { "license_number_dosb": "", "license_number_organisation": "1231 Lizenz Nr.", "license_number_organisation_sf": "567567 WLSB", "first_issue_date": "2019-06-03 00:00:00.000", "issue_date": "2019-06-19 00:00:00.000", "valid_until": "2020-06-30 00:00:00.000", "training_course": "SR-Lizenz", "training_course_short": "SRL" } ], "functions": [ { "id": "96fc343d-01ea-41a9-aca0-9f87f7c9d29f", "function_since": "2019-06-27 00:00:00.000", "function_id": "a1f60eb6-3c11-4a22-84b7-8fe47633194c", "function_name_male": "Lizenzinhaber", "function_name_female": "Lizenzinhaberin" } ] }

OAuth2 Zugriff zulassen

Der Endbenutzer erhält folgende Ansicht, wenn der Zugriff auf die Daten von PhoenixII angefragt werden.

Abbruch des OAuth2 Zugriffs - Fehler Codes

Der Benutzer kann auf der Zugriffsseite auch auswählen, dass er den Zugriff verweigert oder diese Anfrage abbrechen. In diesen Fällen wird der Benutzer auf die hinterlegte redirect_uri weitergeleitet mit folgenden Parametern:

Parameter

Wert

Beschreibung

Parameter

Wert

Beschreibung

error

access_denied

Gibt die Art des Fehlers an.

error_code

200

Der Fehler Code.

error_description

Permission error

Die Beschreibung des Fehlers.

error_reason

user_denied

Der Grund für den Fehler.



Alle Fehlermeldungen:

error

error_code

error_description

error_reason

error

error_code

error_description

error_reason

access_denied

200

Permission error

user_denied

invalid_request

400

Invalid request. Field `code` is missing.

invalid_request



Bibliotheken die PhoenixII OAuth2 unterstützen

PHP

JAVA

  • ---