Verwenden der OAuth-Authentifizierung für Ihre Anwendung

Welchen Plan habe ich?

Direktzugriff: Admin Center > Apps und Integrationen > APIs > Zendesk-API

Sie können OAuth 2 verwenden, um alle von Ihrer Anwendung an Zendesk gesendeten API-Aufrufe zu authentifizieren. OAuth bietet eine sichere Methode zum Zugriff auf Zendesk-Daten, ohne dass die Kennwörter von Zendesk-Benutzern (vertrauliche Informationen) gespeichert und verwendet werden müssen.

Bevor Sie die OAuth-Authentifizierung verwenden können, müssen Sie Ihre Anwendung bei Zendesk registrieren. Sie müssen außerdem bestimmte Funktionen zu Ihrer Anwendung hinzufügen, damit der OAuth-Autorisierungsflow unterstützt wird.

Im vorliegenden Beitrag behandelte Themen:

• Registrieren Ihrer Anwendung bei Zendesk
• Implementieren eines OAuth-Autorisierungsflows in Ihrer Anwendung

Verwandte Themen:

• Ein Tutorial zur Erstellung einer Webanwendung, die einen Workflow zur OAuth-Autorisierung einsetzt, finden Sie unter Building an OAuth web app (Englisch).
• Weitere Informationen zur Implementierung eines OAuth-Authentifizierungsflusses in Zendesk-Apps finden Sie unter Adding third-party OAuth to a Support app (Englisch).
• Auch wenn es nicht erforderlich ist, dass Benutzer Ihrer Anwendung Zugriff auf ihre Konten gewähren, können Sie OAuth-Token zur Authentifizierung von API-Anforderungen verwenden. Weitere Informationen finden Sie unter Creating and using OAuth tokens with the API (Englisch).

Registrieren Ihrer Anwendung bei Zendesk

Sie müssen Ihre Anwendung registrieren, um OAuth-Credentials zu generieren, mit denen Ihre Anwendung API-Aufrufe an Zendesk authentifizieren kann.

Hinweis: In diesem Abschnitt wird die Einrichtung eines OAuth-Clients für die Benutzer eines einzigen Zendesk-Kontos beschrieben. Wenn Ihre Anwendung mit mehreren Zendesk-Konten interagiert, können Sie einen globalen OAuth-Client anfordern. Ein globaler OAuth-Client ist eine Methode zur API-Authentifizierung bei mehreren Zendesk-Instanzen, die mehr Sicherheit und Klarheit bietet. Weitere Informationen finden Sie unter Set up a global OAuth client (Englisch).

So registrieren Sie Ihre Anwendung

1. Klicken Sie in der Seitenleiste des Admin Centers auf Apps und Integrationen und dann auf APIs > Zendesk-API.
2. Klicken Sie auf der Zendesk-API-Seite auf OAuth Clients und dann oben rechts in der OAuth-Clientliste auf OAuth Client hinzufügen.
3. Füllen Sie die folgenden Felder aus, um einen Client zu erstellen:
   • Name – Geben Sie einen Namen für Ihre Anwendung ein. Dies ist der Name, den Benutzer sehen, wenn sie gebeten werden, Ihrer Anwendung Zugriff zu gewähren, oder wenn sie die Liste der Anwendungen von Drittanbietern durchsehen, die Zugriff auf ihren Zendesk besitzen.
   • Beschreibung – Optional. Dies ist eine kurze Beschreibung Ihrer Anwendung, die Benutzer sehen, wenn sie gebeten werden, Ihrer Anwendung Zugriff zu gewähren.
   • Firma – Optional. Dies ist der Firmenname, den Benutzer sehen, wenn sie gebeten werden, Ihrer Anwendung Zugriff zu gewähren. An diesem Namen können sie erkennen, wem sie Zugriff gewähren.
   • Logo – Optional. Dies ist das Logo, das Benutzer sehen, wenn sie gebeten werden, Ihrer Anwendung Zugriff zu gewähren. Unterstützte Bildformate: JPG, GIF und PNG. Die besten Ergebnisse ergeben sich bei einem quadratischen Bild. Es wird automatisch skaliert, damit es auf der Autorisierungsseite in der richtigen Größe erscheint.
   • Eindeutige Kennung – Das Feld wird automatisch mit einer umformatierten Version des Namens gefüllt, den Sie für Ihre Anwendung eingegeben haben. Sie können ihn bei Bedarf ändern.
   • Art von Client – Öffentlich oder Vertraulich. Öffentliche OAuth-Clients sind Anwendungen, die in Umgebungen wie Mobilgeräte- oder Web-Apps ausgeführt werden, in denen Anmeldedaten nicht sicher gespeichert werden können. Diese Clients müssen PKCE verwenden. Vertrauliche OAuth-Clients werden auf sicheren Servern ausgeführt, auf denen Anmeldedaten sicher aufbewahrt werden. Diese Clients können PKCE und/oder ein Client-Geheimnis verwenden. Weitere Informationen finden Sie unter Arten von OAuth-Clients.
   • Weiterleitungs-URLs – Geben Sie die URL oder URLs ein, die Zendesk verwenden soll, um die Entscheidung des Benutzers weiterzuleiten, ob Ihrer Anwendung Zugriff gewährt werden soll. Die URLs müssen absolut sein, nicht relativ, mit „https“ beginnen (es sei denn, Sie verwenden „localhost“ oder „127.0.0.1“) und durch ein Zeilenumbruchzeichen getrennt sein.
4. Klicken Sie auf Speichern.

   Nach Aktualisierung der Seite erscheint unten das Feld Geheimnis mit dem entsprechenden Wert. Dies ist der „client_secret“-Wert aus der OAuth2-Spezifikation.

5. Kopieren Sie den Wert aus dem Feld Geheimnis in die Zwischenablage und bewahren Sie ihn sicher auf. Hinweis: Der Wert ist u. U. so lang, dass er die Breite des Textfelds überschreitet. Achten Sie darauf, dass Sie vor dem Kopieren den gesamten Wert auswählen.
   Wichtig: Aus Sicherheitsgründen wird das Geheimnis nur einmal ganz angezeigt. Nachdem Sie auf Speichern geklickt haben, sehen Sie nur noch die ersten neun Zeichen.
6. Klicken Sie auf Speichern.

Verwenden Sie die eindeutige Kennung und den Geheimniswert in Ihrer Anwendung (siehe weiter unten).

Arten von OAuth-Clients

Zendesk OAuth-Clients haben eine kind-Eigenschaft, die beim Erstellen des OAuth-Clients übergeben wird und einen der folgenden Werte aufweisen kann:

• Public: Öffentliche OAuth-Clients sind Anwendungen, die in Umgebungen wie Mobilgeräte- oder Web-Apps ausgeführt werden, in denen Anmeldedaten nicht sicher gespeichert werden können. Diese Clients müssen PKCE verwenden.
• Confidential: Vertrauliche OAuth-Clients werden auf sicheren Servern ausgeführt, auf denen Anmeldedaten sicher aufbewahrt werden. Diese Clients können PKCE und/oder ein Client-Geheimnis verwenden.

Weitere Informationen finden Sie unter Arten von Clients.

Der Zendesk OAuth Client-Typ gilt nur für das Zendesk Support-Ticketsystem. In Chat, Conversations und Sell wird er nicht unterstützt.

Bei vorhandenen Zendesk OAuth-Clients ist die kind-Eigenschaft derzeit auf unknown eingestellt. Diese Clients bleiben unberührt, bis die kind-Eigenschaft aktualisiert und entweder auf public oder auf confidential eingestellt wird. Beim Erstellen neuer OAuth-Clients im Admin Center muss die kind-Eigenschaft festgelegt werden.

Hinweis: Wenn Sie einen vorhandenen Zendesk OAuth-Client verwenden und die kind-Eigenschaft auf public setzen möchten, müssen Sie zuerst PKCE implementieren. Andernfalls funktioniert der Client nicht, da PKCE zwingend erforderlich ist.

Beim Erstellen neuer OAuth-Clients im Admin Center muss die kind-Eigenschaft festgelegt werden. Obwohl die kind-Eigenschaft für OAuth-Clients, die mit dem Endpunkt api/v2/oauth/clients endpoint erstellt werden, nicht erforderlich ist, empfiehlt Zendesk, sie auch in diesem Fall zu verwenden.

Implementieren eines OAuth-Autorisierungsflows in Ihrer Anwendung

Zendesk unterstützt den Flow „Authorization Code Grant“, um Zugriffstoken zu erhalten. Dieser Flow heißt „Authorization Code Grant“, weil Sie einen Autorisierungscode benötigen, um ein Zugriffstoken anfordern zu können. Andere Grant Flows sind inzwischen eingestellt.

Der Flow verwendet keine Refresh-Tokens. Das Zugriffstoken hat kein Ablaufdatum.

Zur Implementierung des Flows „Authorization Code Grant“ müssen Sie die folgenden Funktionen zur Ihrer Anwendung hinzufügen:

• Schritt 1 – Benutzer zur Zendesk-Autorisierungsseite weiterleiten
• Schritt 2 – Autorisierungsentscheidung des Benutzers verarbeiten
• Schritt 3 – Zugriffstoken von Zendesk anfordern
• Schritt 4 – Zugriffstoken in API-Aufrufen verwenden

Ein Tutorial zur Erstellung einer Webanwendung, die einen Workflow zur OAuth-Autorisierung einsetzt, finden Sie unter Building an OAuth web app (Englisch).

Die Methode „Authorization Code Grant“ unterstützt den Proof Key for Code Exchange (PKCE), der eine zusätzliche Sicherheitsebene bereitstellt. Weitere Informationen finden Sie in der Dokumentation für Entwickler unter Using PKCE to make Zendesk OAuth access tokens more secure (Englisch).

Schritt 1 – Benutzer zur Zendesk-Autorisierungsseite weiterleiten

Zuerst muss Ihre Anwendung den Benutzer zur Zendesk-Autorisierungsseite weiterleiten. Dort wird der Benutzer gebeten, Ihrer Anwendung die Genehmigung zu erteilen, in seinem Namen auf Zendesk zuzugreifen. Nachdem der Benutzer eine Wahl getroffen hat, sendet Zendesk die Entscheidung zusammen mit anderen Informationen zurück an Ihre Anwendung.

So leiten Sie den Benutzer zur Zendesk-Autorisierungsseite weiter

Fügen Sie in Ihrer Anwendung einen Link oder eine Schaltfläche hinzu, durch den/die der Benutzer zur folgenden URL weitergeleitet wird:

https://{subdomain}.zendesk.com/oauth/authorizations/new

wobei {subdomain} Ihre Zendesk-Subdomäne ist. Sie können entweder eine POST- oder GET-Anforderung verwenden. Geben Sie die folgenden Parameter an:

• response_type – Erforderlich. Da Zendesk in der Antwort einen Autorisierungscode zurückgibt, müssen Sie im Parameter „response_type“ den Wert code angeben. Beispiel: response_type=code.
• redirect_uri – Erforderlich. Die URL, die Zendesk verwenden soll, um die Entscheidung des Benutzers weiterzuleiten, ob Ihrer Anwendung Zugriff gewährt werden soll. Die URL muss absolut sein, nicht relativ, und durch https gesichert, es sei denn, Sie verwenden „localhost“ oder „127.0.0.1“.
• client_id – Erforderlich. Die eindeutige Kennung, die Sie beim Registrieren Ihrer Anwendung bei Zendesk erhielten. Siehe weiter oben.
• scope – Erforderlich. Eine durch Leerzeichen getrennte Liste von Zugriffsarten, die den Zugriff auf die Zendesk-Ressourcen steuern. Sie können die Zugriffsart read, write oder impersonate für alle Ressourcen oder für bestimmte Ressourcen anfordern. Weitere Informationen finden Sie unter Festlegen der Zugriffsart.
• state – Eine willkürliche Zeichenfolge, die nach der Entscheidung des Benutzers, ob der Anwendung Zugriff gewährt werden soll, in der Antwort von Zendesk übergeben wird. Mit diesem Parameter können Sie sich vor CSRF-Angriffen schützen. Bei einem CSRF-Angriff wird der Endbenutzer zum Klicken auf einen Link verleitet, durch den eine Aktion in einer Webanwendung ausgelöst wird, bei der der Endbenutzer bereits authentifiziert ist. Um Angriffe dieser Art zu verhindern, fügen Sie einen beliebigen Wert zum Parameter state hinzu und validieren ihn, wenn Sie die Antwort erhalten.
• code_challenge – In Verbindung mit PKCE erforderlich. Eine Zeichenfolge, die eine von einem Code-Verifizierer abgeleitete Code-Challenge darstellt. Weitere Informationen finden Sie in der Dokumentation für Entwickler unter Generating the code_challenge value (Englisch).
• code_challenge_method – In Verbindung mit PKCE erforderlich. Die für die Ableitung der Code-Challenge verwendete Methode. Geben Sie "S256" als Wert an.

Stellen Sie sicher, dass die Parameter URL-codiert sind.

Beispiel für eine GET-Anforderung

https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20write

Die Zendesk-Autorisierungsseite wird im Browser des Endbenutzers geöffnet. Nachdem der Benutzer eine Entscheidung getroffen hat, sendet Zendesk die Entscheidung an die in der Anforderung angegebene Weiterleitungs-URL.

Festlegen der Zugriffsart

Sie müssen eine Zugriffsart angeben, um den Zugriff der Anwendung auf Zendesk-Ressourcen zu steuern. Die Zugriffsart read gewährt einer Anwendung Zugriff auf GET-Endpunkte, einschließlich der Berechtigung zum Sideloaden zugehöriger Ressourcen. Die Zugriffsart write gewährt einer Anwendung Zugriff auf POST-, PUT- und DELETE-Endpunkte zum Erstellen, Aktualisieren und Löschen von Ressourcen.

Weitere Informationen zur Zugriffsart finden Sie unter OAuth Tokens for Grant Types (Englisch).

Die Zugriffsart impersonate ermöglicht es einem Zendesk-Administrator, Anforderungen im Namen von Endbenutzern durchzuführen. Weitere Informationen finden Sie unter Making API requests on behalf of end users (Englisch).

Der folgende Parameter gewährt einer Anwendung beispielsweise Lesezugriff auf alle Ressourcen:

"scope": "read"

Der folgende Parameter gewährt Lese- und Schreibzugriff auf alle Ressourcen:

"scope": "read write"

Bei Bedarf können Sie den Zugriff auf folgende Ressourcen beschränken:

• Tickets
• Benutzer
• auditlogs (nur Lesezugriff)
• organizations
• hc
• apps
• Auslöser
• Automatisierungen
• Ziele
• webhooks
• zis

Die Syntax lautet wie folgt:

"scope": "resource:scope"

Der folgende Parameter beschränkt den Zugriff einer Anwendung auf das Lesen von Tickets:

"scope": "tickets:read"

Um einer Anwendung Lese- und Schreibzugriff auf eine Ressource zu gewähren, geben Sie beide Zugriffsarten an:

"scope": "users:read users:write"

Um einer Anwendung Schreibzugriff auf eine bestimmte Ressource (wie z. B. Organisationen) und Lesezugriff auf alle anderen Ressourcen zu gewähren, geben Sie Folgendes an:

"scope": "organizations:write read"

Schritt 2 – Autorisierungsentscheidung des Benutzers verarbeiten

Ihre Anwendung muss die Antwort von Zendesk verarbeiten, aus der die Entscheidung des Benutzers hervorgeht. Diese Information ist in URL-Parametern in der Weiterleitungs-URL enthalten.

Wenn der Benutzer der Anwendung Zugriff gewährt hat, enthält die Weiterleitungs-URL einen Autorisierungscode. Beispiel:

{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf

Der Autorisierungscode ist nur 120 Sekunden lang gültig.

Wenn der Benutzer der Anwendung keinen Zugriff gewährt hat, enthält die Weiterleitungs-URL die Parameter error und error_description, damit Sie wissen, dass der Benutzer Ihrer Anwendung den Zugriff verweigert hat:

{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

Mit diesen Werten können Sie den Anwendungsfluss steuern. Wenn die URL den Parameter code enthält, müssen Sie ein Zugriffstoken von Zendesk anfordern (siehe nächster Schritt). Dieses Token muss dann in API-Aufrufen an Zendesk angegeben werden.

Schritt 3 – Zugriffstoken von Zendesk anfordern

Wenn Ihre Anwendung einen Autorisierungscode von Zendesk erhalten hat, weil der Benutzer den Zugriff gewährt hat, kann Ihre Anwendung von Zendesk ein Zugriffstoken anfordern. Senden Sie hierzu eine POST-Anforderung an den folgenden Endpunkt:

https://{subdomain}.zendesk.com/oauth/tokens

Hinweis: Verwechseln Sie diesen Endpunkt nicht mit dem Endpunkt Create Token in der OAuth Tokens-API. Obwohl beide Endpunkte gültige OAuth-Zugriffstoken zurückgeben, unterscheiden sie sich im Hinblick auf Pfad, JSON-Format und Anforderungsparameter.

Geben Sie in der Anforderung die folgenden erforderlichen Parameter an:

• grant_type – Geben Sie als Wert „authorization_code“ an.
• code – Geben Sie den Autorisierungscode an, den Sie von Zendesk erhalten haben, nachdem der Benutzer den Zugriff gewährt hat.
• client_id – Verwenden Sie die eindeutige Kennung, die in einem OAuth-Client in der Support-Administratoroberfläche spezifiziert ist (Admin > Kanäle > API > OAuth-Clients). Weitere Informationen finden Sie unter Registrieren Ihrer Anwendung bei Zendesk.
• client_secret – Verwenden Sie das Geheimnis, das in einem OAuth-Client in der Support-Administratoroberfläche spezifiziert ist (Admin > Kanäle > API > OAuth-Clients). Weitere Informationen finden Sie unter Registrieren Ihrer Anwendung bei Zendesk.

  Wenn Sie die PKCE-Parameter code_challenge und code_verifier verwenden, ist client_secret nicht erforderlich. Sie können diese Eigenschaft als Ersatz für den Flow „Implicit Grant“ verwenden, der aus Sicherheitsgründen nicht mehr empfohlen wird. Weitere Informationen finden Sie in der Dokumentation für Entwickler unter Using PKCE to migrate from the implicit grant flow (Englisch).

• redirect_uri – Dieselbe Weiterleitungs-URL wie in Schritt 1. Nur zu Identifizierungszwecken.
• scope – siehe Festlegen der Zugriffsart.
• code_verifier – In Verbindung mit PKCE erforderlich. Die für das Generieren des Werts code_challenge verwendete Zeichenfolge. Weitere Informationen finden Sie in der Dokumentation für Entwickler unter Generating the code_challenge value (Englisch).

Die Anforderung muss über https gesendet werden und die Eigenschaften müssen JSON-codiert sein. Wenn Sie eine angepasste Anwendung oder eine Anwendung eines Drittanbieters für die API-Anforderung verwenden, entnehmen Sie das richtige Format der Eigenschaftswerte der entsprechenden Dokumentation.

Mit cURL

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "{your_code}",
    "client_id": "{your_client_id}", "client_secret": "{your_client_secret}", 
    "redirect_uri": "{your_redirect_url}", "scope": "read" }' \
  -X POST

Beispielantwort

Status: 200 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "bearer",
  "scope":"read"
}

Schritt 4 – Zugriffstoken in API-Aufrufen verwenden

Die Anwendung kann das Zugriffstoken für API-Aufrufe verwenden. Sie müssen das Token wie folgt in einem HTTP-Autorisierungs-Header angeben:

Authorization: Bearer {a_valid_access_token}

Eine cURL-Anforderung zum Auflisten von Tickets sieht beispielsweise wie folgt aus:

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"