Zum Hauptinhalt springen

OpenID Connect

OpenID Connect ermöglicht es Nutzern, externen Anwendungen auf sichere Weise Zugriff auf Ressourcen in Yggio zu gewähren.

Yggio unterstützt OpenID Connect mit Authorization Code Flow, was voraussetzt, dass Ihre Anwendung über ein Backend verfügt.

Um OpenID Connect zu verwenden, müssen Sie über die Yggio-REST-API eine RP (Relying Party) erstellen. RP ist die Bezeichnung für eine Anwendung in der OpenID-Connect-Spezifikation. Es ist wichtig, dass Sie das erstellte Secret speichern, um es in Ihrem Anwendungs-Backend zu verwenden. Es gibt keine Möglichkeit, Ihr Secret aus Yggio wiederherzustellen, wenn Sie es verlieren – die einzige Lösung ist dann, eine neue RP zu erstellen.

Werfen Sie gerne einen Blick auf das Yggio-Service-Beispiel, um eine funktionierende Implementierung zu sehen.

Verwendung des OpenID-Connectors von Yggio in Ihrer Anwendung​

Unten ist ein Sequenzdiagramm, das den OpenID-Connect-Prozess zeigt, gefolgt von einer ausführlichen Beschreibung der Schritte.

oauth

1. Erfassen Sie die clientId und redirectUri der zuvor erstellten RP, die URL des Autorisierungsendpunkts sowie den gewünschten Scope.
Die URL und die unterstützten Scopes finden Sie durch eine Anfrage an auth/endpoints.
Nachdem Sie das oben Genannte erfasst haben, leiten Sie den Nutzer mit den Variablen als Query-Parametern zum Autorisierungsendpunkt weiter. Optional kann auch ein state-Parameter gesendet werden, um CSRF-Angriffe abzuschwächen.

<authorizationEndpoint>?client_id=<clientId>&redirect_uri=>redirectUri>&response_type=code&scope=<scope>&state=<state>

2. Die Weiterleitung führt den Nutzer zu einer Anmeldeseite, auf der er seinen Benutzernamen und sein Passwort eingeben und sich anmelden kann. Dieser Schritt wird übersprungen, wenn der Nutzer bereits angemeldet ist.

3. Der Nutzer gelangt auf eine Seite, auf der er wählen kann, ob er der Anwendung den Zugriff auf sein Konto erlaubt oder verweigert. Wenn der Nutzer auf „Allow“ klickt, wird er zusammen mit einem generierten code und dem oben verwendeten state zur redirectUri weitergeleitet. Der state sollte vor der Annahme des Codes überprüft werden. <redirectUri>?code=<code>&state=<state>

4. Die Anwendung kann nun eine POST-Anfrage an den Token-Endpunkt senden (kann über auth/endpoints abgerufen werden). Diese Anfrage sollte Folgendes enthalten:

headers: {
  'content-type': 'application/x-www-form-urlencoded'
},
data: {
  client_id: <clientId>,
  client_secret: <clientSecret>,
  code: <code>,
  grant_type: 'authorization_code',
  redirect_uri: <redirectUri>
}

Die Antwort sollte diese Werte enthalten (id_token wird nur angezeigt, wenn es als Scope angefordert wurde):

{
  access_token,
  expires_in,
  refresh_expires_in,
  refresh_token,
  token_type: 'bearer',
  id_token,
  'not-before-policy',
  session_state,
  scope
}

wobei access_token, refresh_token und id_token jeweils JWTs (JSON Web Token) sind

5. Der Autorisierungsprozess ist nun abgeschlossen. Die Tokens und Daten sollten gespeichert werden, damit sie wiederverwendet werden können. Das access_token wird als Autorisierungsheader in Anfragen an die Yggio-REST-API verwendet. So:

Authorization: Bearer <access_token>

Das id_token kann zur Authentifizierung des Nutzers verwendet werden, und das refresh_token dient zur Erneuerung des Access Tokens. Siehe den folgenden Abschnitt.

Erneuern des Access Tokens​

Das Access Token ist nur 30 Tage gültig. Um zu vermeiden, dass der Nutzer sich erneut anmelden muss, können Sie das Access Token des Nutzers erneuern.

Um das Access Token zu erneuern, sendet die Anwendung dieselbe Anfrage wie in Schritt 4, mit der Ausnahme, dass die Daten stattdessen Folgendes enthalten:

  {
    client_id: <clientId>,
    client_secret: <clientSecret>,
    grant_type: 'refresh_token',
    refresh_token: <refresh_token>
  }