/
13.2 OAuth 2 - Schnittstelle

13.2 OAuth 2 - Schnittstelle

Owned by Sven Wolter
Last updated: yesterday at 1:11 pm by Sven Wolter
3 min read

Hier ist die überarbeitete Version des Textes:

OAuth 2.0-Integration in PhoenixII (PII)

PhoenixII nutzt OAuth 2.0, um Webanwendungen und Web-APIs den Zugriff auf Daten in Ihrem PII-Mandanten zu ermöglichen. Der Autorisierungscodefluss, wie in Abschnitt 4.1 der OAuth 2.0-Spezifikation beschrieben, wird für Authentifizierung und Autorisierung verwendet.

Registrierung Ihrer Anwendung in PhoenixII

  1. Anmeldung bei PhoenixII:
    Melden Sie sich in Ihrem PhoenixII-Konto an.

  2. Navigieren zu OAuth2 Clients:

    • Gehen Sie zu „System“ und wählen Sie „OAuth2 Clients“ aus.

    • Klicken Sie auf das „+“-Symbol, um eine neue Anwendung zu registrieren.

  3. Eingabe der Anwendungsdaten:
    Füllen Sie alle mit (*) markierten Felder aus:

    • App Name: Der Name Ihrer Anwendung, der für Endnutzer sichtbar ist.

    • App URL: Die URL der Hauptseite Ihrer Anwendung.

    • App Vendor: Der Name des Anbieters oder Unternehmens, das die Anwendung bereitstellt.

    • App Vendor URL: Die Webseite des Anbieters oder Unternehmens.

    • App Privacy URL: Die URL zu Ihrer Datenschutzerklärung.

    • Redirect URI: Die Basis-URL Ihrer Anwendung, unter der Benutzer sich anmelden können, z. B. https://myapp.de/login.

  4. Abschluss der Registrierung:
    Nach der Registrierung erhalten Sie:

    • Client-ID: Eindeutige Anwendungs-ID für Ihre App.

    • Client-Secret: Ein geheimer Schlüssel für Ihre App.

    • Bearer-Token: Ein einmaliger Token, der bei jeder Anfrage an den PII-Webservice verwendet wird. Notieren Sie diesen Token, da er später nicht mehr angezeigt wird.

Anfordern eines Autorisierungscodes

Der Autorisierungscodefluss startet, indem der Benutzer auf den /oauth2/authorize-Endpunkt weitergeleitet wird. Hier gibt der Client an, welche Berechtigungen benötigt werden.

Beispiel-Anfrage

http

KopierenBearbeiten

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:

Parameter

Erforderlich

Beschreibung

Parameter

Erforderlich

Beschreibung

mandant

Ja

Ihr PII-Mandant.

client_id

Ja

Die Anwendungs-ID, die Ihrer App bei der Registrierung zugewiesen wurde.

response_type

Ja

Muss auf code gesetzt werden.

state

Empfohlen

Ein eindeutiger Wert, um Anfragen zu verifizieren und Angriffe wie „Cross-Site Request Forgery“ zu verhindern.

redirect_uri

Empfohlen

Die registrierte URL, an die Antworten gesendet werden. Muss mit der registrierten URI übereinstimmen.

Antwort nach erfolgreicher Autorisierung

Nach der erfolgreichen Anmeldung leitet PhoenixII den Benutzer zur redirect_uri zurück und fügt folgende Parameter hinzu:

Beispiel:

http

KopierenBearbeiten

GET https://myapp.de/login? code=OTg2OTQxODRhOTEzNTQ2ZDRmMTMyODc4MzhhNjMxNzI0NjMxNTk0OGZlMDIyZTVkYjAwZmIwZTAxZDM3ZWJlMw &state=12345

Parameter

Beschreibung

Parameter

Beschreibung

code

Autorisierungscode, der zur Anforderung eines Zugriffstokens genutzt werden kann.

state

Der ursprüngliche Statuswert aus der Anfrage, um die Authentizität der Antwort zu überprüfen.

Abrufen eines Zugriffstokens

Senden Sie eine POST-Anfrage an den Endpunkt /oauth2/access_token, um den Autorisierungscode gegen ein Zugriffstoken einzutauschen:

Beispiel-Anfrage:

http

KopierenBearbeiten

POST https://{mandant}.it4sport.de/oauth2/access_token Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIU... Content-Type: application/json grant_type=authorization_code &client_id=cc69ef07-6b5d-43c6-bf5d-35a290d198e4 &code=OTg2OTQxODRhOTEzNTQ2ZDRmMTMyODc4MzhhNjMxNzI0NjMxNTk0OGZlMDIyZTVkYjAwZmIwZTAxZDM3ZWJlMw &redirect_uri=https://myapp.de/login &client_secret=zR6cebHdJFTZ6yI+jsAErcNxIOvMUpgLrTZc4AYL9UQ=

Header-Parameter:

Parameter

Beschreibung

Parameter

Beschreibung

Authorization

Bearer-Token, der bei der Registrierung generiert wurde.

Content-Type

Muss auf application/json gesetzt werden.

Antwort bei erfolgreicher Tokenanforderung

Beispiel:

KopierenBearbeiten

{ "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", "email": "max@mustermann.de" }, "organisation": { "id": "1", "full_name": "Tricept Verband Württemberg", "short_name": "Tricept AG", "internal_name": "bowb" } } }

Parameter

Beschreibung

Parameter

Beschreibung

access_token

Das Zugriffstoken, das für geschützte Anfragen genutzt wird.

expires_in

Die Gültigkeitsdauer des Tokens in Sekunden.

refresh_token

Token zur Erneuerung abgelaufener Zugriffstokens.

data

Umfasst Benutzer-, Organisations- und Lizenzinformationen.

Abrufen von Benutzer-Daten

Mit dem Zugriffstoken können Sie weitere Benutzerdaten anfordern:

Beispiel:

KopierenBearbeiten

GET https://{mandant}.it4sport.de/api/userinfo Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIU...

Fehlermeldungen bei Zugriff

Wenn der Benutzer den Zugriff verweigert, wird er auf die redirect_uri zurückgeleitet, wobei folgende Parameter übergeben werden:

Parameter

Wert

Beschreibung

Parameter

Wert

Beschreibung

error

access_denied

Art des Fehlers.

error_code

200

Fehlercode.

error_reason

user_denied

Grund des Fehlers.

Benötigen Sie Unterstützung bei der Implementierung, können Sie auf Bibliotheken wie die folgenden zurückgreifen: