Mikroapps

Erstellen der HTTP-Integration

Nach dem Identifizieren Ihrer APIs fügen wir nun eine HTTP-Integration zum Mikroappsdienst hinzu.

  1. Wählen Sie auf der Seite Mikroappintegrationen die Option Integration hinzufügen.
  2. Wählen Sie die Option Neue Integration in HTTP-Webdienst erstellen, um Konfigurationsdetails hinzuzufügen.

    HTTP-Kachel

  3. Geben Sie einen Namen für die Integration ein und fügen Sie die zuvor erfasste Basis-URL ein. Die Basis-URL ist der gleichbleibende Teil Ihrer Webadresse, die Sie für diese Integration verwenden.

    Sie können pro Integration nur eine Basis-URL hinzufügen. Wenn Sie weitere Basis-URLs benötigen, müssen Sie eine weitere Integration erstellen.

Hinweis:

Obwohl HTTP und HTTPS als Basis-URL zulässig sind, gilt HTTP als das weniger sichere Verbindungsverfahren und wird wahrscheinlich nicht von Ihnen für Ihre Zielintegrationsanwendung verwendet.

Beispiel:

Name: Asana-Integration

Basis-URL: https://app.asana.com/api/1.0/workspaces/${YOUR_WORKSPACE_ID}

Hinweis:

Ersetzen Sie ${YOUR_WORKSPACE_ID} im Beispiel durch Ihre Workspace-ID (z. B. 419224638481718).

On-Premises-Instanz

Der Mikroappsdienst ermöglicht eine Verbindung mit Ihrem On-Premises-SoR (System of Record). Um eine On-Premises-Verbindung zu erstellen, stellen Sie zunächst eine Verbindung mit der Connectorgerät her. Anschließend führen Sie dieses Verfahren aus, um die Ressourcen-ID zu erfassen und hinzuzufügen. Weitere Informationen finden Sie unter Citrix Coud-Connectorgerät.

  1. Gehen Sie zu Citrix Cloud und melden Sie sich mit Ihren Anmeldeinformationen an.
  2. Nach dem Anmelden in Citrix Cloud wählen Sie Ressourcenstandorte im Menü.
  3. Wählen Sie das Pluszeichen+ und suchen Sie Ihre Mikroappressource in der Liste.
  4. Wählen Sie ID und kopieren Sie die Ressourcen-ID in das Feld Ressourcenstandort von On-Premises-Instanz im Fenster HTTP-Integration hinzufügen.

Ihre On-Premises-Integration ist konfiguriert.

Einrichten der Dienstauthentifizierung

Beim Konfigurieren der Dienstauthentifizierung Ihrer HTTP-Integration haben Sie das Dienstkonto mit Ihrer Zielanwendung eingerichtet und verfügen somit über die nötigen Anmeldeinformationen gemäß den Erfordernissen Ihrer Zielanwendung. Nachdem Ihnen alle nötigen Angaben zur Zielanwendung vorliegen (Anmeldungs- und Sicherheitsangaben, Kennwörter usw.), können Sie mit der Integration des Diensts beginnen.

Wählen Sie eine der folgenden Authentifizierungsmethoden aus:

  • Keine - Es sind keine Anmeldeinformationen erforderlich.
  • Standard - Verwenden Sie Ihren Benutzernamen und das Kennwort der Zielanwendung für die Authentifizierung.
  • NTLM - Die HTTP-Integration verwendet diverse Microsoft-Protokolle, um eine Verbindung über einen Authentifizierungsserver mit NTLM (NT LAN Manager) herzustellen und NTLM-Benutzer über Microsoft Windows-Anmeldeinformationen zu authentifizieren.
  • Bearer - Konfigurieren Sie im Authentifizierungsschema der Zielintegration die Verwendung von Bearertoken, die vom Server nach Empfang einer Anmeldeanforderung generiert werden.
  • OAuth 2.0 - Generieren Sie über das Sicherheitsprotokoll OAuth 2.0 einen Anforderungs-/Autorisierungstoken zum delegierten Zugriff. Eine OAuth 2.0-Implementierung variiert von System zu System, der allgemeine Workflow für OAuth 2.0 funktioniert jedoch wie im Folgenden beschrieben.
  • API-Schlüssel - Authentifizieren Sie einen Benutzer, einen Entwickler oder ein aufrufendes Programm bei einer API.

Hinweis:

Sofern verfügbar, sollten Sie stets OAuth 2.0 zur Dienstauthentifizierung verwenden. OAuth 2.0 stellt sicher, dass Ihre Integration höchste Sicherheitsansprüche mit Ihrer konfigurierten Mikroapp erfüllt.

Führen Sie die folgenden Schritte aus:

  1. Geben Sie die Parameter zur Dienstauthentifizierung für die Integration ein.
  2. (Optional) Wählen Sie für den Gewährungstyp (Grant Type) “Authorization code” die Option Mit Ihrem Dienstkonto anmelden und warten Sie, bis die Anmeldung abgeschlossen ist.
  3. (Optional) Wählen Sie das Optionsfeld Dienstaktionsauthentifizierung und geben Sie Authentifizierungsparameter auf der Dienstaktionsebene ein.

    Wichtig:

    Wenn Sie delegierte Berechtigungen verwenden, haben Sie möglicherweise keinen Vollzugriff. Verwenden Sie in diesem Fall die Option Dienstaktionsauthentifizierung, um sich auf der Dienstaktionsebene zu authentifizieren. Sie können dann zwar die Standardauthentifizierung auf der Dienstebene verwenden, müssen jedoch aus Sicherheitsgründen OAuth 2.0 auf der Dienstaktionsebene verwenden.

  4. Wählen Sie Hinzufügen.

Authentifizierung mit OAuth 2.0

OAuth 2.0 gewährt Anwendungen Zugriff auf spezielle HTTP-Dienstbenutzerkonten in Drittanbieteranwendungen. Die Authentifizierung wird an den Dienst delegiert, der das Benutzerkonto enthält. Anschließend werden Drittanbieteranwendungen autorisiert, auf dieses Benutzerkonto zuzugreifen.

OAuth-Callback-URLs

Callback-URLs für die Authentifizierung folgen diesem Muster:

https://{customer_id}.{customer_geo}.iws.cloud.com/admin/api/gwsc/auth/serverContext,
https://{customer_id}.{customer_geo}.iws.cloud.com/app/api/auth/serviceAction/callback

Der zweite Teil der URL wird nur verwendet, wenn authentifizierte Aktionen pro Benutzer definiert werden. Kunden-ID und geografische Kennung sind variabel und für jeden Kunden eindeutig.

Gewährungstypen von OAuth 2.0

In der HTTP-Integration stehen drei Gewährungstypen zur Auswahl. Wählen Sie den gewünschten Gewährungstyp beim Einrichten von OAuth 2.0 im Menü aus. Wir empfehlen, beim Konfigurieren von OAuth 2.0 den Typ “Authorization Code” zu verwenden, da dies den sichersten Genehmigungsfluss bietet. Verwenden Sie die Gewährungstypen “Client Credential” und “Resource Owner Password”, wenn Sie sie für zusätzliche Authentifizierungsmethoden für Dienstaktionen benötigen:

  • Authorization Code - Gewähren Sie einen temporären Code, den der Client gegen einen Zugriffstoken tauscht. Der Code wird vom Autorisierungsserver abgerufen, wo Sie die vom Client angeforderten Informationen sehen. Nur dieser Gewährungstyp ermöglicht einen sicheren Benutzeridentitätswechsel.
  • Client Credentials - Diese Form der Autorisierungsgewährung wird eingesetzt, um einen Zugriffstoken außerhalb des Kontexts eines Benutzers zu erhalten. Dies wird von Clients verwendet, um auf eigene Ressourcen und nicht auf die Ressourcen eines Benutzers zuzugreifen.
  • Resource Owner Password - Stellen Sie die korrekten Anmeldeinformationen zur Vergabe eines Zugriffstoken durch den Ressourcenserver bereit.

Eingaben des Gewährungstyps

Je nach oben definiertem Gewährungstyp stehen Ihnen folgende Optionen zur Verfügung, um die OAuth 2.0-Authentifizierung durchzuführen:

  • Token-URL - Definieren Sie die URL des autorisierenden Zugriffstoken.
  • Bereich - Definieren Sie den Bereich der Zugriffsanforderung. Diese Zeichenfolge wird vom Autorisierungsserver beim Einrichten Ihrer Zielintegrationsanwendung festgelegt.
  • Client-ID - Definieren Sie die Zeichenfolge, die die eindeutigen Angaben des Autorisierungsservers zur Clientregistrierung darstellt.
  • Geheimer Clientschlüssel - Definieren Sie die eindeutige Zeichenfolge, die beim Einrichten der Zielanwendungsintegration ausgegeben wird.
  • Benutzername - Definieren Sie den Benutzernamen Ihres Zielanwendungskontos.
  • Kennwort - Definieren Sie das Kennwort Ihres Zielanwendungskontos.
  • Autorisierungs-URL - Definieren Sie die Autorisierungsserver-URL, die beim Einrichten der Zielanwendungsintegration bereitgestellt wird.
  • Zugriffstokenparameter - Definieren Sie die Zugriffstokenparameter, falls dies für den Autorisierungsserver der Zielanwendung erforderlich ist.
  • Mit Ihrem Dienstkonto anmelden - Melden Sie sich im Dienstkonto des Autorisierungsservers Ihrer Zielanwendung an.
  • Headerpräfix - Geben Sie das Headerpräfix ein, wenn sich Ihr Bearerpräfix vom Standardheader unterscheidet (optional).

Zusätzliche Ressourcen zu OAuth 2.0 finden Sie auf der Seite Anfordern von Fragen von OAuth 2.0.

Problembehandlung von OAuth 2.0

Wenn beim Verbinden Ihrer Zielanwendung mit der Mikroappplattform Probleme auftreten, sollten Sie Ihre Konfiguration auf folgende möglichen Fehler überprüfen:

  • invalid_request - In der Autorisierungsanforderung fehlt möglicherweise ein Parameter, ein Parameterwert (oder anderer Gewährungstyp) wird nicht unterstützt, ein Parameter wird wiederholt, mehrere Anmeldeinformationen sind enthalten, mehrere Verfahren zur Clientauthentifizierung werden verwendet.
  • invalid_client - Ihre Clientauthentifizierung ist aus folgenden Gründen fehlgeschlagen: unbekannter Client, keine Clientauthentifizierung enthalten oder nicht unterstützte Authentifizierungsmethode. Der Autorisierungsserver gibt möglicherweise den HTTP-Statuscode 401 (Unauthorized) zurück, um anzugeben, welche HTTP-Authentifizierungsschemata unterstützt werden.
  • invalid_grant - Die Autorisierungsgenehmigung oder der Aktualisierungstoken sind möglicherweise ungültig, abgelaufen, widerrufen, stimmen nicht mit dem Umleitungs-URI in der Autorisierungsanforderung überein oder wurde für einen anderen Client ausgestellt.
  • unauthorized_client - Der authentifizierte Client ist nicht zur Autorisierung mit diesem Gewährungstyp berechtigt.
  • unsupported_grant_type - Der Gewährungstyp wird vom Autorisierungsserver nicht unterstützt.
  • invalid_scope - Der angeforderte Geltungsbereich ist ungültig, unbekannt, falsch formatiert oder größer als der vom Ressourcenbesitzer genehmigte Bereich.

Wenn beim Konfigurieren von OAuth 2.0 weiterhin Probleme auftreten, überprüfen Sie, ob Sie die richtige URL für Token und Autorisierungs-URL eingegeben haben, da beide eindeutig sind. Überprüfen Sie auch die übrigen Eingaben erneut, z. B. den Geltungsbereich. Wenn die Probleme weiterhin bestehen, überprüfen Sie die Einstellungen auf dem Server der integrierten Anwendung.

Anforderungsratenlimit (optional)

Aktivieren Sie das Anforderungsratenlimit, um die Anzahl an Anforderungen für Ihre Integration zu begrenzen. Wenn diese Option aktiviert ist, können Sie die Anzahl der von der Zielanwendung extrahierten Anforderungen und das Zeitintervall (1 Sekunde oder 1 Minute) definieren. Konfigurieren Sie das Anforderungsratenlimit gemäß den bewährten Methoden/Ratenlimits in der Dokumentation Ihrer Zielanwendung.

Webhook-Listener

Konfigurieren Sie Webhook-Listener (auch HTTP-Push-API genannt), um Endbenutzern Daten Ihrer Mikroapps nahezu in Echtzeit bereitzustellen. Durch Konfigurieren eines Webhooks erfolgt die Datenübertragung von Ihren Apps an andere Anwendungen wesentlich schneller als bei der Synchronisierung durch die Mikroappsplattform. Um Webhook-Listener hinzufügen, müssen Sie mit dem System of Record (SoR) Ihrer Zielanwendung vertraut sein und über die erforderlichen Tools und Administratorrechte verfügen, um Ihre Webhooks an diesen Standorten zu konfigurieren.

Konfigurieren Sie Ihre Webhooks, nachdem Sie die Integration über Daten laden eingerichtet haben und führen Sie folgende Schritte aus:

  1. Klicken Sie in der linken Leiste des HTTP-Integrationsfensters auf Webhook-Listener:

    Webhook-Listener

  2. Geben Sie einen Namen für den Webhook ein.
  3. Wählen Sie Kopieren, um die Webhook-URL zur späteren Verwendung in der Administrationsoberfläche Ihres Ziel-SoR zu kopieren.

Autorisierungsmethode

Als Autorisierungsmethode können Sie entweder Token oder Keine wählen. Führen Sie folgende Schritte aus, um die Autorisierungsmethode Token zu konfigurieren:

  1. Wählen Sie unter Autorisierungsmethode die Option Token.
  2. Wählen Sie Token generieren und dann Kopieren, um den Token später aus der Zwischenablage in der Administrationsoberfläche des Ziel-SoR einzufügen.
  3. Wählen Sie Token lesen aus und wählen Sie aus:
    • Benutzerdefinierter Header
    • Abfrageparameter
    • Autorisierungsheader
  4. Definieren Sie je nach ausgewählter Lesemethode entweder Name oder Präfix.

Der Token ist jetzt eingerichtet.

Definieren der Datenstruktur

Zum Definieren der Datenstruktur können Sie ein ähnliches Verfahren wie beim Abrufen der Datenstruktur während der Konfiguration des Datenladens verwenden. Weitere Informationen finden Sie unter Konfigurieren der Integration.

Führen Sie folgende Schritte aus, um Ihre Webhook-Datenstruktur zu definieren:

  1. Legen Sie den Aufbewahrungszeitraum fest.
  2. Wählen Sie Tabellen generieren.

    Das Fenster Tabellen generieren wird geöffnet.

    Fügen Sie hier Ihre JSON-Beispielanforderung aus dem System of Record (SoR) Ihrer Zielanwendung ein.

  3. Legen Sie den Basisnamen der erstellten Tabellen fest.
  4. (Optional) Legen Sie bei Bedarf den Stammpfad fest.
  5. Wählen Sie Generieren.

Wenn dieser Prozess und die Konfigurationsmaßnahmen in der Administration des System of Record (SoR) der Zielanwendung abgeschlossen sind, wählen Sie Hinzufügen.

Ihr Webhook ist jetzt konfiguriert.

So geht es weiter

Nach dem Erstellen der HTTP-Integration konfigurieren Sie nun die Integration:

Erstellen der HTTP-Integration