Zum Inhalt springen

Clientauthentifizierung in Jitterbit App Builder

App Builder kann als OpenID Connect (OIDC)-Autorisierungsserver fungieren. Der Autorisierungsserver ermöglicht es Clientanwendungen, einschließlich anderer Instanzen von App Builder, Benutzer zu authentifizieren. Der OIDC-Anmeldeprozess erzeugt ein Zugriffstoken, das der Clientanwendung ermöglicht, geschützte Ressourcen im Namen des Benutzers zu verwenden. Geschützte Ressourcen umfassen von App Builder gehostete REST- und Webhook-APIs sowie App Builder Connector-Datenquellen.

Protokollunterstützung

Das OIDC-Protokoll wird durch den OpenID Connect Core 1.0-Standard definiert. OIDC ist eine Identitätsebene, die auf dem OAuth 2.0-Autorisierungsframework aufbaut, das durch RFC-6749 definiert wird. Diese Standards beschreiben zusammen:

  • Flows - Ein Flow ist ein Prozess, durch den der Client Identitäts- und Zugriffstokens abruft. Aus diesem Grund werden Flows auch als Grants bezeichnet.
  • Endpoints - Jeder Flow umfasst eine oder mehrere HTTP-Anfragen an bekannte URLs.
  • Scopes - Clientanwendungen können einen oder mehrere Scopes anfordern. Scopes bestimmen, welche Tokens ausgegeben werden (Identität, Aktualisierung), was in diesen Tokens enthalten ist (Claims), und auf welche APIs mit diesen Tokens zugegriffen werden kann.
  • Claims - Wie durch den Standard beschrieben, ist das Identitätstoken grundlegend ein JSON Web Token (JWT). JWTs sind anspruchsbasiert. Der angeforderte Scope bestimmt, welche Claims im Identitätstoken enthalten sind.

Unterstützte Flows

Der App Builder-Autorisierungsserver unterstützt die folgenden grundlegenden OAuth 2.0-Flows:

  • Authorization Code. Der Authorization Code-Flow ermöglicht dem Client, ein Zugriffstoken zu erwerben, das dem Client ermöglicht, geschützte Ressourcen im Namen des Benutzers zu verwenden. Der Authorization Code-Flow ist ein interaktiver Flow: Ein Benutzer muss anwesend sein, um den Authorization Code-Flow zu starten.
  • Client Credentials. Der Client Credentials-Flow ermöglicht der Clientanwendung, ein Zugriffstoken im Namen ihrer selbst zu erwerben. Dies ist ein Server-zu-Server-Flow, der typischerweise als Dienstkonto fungiert.
  • Refresh Token. Der Refresh Token-Flow ermöglicht dem Client, ein neues Zugriffstoken anzufordern, sobald das aktuelle Token abgelaufen ist. Dies wird manchmal als "Offline-Zugriff" bezeichnet. Der Refresh Token-Flow kann in Kombination mit entweder dem Authorization Code- oder Client Credentials-Flow verwendet werden. Der offline_access-Scope ermöglicht den Refresh Token-Flow (siehe unten).

Wie oben erwähnt, wird OIDC auf dem OAuth 2.0-Autorisierungsframework aufgebaut. OIDC nutzt OAuth 2.0-Flows und verwendet den scope-Parameter, um sich für OIDC-spezifische Funktionen anzumelden. Der App Builder-Autorisierungsserver unterstützt die folgenden OIDC-Flows:

  • Authorization Code. Wenn der openid-Scope angegeben ist, ermöglicht der Authorization Code-Flow dem Client, einen Benutzer durch Rückgabe eines zusätzlichen Identitätstokens zu authentifizieren. Zusätzliche Scopes bestimmen, welche Claims im Token enthalten sind.
  • Refresh Token. Der Refresh Token-Flow funktioniert in OIDC genauso wie in OAuth 2.0.

Der Autorisierungsserver unterstützt weder die OIDC Implicit- noch die Hybrid-Flows. Der OAuth 2.0 Client Credentials-Flow ist kein OIDC-Flow.

Der Authorization Code-Flow kann mit oder ohne die Proof Key for Code Exchange (PKCE)-Erweiterung verwendet werden, wie durch RFC-7636 definiert.

Unterstützte Endpoints

Der App Builder-Autorisierungsserver veröffentlicht die folgenden Endpoints:

Endpoint Standard Beschreibung
/connect/authorize RFC-6749 Gibt einen Autorisierungscode aus.
/connect/token RFC-6749 Gibt ein Zugriffstoken aus.
/connect/introspect RFC-7662 Introspektiondes Zugriffstokens.
/connect/userinfo OIDC Core Introspektiondes Identitätstokens.
/.well-known/openid-configuration OIDC Discovery OpenID Connect-Anbieterkonfiguration.

Unterstützte Bereiche

Der App Builder-Autorisierungsserver unterstützt die folgenden Bereiche:

Bereich Beschreibung
openid Gibt ein OIDC-Identitätstoken aus.
profile Bezieht Benutzerprofilansprüche in das Identitätstoken ein.
email Bezieht E-Mail-Adressansprüche in das Identitätstoken ein.
phone Bezieht Telefonnummeransprüche in das Identitätstoken ein.
offline_access Gibt ein Aktualisierungstoken zur Verwendung im Aktualisierungstokenfluss aus.
* Nicht für öffentliche Clients verfügbar
api Autorisiert den Zugriff auf von App Builder gehostete REST-, Webhook- und App Builder Connector-APIs.

Unterstützte Ansprüche

Wie oben erwähnt, ist das Identitätstoken ein anspruchsbasiertes JWT-Token. Der Client kann bestimmen, welche Ansprüche in das Identitätstoken aufgenommen werden, indem er Bereiche angibt.

Bereich Ansprüche
openid sub
profile name, nickname, locale und zoneinfo
email email und email_verified
phone phone_number und phone_number_verified

Eine Beschreibung der einzelnen Ansprüche finden Sie in Abschnitt 5.1 Standard Claims des OIDC-Standards. Alle nicht explizit oben aufgeführten Standardansprüche werden nicht unterstützt.

Konfiguration

Um den Autorisierungsserver zu nutzen, muss der App Builder-Administrator zunächst:

  1. Den Autorisierungsserver aktivieren.
  2. Eine Clientanwendung registrieren.
  3. Die Clientanwendung konfigurieren.

Aktivieren des Autorisierungsservers

Um den Autorisierungsserver zu aktivieren, melden Sie sich zunächst als Administrator bei App Builder an:

  1. Klicken Sie auf den Link IDE.
  2. Klicken Sie auf die Schaltfläche Security Providers.
  3. Suchen Sie im Bereich Security Providers den Sicherheitsanbieter Authorization Server und klicken Sie auf das Symbol Details (Chevron).
  4. Klicken Sie auf die Schaltfläche Edit.
  5. Aktivieren Sie die Option Enabled.
  6. Klicken Sie auf die Schaltfläche Save.

Registrieren einer Clientanwendung

Jede Clientanwendung, die Benutzer authentifizieren oder auf geschützte Ressourcen zugreifen möchte, muss registriert werden. Um eine Clientanwendung zu registrieren, melden Sie sich zunächst als Administrator bei App Builder an und führen Sie dann die folgenden Schritte aus:

  1. Klicken Sie auf den Link IDE.
  2. Klicken Sie auf die Schaltfläche User Management.
  3. Klicken Sie auf die Schaltfläche Clients.
  4. Klicken Sie auf die Schaltfläche +Client, um eine neue Clientanwendung zu registrieren.

  5. Stellen Sie Folgendes bereit:

    • Name: Ein beschreibender, benutzerfreundlicher Name für die Clientanwendung.
    • Description: Eine optionale Beschreibung.
    • User: Wählen Sie das Servicebenutzerkonto aus. Erforderlich für den Client Credentials-Fluss. Sonst leer lassen.
    • Authentication Provider: Wählen Sie einen Provider aus oder lassen Sie das Feld leer.
    • Enabled: Aktivieren oder deaktivieren Sie die Clientanwendung.

  6. Klicken Sie auf die Schaltfläche Save.

  7. (Optional) Klicken Sie auf More, dann Advanced. Das Dialogfeld Advanced Settings wird geöffnet. Es enthält zwei Registerkarten:

    • Properties: Stellen Sie die folgenden Einstellungen nach Bedarf ein:

      • Requires PKCE: Wenn diese Option aktiviert ist, muss der Client die PKCE-Erweiterung verwenden. Dies gilt nur für den Authorization Code-Fluss und ist für öffentliche Clients erforderlich.

      • Public: Wenn diese Option aktiviert ist, ist der Client öffentlich und Geheimnisse können nicht sicher gespeichert werden. Wenn diese Option deaktiviert ist, ist der Client vertraulich und kann Geheimnisse sicher speichern.

    • Token Lifetimes: Geben Sie nach Bedarf Werte für die folgenden Felder ein:

      • Access Token: Ablaufzeit des Zugriffstokens in Minuten. Standard: 60.

      • Refresh Token: Ablaufzeit des Aktualisierungstokens in Minuten. Standard: 20160 (14 Tage).

      • Identity Token: Ablaufzeit des Identitätstokens in Minuten. Standard: 20.

      • Authorization Code: Ablaufzeit des Autorisierungscodes in Minuten. Standard: 5.

Generieren eines Client-Geheimnisses

Die Clientanwendung muss ihre eigenen Anmeldedaten bereitstellen, wenn sie ein Zugriffstoken anfordert. Die Client-Anmeldedaten bestehen aus der Client-ID und einem Client-Geheimnis. Client-Geheimnisse können nur für vertrauliche Clients generiert werden. Der Bereich „Geheimnisse" wird für öffentliche Clients ausgeblendet.

Um einen Client Secret zu generieren:

  1. Klicken Sie im Panel Secrets auf die Schaltfläche +Secret.

  2. Geben Sie Folgendes an:

    • Description: Optionale Beschreibung des Client Secrets.
    • Expires On: Wenn das Secret ablaufen soll, legen Sie das Ablaufdatum und die Uhrzeit fest. Andernfalls lassen Sie dieses Feld leer.

  3. Klicken Sie auf die Schaltfläche Save.

  4. Kopieren Sie die Client ID und das Client Secret.

WARNUNG: Dies ist der einzige Zeitpunkt, zu dem das Secret sichtbar ist.

Client-Redirect-URI registrieren

Wie oben erwähnt, ist der Authorization Code Flow ein interaktiver Flow. In diesem Flow wird der Benutzer zum Authorization Endpoint weitergeleitet. Nachdem der Benutzer sich authentifiziert hat, wird er zur Client-Anwendung zurückgeleitet.

Die Callback-URL der Client-Anwendung wird als „Redirect URI" bezeichnet. Jede Redirect URI muss registriert werden. Client-Redirect-URIs müssen folgende Einschränkungen erfüllen:

  • Die Client-Redirect-URL muss eine absolute URL sein.
  • Die Client-Redirect-URL sollte das HTTPS-Protokoll verwenden. Die Client-Redirect-URL kann jedoch das HTTP-Protokoll verwenden, wenn Sie zu localhost umleiten.
  • Die Client-Redirect-URL kann eine Query-Zeichenkette enthalten.
  • Die Client-Redirect-URL darf kein Fragment enthalten.

Um eine Client-Redirect-URI zu registrieren:

  1. Klicken Sie im Panel Redirects auf die Schaltfläche +URL.
  2. Geben Sie die URL an.
  3. Klicken Sie auf die Schaltfläche Save.

Client-Anwendung konfigurieren

Jede standardskonforme OIDC- oder OAuth 2.0-Client-Anwendung, die den Authorization Code Flow oder den Client Credentials Flow unterstützt, kann den App Builder Authorization Server nutzen. Dies gilt auch für App Builder selbst: Es ist möglich, eine zweite Instanz von App Builder als Client zu konfigurieren.

Um den App Builder Client zu konfigurieren, benötigen Sie:

  • Die Root-URL des App Builder Authorization Servers, z. B. https://example.com/Vinyl.
  • Client ID und Secret (siehe oben)

Melden Sie sich zunächst als Administrator bei der Client-Instanz von App Builder an:

  1. Klicken Sie auf den Link IDE.
  2. Klicken Sie auf die Schaltfläche Security Providers.
  3. Klicken Sie auf die Schaltfläche + Security Provider.

  4. Geben Sie Folgendes an:

    • Name: Name des Security Providers, z. B. App Builder.
    • Type: App Builder / OpenID Connect
    • Show On Login Form: Aktivieren Sie diese Option, um die Anmeldeoption auf dem Anmeldeformular anzuzeigen.
    • User Provisioning: Aktivieren Sie diese Option, um User Provisioning zu aktivieren.

  5. Klicken Sie auf die Schaltfläche Save.

  6. Klicken Sie im Panel Endpoints auf die Schaltfläche +Endpoint.

  7. Geben Sie Folgendes an:

    • Endpoint Type: OpenID Connect Issuer
    • URL: Die Root-URL des App Builder Authorization Servers.

  8. Klicken Sie auf die Schaltfläche Save.

  9. Klicken Sie im Panel Credentials auf die Schaltfläche +Credential.

  10. Geben Sie Folgendes an:

    • Type: Client
    • User Name: Die Client ID (siehe oben).
    • Password: Das Client Secret (siehe oben).

  11. Klicken Sie auf die Schaltfläche Save.

  12. Klicken Sie im Panel Provider auf die Schaltfläche Edit.
  13. Aktivieren Sie die Option Enabled.
  14. Klicken Sie auf die Schaltfläche Save.

Nach Abschluss können sich Benutzer mit dem App Builder Authorization Server bei der Client-Instanz von App Builder anmelden.

Bekannte Einschränkungen

Der App Builder Authorization Server unterstützt Folgendes nicht:

  • User Consent.
  • OIDC Implicit oder Hybrid Flows