Page Comparison

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

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

Nun wird der Benutzer zur Eingabe der Anmeldeinformationen und zur Zustimmung zu den Berechtigungen in PhoenixII aufgefordert, die von der App angefordert werden. Nach  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:

GET https://myapp.de/login?

code=OTg2OTQxODRhOTEzNTQ2ZDRmMTMyODc4MzhhNjMxNzI0NjMxNTk0OGZlMDIyZTVkYjAwZmIwZTAxZDM3ZWJlMw
&state=12345

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:

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:

Erfolgreiche Antwort

Eine erfolgreiche Antwort vom PhoenixII Server liefert folgende Daten:

{
    "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"
            }
        ]
    }
}

Benutzer-Daten abrufen

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

Der Aufruf hier als Beispiel:

Response-JSON

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.Image Removed

...

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:

Alle Fehlermeldungen:

Bibliotheken die PhoenixII OAuth2 unterstützen

PHP

• PHP-Bibliothek: https://github.com/TobyMaxham/phoenixii-oauth2

• Laravel-Socialte Treiber: https://github.com/TobyMaxham/phoenix-socialite

JAVA

• ---