Mit einer Verbindung können Sie API-Anmeldedaten für Dienste oder Systeme wie Slack oder Shopify sicher speichern. Um REST-API-Aufrufe im Bot-Builder-Schritt API-Aufruf durchführen oder für automatische Unterstützungsaktionen zu authentifizieren, können Sie eine Verbindung zu einem externen Dienst oder System herstellen. Verbindungen können nur von einem Administrator erstellt werden.
Überblick über Verbindungen
Eine Verbindung unterstützt eine der folgenden API-Authentifizierungsmethoden:
- API-Schlüssel
- Standardauthentifizierung
- Inhaber-Token
- OAuth 2.0
Diese Authentifizierungsmethode bestimmt die Art der in der Verbindung gespeicherten Anmeldedaten. Bei einer Standardauthentifizierungsverbindung werden beispielsweise ein Benutzername und ein Kennwort gespeichert. Nachdem Sie eine Verbindung erstellt haben, können Sie ihren Authentifizierungstyp nicht mehr ändern.
Verschiedene APIs unterstützen unterschiedliche Authentifizierungsmethoden. Die geeignete Authentifizierungsmethode für einen API-Aufruf finden Sie in der Dokumentation der betreffenden API.
HTTP-Header für Authentifizierungstypen
| Authentifizierungstyp | HTTP-Header |
|---|---|
| API-Schlüssel | Wird beim Erstellen der Verbindung festgelegt. Weitere Informationen finden Sie unter HTTP-Header für API-Schlüssel. |
| Standardauthentifizierung |
Authorization: Basic
|
| Inhaber-Token |
Authorization: Bearer
|
| OAuth 2.0 |
Zugriffstoken wird gesendet an den Service in Authorization:
Bearer.
|
Weitere Informationen zur Verwendung einer Verbindung in einem Bot finden Sie unter Verwenden des Schritts „API-Aufruf durchführen“ im Bot-Builder. Weitere Informationen zur Verwendung einer Verbindung in einer Aktion finden Sie unter Erstellen und Verwalten von Aktionen für die automatische Unterstützung.
Erstellen eines OAuth-Clients
Eine OAuth-Verbindung speichert ein OAuth 2.0-Zugriffstoken für einen Dienst oder ein System, z. B. Slack, Shopify oder Zendesk.
Bevor Sie eine Verbindung mit dem Authentifizierungstyp OAuth 2.0 erstellen, müssen Sie einen OAuth-Client konfigurieren. Bei der Konfiguration des OAuth-Clients benötigen Sie die Client-ID, das Client-Geheimnis, die Autorisierungs-URL, die Token-URL und die Zugriffsarten aus der OAuth-Konfigurationsschnittstelle oder dem Admin-Portal des externen Systems. Diese Anmeldedaten werden generiert, wenn Sie die Client-Anwendung (z. B. Zendesk) beim externen System registrieren. Die genauen Schritte hängen vom jeweiligen externen Dienst ab. Geben Sie bei Bedarf die Callback-URL des Clients als "https://zis.zendesk.com/api/services/zis/connections/oauth/callback" an.
- Autorisierungscode
- Client-Anmeldedaten
Der Gewährungstyp „Aktualisierungstoken“ (Update Token) wird für OAuth 2.0-Clients unterstützt, die mit dem Gewährungstyp „Autorisierungscode“ (Authorization Code) erstellt wurden. Wenn die Antwort des Systems auf das Zugriffstoken nicht leere Werte für expires_in und refresh_token enthält, wird das Zugriffstoken automatisch mithilfe des Aktualisierungstokens aktualisiert.
OAuth 2.0-Verbindungen, die mit einem Client erstellt werden, der den Gewährungstyp „Client-Anmeldedaten“ verwendet, können einen Ablaufwert für das Token enthalten. Wenn das Token abläuft, wird in diesen Fällen ein neues Zugriffstoken über denselben OAuth-Client abgerufen.
So erstellen Sie einen OAuth-Client
- Klicken Sie in der Seitenleiste des Admin Centers auf
Apps und Integrationen und dann auf Verbindungen > Verbindungen. - Geben Sie einen Namen für den Client ein. Diesen Namen können Sie nach der Erstellung des Clients nicht mehr ändern.
- Geben Sie die Client-ID ein. Hierbei handelt es sich um eine eindeutige Kennung, die Ihrem OAuth-Client zugewiesen wird, ähnlich einem Benutzernamen für Ihren Client.
- Geben Sie das Client-Geheimnis ein. Dies dient als Kennwort für die Client-Anwendung und stellt das Vertrauen zwischen Zendesk und dem externen System her.
- (Nur bei Gewährungstyp „Autorisierungscode“) Geben Sie die Autorisierungs-URL ein. Dies ist die Server-URL, die zum Erhalt eines Autorisierungscodes verwendet wird.
- Geben Sie die Token-URL ein. Dies ist die URL, die zum Erhalt eines Zugriffstokens verwendet wird.
- Geben Sie eine durch Leerzeichen getrennte Liste von Standard-Scopes ein. Scopes sind Berechtigungen, die angeben, worauf eine Client-Anwendung im Namen des Benutzers zugreifen kann.
- Klicken Sie auf Speichern, um den Client zu erstellen.
Erstellen einer Verbindung
Sie können eine Verbindung im Admin Center auf der Seite „Verbindungen“ erstellen.
So erstellen Sie eine Verbindung
- Klicken Sie in der Seitenleiste des Admin Centers auf Apps und Integrationen und dann auf Verbindungen > OAuth-Clients.
- Klicken Sie auf Verbindung erstellen.
- Wählen Sie einen Authentifizierungstyp aus.
- Geben Sie einen Namen für die Verbindung ein. Nachdem Sie die Verbindung erstellt haben, können Sie diesen Namen nicht mehr ändern.
- Führen Sie einen der folgenden Schritte durch:
- (API-Schlüssel, Basisauthentifizierung, Bearer-Token) Konfigurieren Sie die Authentifizierungsdaten für die Verbindung. Diese Angaben werden von der Verbindung verwendet, um REST-API-Aufrufe an den Dienst oder das System zu authentifizieren.
- (OAuth 2.0) Wählen Sie den zu verwendenden Client aus und geben Sie optional eine durch Leerzeichen getrennte Liste von Scopes ein. Wenn Sie keine Scopes angeben, werden die im OAuth-Client vorgegebenen Standard-Scopes verwendet.
- Geben Sie eine zulässige Domäne für die Verbindung ein. Nachdem Sie die Verbindung erstellt haben, können Sie die zulässige Domäne nicht mehr ändern. Weitere Informationen finden Sie unter Zulässige Domäne.
- Klicken Sie auf Speichern, um die Verbindung zu erstellen.
Nachdem Sie die Verbindung erstellt haben, können Sie ihre Details im Admin Center auf der Seite „Verbindungen“ anzeigen. Weitere Informationen finden Sie unter Managing connections (Englisch).
Zulässige Domäne
Jede Verbindung benötigt einen URL-Hostnamen als zulässige Domäne. Zendesk übergibt die Anmeldedaten der Verbindung nur in API-Aufrufen an diesen Hostnamen. Die Verbindung kann also nicht mit anderen Hostnamen verwendet werden. Das sorgt dafür, dass die Anmeldedaten der Verbindung nicht versehentlich an Unbefugte weitergegeben werden können. Nachdem Sie eine Verbindung erstellt haben, können Sie ihre zulässige Domäne nicht mehr ändern.
Eine Verbindung mit der zulässigen Domäne „api.example.com“ kann beispielsweise nur für API-Aufrufe an den Hostnamen „https://api.example.com“ verwendet werden.
Anforderungen an die zulässige Domäne
Die zulässige Domäne einer Verbindung darf maximal 128 Zeichen enthalten. In diesem Wert enthaltene Subdomänen oder Domänen dürfen maximal 63 Zeichen lang sein. Der Wert muss einen gültigen Domänennamen enthalten.
Eine Verbindung verwendet immer ein https-Schema. Andere Schemas wie ftps werden nicht unterstützt.
Platzhalter in der zulässigen Domäne
Die zulässige Domäne einer Verbindung kann anstelle der Subdomäne einen optionalen Platzhalter (*) enthalten. Auf diese Weise kann die Verbindung für jede Subdomäne der angegebenen Domäne genutzt werden. Über eine Verbindung mit der zulässigen Domäne *.example.com lassen sich also beispielsweise API-Aufrufe an „example.com“ und jede Subdomäne von „example.com“ authentifizieren.
Wenn Sie einen Platzhalter verwenden möchten, müssen Sie als erstes und zweites Zeichen der zulässigen Domäne *. eingeben. Andere Teile des Hostnamens können nicht durch Platzhalter ersetzt werden. Hostnamen mit Platzhaltern wie exam*.com oder my-*.example.com. sind also nicht zulässig.
Platzhalter können nicht allein mit dem Suffix einer öffentlichen Domäne (*.com, *.com.au oder *.myshopify.com) verwendet werden. Eine Aufstellung dieser Suffixe finden Sie in der Liste der öffentlichen Suffixe auf publicsuffix.org.
HTTP-Header für API-Schlüssel
Beim Erstellen einer API-Schlüssel-Verbindung müssen Sie einen HTTP-Header-Namen angeben. In diesem Header übergibt Zendesk den API-Schlüssel, wenn die Verbindung für einen API-Aufruf verwendet wird.
Viele APIs akzeptieren API-Schlüssel in einem angepassten Header. Den geeigneten Header-Namen für einen API-Aufruf finden Sie in der Dokumentation der betreffenden API.
Anforderungen an den Header-Namen
Der Header-Name einer API-Schlüssel-Verbindung darf maximal 128 Zeichen lang sein. Der Header-Name darf nur Buchstaben, Bindestriche (-) und Unterstriche (_) enthalten.
acceptaccept-charsetaccept-encodingaccept-languagecache-controlconnectioncontent-md5cookiedateexpectfromhostif-matchif-modified-sinceif-none-matchif-rangeif-unmodified-sincemax-forwardspragmaproxy-authenticateproxy-authorizationrangeserverreferertetrailertransfer-encodingupgradeuser-agentviawarningwww-authenticate- Header-Namen, die mit diesen Zeichenfolgen beginnen:
x-amz-
x-amzn-x-forwarded-x-zis-