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.

   

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. Beispiel: https://app.asana.com/api/1.0/workspaces/${YOUR_WORKSPACE_ID}. Ersetzen Sie ${YOUR_WORKSPACE_ID} durch Ihre Workspace-ID (z. B. 419224638481718).

   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 für SaaS-Integrationen zulässig sind, gilt HTTP als das weniger sichere Verbindungsverfahren. Sie werden es daher wahrscheinlich nicht für Ihre Zielintegrationsanwendung verwenden. On-premises-Integrationen erlauben keine HTTP-Basis-URLs.

4. Wählen Sie ein Symbol für Ihre Integration. Zur Auswahl stehen mehrere vordefinierte Symbole, Sie können aber auch ein eigenes Symbol hinzufügen. Weitere Informationen zum Hinzufügen benutzerdefinierter Symbole finden Sie unter Hinzufügen von benutzerdefinierten Symbolen.
5. (Optional) Um eine Verbindung mit einem On-Premises-SoR (System of Record) herzustellen, aktivieren Sie die Umschaltfläche On-Premises-Instanz. Weitere Informationen finden Sie unter On-Premises-Instanz.
6. Wählen Sie Ihr gewünschtes Verfahren zur Dienstauthentifizierung und zur Dienstaktionsauthentifizierung. Weitere Informationen finden Sie unter Einrichten der Dienstauthentifizierung.
7. (Optional) Aktivieren Sie das Anforderungsratenlimit, um die Anzahl an Anforderungen für Ihre Integration zu begrenzen. Weitere Informationen finden Sie unter Anforderungsratenlimit.
8. Wählen Sie rechts oben die Option Hinzufügen, um diese Integrationskonfigurationen zu speichern. Anschließend fahren Sie mit der Konfiguration der Integration fort. Weitere Informationen finden Sie unter Konfigurieren der Integration.

Hinzufügen von benutzerdefinierten Symbolen

Zum leichteren Identifizieren Ihrer Integrationen können Sie benutzerdefinierte Symbole hinzufügen. Wenn Sie Ihre HTTP-Integration für eine breitere Benutzergruppe veröffentlichen, werden die Symboldateien in den Azure CDN-Speicher hochgeladen und sind öffentlich zugänglich.

Die Symboldatei muss den folgenden Parametern entsprechen:

• Die Datei ist im PNG-Format und hat einen transparenten Hintergrund.
• Die Auflösung der Datei muss genau 128x128 Pixel sein.
• Die maximale Dateigröße beträgt 80 KB.

Hinweis:

Benutzerdefinierte Symbole sind nur in Ihrer Integrationsübersicht verwendbar. Sie können sie nicht an Workspace-Benachrichtigungen weiterleiten.

Um ein Symbol hinzuzufügen, wählen Sie zunächst Symbol hinzufügen und dann die Datei, die Sie hochladen möchten.

Wenn Sie eine Integration exportieren und dann in eine andere Instanz importieren, wird das Symbol der Liste der benutzerdefinierten Symbole in der Zielinstanz hinzugefügt.

Um ein Symbol zu entfernen, wählen Sie das Symbol im Popup “Symbole” und klicken auf Symbol entfernen. Wenn Sie ein Symbol entfernen, wird das Symbol nicht gelöscht. Die Integration enthält einen Link zum Symbol, Sie können das Symbol jedoch nicht erneut auswählen.

On-Premises-Instanz

Der Mikroappsdienst ermöglicht eine Verbindung mit Ihrem On-Premises-SoR (System of Record). On-premises-Integrationen erlauben keine HTTP-Basis-URLs. 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 Cloud-Connectorgerät.

1. Melden Sie sich bei Citrix Cloud mit Ihren Anmeldeinformationen an.
2. Nach dem Anmelden in Citrix Cloud wählen Sie Ressourcenstandorte im Menü links oben.
3. Suchen Sie den gewünschten Ressourcenstandort und wählen Sie das ID-Symbol unter dem Ressourcennamen, um die ID Ihres Ressourcenstandorts anzuzeigen.
4. Kopieren Sie die ID des Ressourcenstandorts.
5. Fügen Sie die Standort-ID im Bildschirm HTTP-Integration hinzufügen in das Feld Ressourcenstandort der On-Premises-Instanz ein.
6. (Optional) Deaktivieren Sie SSL-Zertifikatvalidierung, wenn Ihre Integration nicht signierte Zertifikate akzeptieren soll.

Ihre On-Premises-Integration ist konfiguriert.

Einrichten der Dienstauthentifizierung

Beim Konfigurieren der Dienstauthentifizierung für Ihre HTTP-Integration müssen Sie ein Dienstkonto bei der Zielanwendung (System of Record, SoR) einrichten. Sie müssen zudem Lese- und Schreibrechte für die Zielanwendung besitzen, falls Sie mit dem Dienstkonto Daten in Ihre Anwendung schreiben. 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 folgende 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 aus.

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-Rückruf-URLs

Rückruf-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 vier 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.
• Implicit Flow - Dieser Gewährungstyp wird nur für die Dienstaktionsauthentifizierung und nur im Entwicklermodus angezeigt. Sie können den Antworttyp entweder auf token oder id_tokenfestlegen. Eine automatische Aktualisierung des Zugriffstokens erfolgt nicht. Sie müssen erneut einwilligen, wenn der Zugriffstoken abläuft.

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:

• 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.
• Token-URL - Definieren Sie die URL des autorisierenden Zugriffstoken.
• Aktualisierungstoken-URL - Definieren Sie die Aktualisierungstoken-URL des autorisierenden Zugriffstoken (optional). Wenn nicht festgelegt, wird die Token-URL verwendet.
• 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).
• Mit RelayState können Sie die Authentifizierung so konfigurieren, dass Benutzer auf bestimmte Mikroapps zugreifen können, ohne erneut ihre Anmeldeinformationen einzugeben.

Zusätzliche Ressourcen zu OAuth 2.0 finden Sie auf der Seite Request for questions von OAuth 2.0.

RelayState

RelayState kann nur verwendet werden, wenn folgende Bedingungen erfüllt sind:

• Sie verwenden Okta als Identitätsanbieter.
• Das Ziel-SoR unterstützt Okta als Identitätsanbieter.
• RelayState ist aktiviert und mit der korrekten Okta-URL konfiguriert.

Geben Sie nach dem erfolgreichen Einrichten von Okta die von Okta bereitgestellte URL für SingleSignOnService im Feld der RelayState-Okta-URL für Ihre Integration ein. Beispiel: https://{your Okta}.okta.com/app/{SoR ID}/{ID}/sso/saml.

RelayState funktioniert nur mit Benutzeraktionen und nicht mit einer vollständigen/inkrementellen Synchronisierung. Es werden nur Anmeldeinformationen von Endbenutzern weitergeleitet. Bei einigen SoRs müssen Endbenutzer eine Zustimmungsseite bestätigen. Diese Anforderung bleibt auch bei konfiguriertem RelayState bestehen.

Weitere Informationen zum Konfigurieren von Okta finden Sie in der offiziellen Dokumentation von Okta. Hinweise zum Konfigurieren von Okta in Salesforce finden Sie beispielsweise unter How to Configure SAML 2.0 for Salesforce.

Problembehandlung von OAuth 2.0

Wenn beim Verbinden Ihrer Zielanwendung mit der Mikroappsplattform 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.

So geht es weiter

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

• Konfigurieren der Integration