Der Single-Sign-On ist ein Mechanismus, über den Sie Benutzer in Ihren Systemen authentifizieren und anschließend Zendesk mitteilen können, dass eine Benutzerauthentifizierung stattgefunden hat. Wenn Sie Single-Sign-On über JSON Web Token (JWT) verwenden, wird ein Benutzer bei der Anmeldung automatisch durch den Identity Provider verifiziert. Der Benutzer kann dann auf Zendesk zugreifen, ohne separate Anmeldeinformationen eingeben zu müssen.
Als Zendesk-Administrator sind Sie für die Aktivierung der SSO-Optionen verantwortlich. In diesem Beitrag wird beschrieben, wie Sie mehrere Konfigurationen für Single-Sign-On über JWT aktivieren, die für die Authentifizierung von Teammitgliedern (Administratoren und Agenten, einschließlich Light Agents und Mitwirkende) und/oder von Endbenutzern verwendet werden können.
Der Single-Sign-On basiert auf einem Sicherheitsmechanismus, der es Zendesk ermöglicht, die von Ihren Systemen empfangenen Anmeldeanforderungen als vertrauenswürdig einzustufen. Zendesk gewährt nur den Benutzern Zugriff, die von Ihnen authentifiziert wurden. Zendesk-SSO verwendet JWT für den sicheren Austausch von Benutzerauthentifizierungsdaten.
- Wie SSO über JWT bei Zendesk funktioniert
- Anforderungen zum Aktivieren von SSO über JWT
- Aktivieren von SSO über JWT
- Zuweisen von SSO über JWT zu Benutzern
- Verwalten von Benutzern in Zendesk nach Aktivieren von SSO über JWT
- Generieren eines neuen Shared Secret
- Wechseln der Authentifizierungsmethode
- Weitere Informationen zu JWT
Normalerweise ist das IT-Team in einem Unternehmen für die Einrichtung und Verwaltung des JWT-Authentifizierungssystems verantwortlich. Es ist seine Aufgabe, SSO für Zendesk im System zu implementieren. Verweisen Sie Ihr IT-Team zum folgenden Abschnitt in diesem Beitrag:
Verwandte Beiträge:
Wie SSO über JWT bei Zendesk funktioniert
Nach Aktivierung von SSO werden Anmeldeanforderungen an eine Anmeldeseite außerhalb von Zendesk weitergeleitet.
Schritte zur JWT-Authentifizierung für SSO:
- Nicht authentifizierte Benutzer werden zu Ihrer Zendesk Support-URL geführt. Beispiel: https://meinesubdomäne.zendesk.com/.
- Der SSO-Mechanismus von Zendesk erkennt, dass SSO aktiviert ist und der Benutzer noch nicht authentifiziert wurde.
- Zendesk versucht zu erkennen, ob es sich bei einem nicht authentifizierten Benutzer um einen Endbenutzer oder ein Teammitglied handelt, und leitet ihn jeweils an die entsprechende Remote-Anmeldeseite Ihres Unternehmens weiter. Beispiel: https://meinefirma.com/zendesk/sso.
- Ein Skript auf dem Remote-Server authentifiziert den Benutzer über den Anmeldeprozess Ihres Unternehmens.
- Das Authentifizierungssystem generiert eine JWT-Anforderung mit den relevanten Benutzerdaten.
- Das Authentifizierungssystem leitet den Benutzer an den folgenden Zendesk-Endpunkt mit der JWT-Payload um:
https://meinesubdomäne.zendesk.com/access/jwt
- Zendesk verifiziert das Token, parst dann die Benutzerdetails in der JWT-Payload und gewährt dem Benutzer eine Sitzung.
Wie Sie sehen, verlässt sich dieser Prozess auf Browserumleitungen und die Übergabe signierter Nachrichten über JWT. Die Umleitungen finden vollständig im Browser statt. Es besteht keine Direktverbindung zwischen Zendesk und Ihren Systemen, sodass Ihre Authentifizierungsskripts hinter Ihrer Unternehmensfirewall bleiben können.
Anforderungen zum Aktivieren von SSO über JWT
Schließen Sie sich mit dem Team in Ihrem Unternehmen kurz, das für das JWT-Authentifizierungssystem zuständig ist (in der Regel das IT-Team), um sicherzustellen, dass der Zendesk-Datenverkehr über HTTPS und nicht über HTTP abgewickelt wird.
- Die Remote-Login-URL, an die Zendesk-Benutzer umgeleitet werden sollen, wenn sie versuchen, auf Zendesk zuzugreifen.
- (Optional) Die Remote-Logout-URL, an die Zendesk Benutzer umleiten soll, nachdem sie sich bei Zendesk abgemeldet haben.
- (Optional) Eine Liste von IP-Bereichen, damit Benutzer an die entsprechende Anmeldeseite umgeleitet werden können. Benutzer, die eine Anforderung von einer Adresse innerhalb der angegebenen IP-Bereiche aus einreichen, werden an das Remote-JWT-Authentifizierungsformular weitergeleitet. Benutzer, die eine Anforderung von einer Adresse außerhalb der angegebenen IP-Bereiche aus einreichen, werden an das normale Zendesk-Anmeldeformular weitergeleitet. Wenn Sie keinen IP-Bereich angeben, werden alle Benutzer an das Remote-Authentifizierungsformular umgeleitet.
Ihr IT-Team benötigt u. U. weitere Informationen von Zendesk zur Konfiguration der JWT-Implementierung. Verweisen Sie Ihr IT-Team an das Worksheet zur technischen Implementierung in diesem Beitrag.
Nachdem Sie sich vergewissert haben, dass Sie die Anforderungen erfüllen und über alle erforderlichen Informationen verfügen, können Sie SSO über JWT aktivieren.
Aktivieren von SSO über JWT
Administratoren können JWT-Single-Sign-On wahlweise nur für Endbenutzer, nur für Teammitglieder (einschließlich Light Agents und Mitwirkende) oder für beide Gruppen aktivieren. Sie können mehrere Konfigurationen für SSO über JWT erstellen. Holen Sie alle benötigten Informationen vom IT-Team Ihres Unternehmens ein, bevor Sie beginnen. Weitere Informationen finden Sie unter Anforderungen zum Aktivieren von SSO über JWT.
So aktivieren Sie den JWT-Single-Sign-On
- Klicken Sie in der Seitenleiste des Admin Centers auf
Konto und dann auf Sicherheit > Single-Sign-On. - Klicken Sie auf SSO-Konfiguration erstellen und dann auf JSON Web Token.
- Geben Sie einen eindeutigen Konfigurationsnamen ein.
- Geben Sie im Feld Remote-Login-URL die URL ein, an Ihre Benutzer umgeleitet werden sollen, wenn sie versuchen, auf Ihre Zendesk-URL zuzugreifen.
Zendesk Support fügt automatisch den Parameter brand_id zur URL hinzu. Dieser Parameter gibt die Marke in Zendesk Support an, in der sich der Benutzer beim Anmeldeversuch befand.
- (Optional) Geben Sie im Feld Remote-Logout-URL eine Logout-URL ein, an die Benutzer nach der Abmeldung bei Zendesk weitergeleitet werden sollen.
Zendesk fügt automatisch die Parameter email, external_id und brand_id zur Logout-URL hinzu. Wenn die E-Mail-Adresse und externe ID nicht in der URL erscheinen sollen, geben Sie in der Logout-URL leere Parameter an. Beispiel:
https://www.xyz.com/user/signout/?email=&external_id=
Hinweis: Wenn Sie eine Ember.js-Anwendung nutzen, müssen Sie in der Logout-URL vor dem Hash-Zeichen leere Parameter verwenden. Beispiel:https://somedomain.com/?brand_id=&return_to=&email=#/zendesk-login/. - (Optional) Geben Sie im Feld IP-Bereiche eine Liste von IP-Bereichen ein, damit Benutzer an die entsprechende Anmeldeseite umgeleitet werden können.
Benutzer, die eine Anforderung von einer Adresse innerhalb der angegebenen IP-Bereiche aus einreichen, werden an das JWT-Authentifizierungsformular weitergeleitet. Benutzer, die eine Anforderung von einer Adresse außerhalb der angegebenen IP-Bereiche aus einreichen, werden an das normale Zendesk-Anmeldeformular weitergeleitet. Wenn Sie keinen IP-Bereich angeben, werden alle Benutzer an das JWT-Authentifizierungsformular umgeleitet.
- Wenn Sie externe IDs für Ihre Benutzer verwenden, können Sie diese in Zendesk Support aktualisieren, indem Sie die Option Externe IDs aktualisieren? auf Ein setzen.
- Leiten Sie das Shared Secret an Ihr IT-Team weiter. Es wird für die JWT-Implementierung benötigt. Wichtig: Bewahren Sie das Shared Secret sicher auf. Wenn es in die Hände Unbefugter fällt, sind alle Daten in Ihrem Zendesk Support-Konto gefährdet.
- Wählen Sie Schaltfläche anzeigen, wenn Benutzer sich anmelden, um die Schaltfläche Mit SSO fortfahren zur Zendesk-Anmeldeseite hinzuzufügen.
Bei Bedarf können Sie im Feld Schaltflächenname eine andere Beschriftung eingeben. Angepasste Schaltflächenbeschriftungen sind hilfreich, wenn auf der Anmeldeseite mehrere SSO-Schaltflächen erscheinen sollen. Weitere Informationen finden Sie unter Hinzufügen von SSO-Schaltflächen zur Zendesk-Anmeldeseite.
- Klicken Sie auf Speichern.
Standardmäßig sind Enterprise-SSO-Konfigurationen inaktiv. Sie müssen die SSO-Konfiguration Benutzern zuweisen, um sie zu aktivieren.
Zuweisen von SSO über JWT zu Benutzern
Nachdem Sie Ihre JWT SSO-Konfiguration erstellt haben, müssen Sie sie aktivieren, indem Sie sie Endbenutzern und/oder Teammitgliedern zuweisen.
So weisen Sie eine SSO-Konfiguration Teammitgliedern oder Endbenutzern zu
- Öffnen Sie die Sicherheitseinstellungen für Teammitglieder oder Endbenutzer.
- Klicken Sie in der Seitenleiste des Admin Centers auf Konto und dann auf Sicherheit > Authentifizierung für Teammitglieder.
- Klicken Sie in der Seitenleiste des Admin Centers auf Konto und dann auf Sicherheit > Authentifizierung für Endbenutzer.
- Klicken Sie in der Seitenleiste des Admin Centers auf
- Wählen Sie Externe Authentifizierung, um die Authentifizierungsoptionen anzuzeigen.
- Wählen Sie die Namen der SSO-Konfigurationen aus, die Sie verwenden möchten.
Single-Sign-On deckt möglicherweise nicht alle Anwendungsfälle ab. Deshalb bleibt die Zendesk-Authentifizierung standardmäßig aktiviert.
- Geben Sie an, wie sich die Benutzer anmelden sollen.
Lassen Sie sie wählen bedeutet, dass sich die Benutzer mit jeder aktiven Authentifizierungsmethode anmelden können. Weitere Informationen finden Sie unter Bereitstellen mehrerer Möglichkeiten zur Anmeldung bei Zendesk.
Zu SSO umleiten bedeutet, dass sich Benutzer nur mit der primären SSO-Konfiguration authentifizieren können. Weitere Möglichkeiten der Anmeldung werden nicht angezeigt, auch wenn die betreffenden Authentifizierungsoptionen aktiv sind. Wenn Sie Zu SSO umleiten wählen, wird das Feld Primäres SSO eingeblendet, in dem Sie die primäre SSO-Konfiguration auswählen können.
- Klicken Sie auf Speichern.
Verwalten von Benutzern in Zendesk nach Aktivieren von SSO über JWT
Nachdem Sie JWT als Single-Sign-On-Mechanismus in Zendesk aktiviert haben, werden außerhalb von Zendesk vorgenommene Änderungen an Benutzern nicht automatisch mit Ihrem Zendesk-Konto synchronisiert. Benutzer werden in Zendesk zum Zeitpunkt der Authentifizierung aktualisiert. Wenn beispielsweise ein Benutzer zu Ihrem internen System hinzugefügt wird, wird er bei seiner Zendesk-Anmeldung auch Ihrem Zendesk-Konto hinzugefügt. Wenn ein Benutzer aus Ihrem internen System gelöscht wird, kann er sich nicht mehr bei Zendesk anmelden. Sein Konto ist aber weiterhin in Zendesk vorhanden.
Wenn Single-Sign-On aktiviert ist, werden standardmäßig nur der Name und die E-Mail-Adresse des Benutzers in Zendesk gespeichert. Kennwörter werden von Zendesk nicht gespeichert. Deshalb sollten Sie alle automatischen E-Mail-Benachrichtigungen, die mit Kennwörtern zu tun haben, in Zendesk ausschalten.
Um ein besseres Kundenerlebnis zu gewährleisten, sollten Sie aber mehr Benutzerdaten in Zendesk speichern als nur den Namen und die E-Mail-Adresse. Hierzu können Sie zusätzliche JWT-Attribute verwenden.
Deaktivieren von Kennwort-E-Mails in Zendesk
Für jeden neuen Benutzer, der über SAML, JWT oder OpenID Connect (OIDC) auf Ihr Zendesk-Konto zugreift, wird ein Zendesk-Benutzerprofil erstellt. Das Profil wird ohne Kennwort erstellt, da Benutzer über einen IdP mit einem nicht von Zendesk vergebenen Kennwort authentifiziert werden und sich deshalb nicht bei direkt bei Zendesk anmelden müssen.
Da neue Benutzer, die sich per SSO bei Zendesk anmelden, durch einen IdP bestätigt werden, erhalten sie keine E-Mail-Benachrichtigungen für die Verifizierung ihres Kontos. Sie sollten diese automatisierten E-Mail-Benachrichtigungen trotzdem deaktivieren, um zu verhindern, dass sie bei einer nicht erfolgreichen Bestätigung des Benutzers durch den IdP gesendet werden. Bei einer SSO-Anmeldung muss der Benutzer immer durch den IdP bestätigt werden.
So schalten Sie Kennwortbenachrichtigungen per E-Mail aus
- Klicken Sie in der Seitenleiste des Admin Centers auf
Personen und dann auf Konfiguration > Endbenutzer. - Deaktivieren Sie im Abschnitt Konto-E‑Mails die Option Willkommens-E-Mail auch dann senden, wenn ein neuer Benutzer von einem Agenten oder Administrator erstellt wird.
- Deaktivieren Sie die Option Benutzer dürfen ihr Kennwort ändern.
Generieren eines neuen Shared Secret
Unter Umständen, etwa wenn Ihr Geheimnis kompromittiert wird, müssen Sie ein neues JWT Shared Secret generieren und an Ihr IT-Team oder Ihren externen Identity Provider weiterleiten. Sie können ein neues JWT Shared Secret vom Zendesk Admin Center aus generieren. Dadurch wird das ursprüngliche Secret entfernt und durch ein neues Secret ersetzt. Sie müssen Ihr IT-Team oder Ihren externen Identity Provider über Ihr neues Shared Secret informieren, damit die Zendesk SSO-Kontoauthentifizierung funktioniert.
So generieren Sie ein neues Shared Secret
- Klicken Sie in der Seitenleiste des Admin Centers auf Konto und dann auf Sicherheit > Single-Sign-On.
- Setzen Sie den Mauszeiger auf die JWT-Konfiguration, für die Sie ein neues Shared Secret erstellen möchten, klicken Sie auf das Symbol für das Optionsmenü (
) und dann auf Bearbeiten. - Klicken Sie ganz unten auf der Konfigurationsseite unter Shared Secret auf Geheimnis zurücksetzen.
Eine Bestätigungsmeldung wird angezeigt.
- Klicken Sie auf Geheimnis zurücksetzen, um den Vorgang zu bestätigen.
Ein neues Shared Secret wird im Klartext angezeigt.
- Klicken Sie auf Kopieren, um das neue Shared Secret zu kopieren, und leiten Sie es an Ihr IT-Team oder Ihren externen Identity Provider weiter.
- Speichern Sie die Änderungen.
Wechseln der Authentifizierungsmethode
Wenn Sie Benutzer in Zendesk über die SSO-Methode eines Drittanbieters erstellen und authentifizieren und später zur Zendesk-Authentifizierung wechseln, haben diese Benutzer kein Kennwort für die Anmeldung. Sie können sich erst wieder anmelden, nachdem sie ihr Kennwort auf der Zendesk-Anmeldeseite zurückgesetzt haben.
Weitere Informationen zu JWT
JWT ist ein offener Standard, der von der Internet Engineering Task Force (IETF) vorangetrieben und von führenden Technologieunternehmen wie Microsoft, Facebook und Google unterstützt wird.
Da die Grundbausteine von JWT bekannte Komponenten sind, ist die Spezifikation (http://tools.ietf.org/html/draft-jones-json-web-token-10) relativ unkompliziert. Es gibt zahlreiche Open-Source-Implementierungen der JWT-Spezifikation, die die meisten modernen Technologien abdecken. Sie sollten also den JWT-Single-Sign-On ohne größere Schwierigkeiten konfigurieren können.
Beachten Sie, dass die JWT-Payload zwar codiert und signiert, nicht aber verschlüsselt wird – übergeben Sie also in der Hashtabelle keine sensiblen Daten. JWT serialisiert den übertragenen JSON-Wert in eine Zeichenfolge. Die Zeichenfolge wird im Base64-Format codiert und anschließend anhand des Shared Secret ein HMAC der Base64-Zeichenfolge erstellt. Das Endergebnis ist eine Signatur, die von der Empfängerseite zur Validierung des Benutzers herangezogen werden kann.
Worksheet zur technischen Implementierung
Dieser Abschnitt ist für das Team gedacht, das für das JWT-Authentifizierungssystem des Unternehmens zuständig ist. Er enthält wichtige Informationen zur Implementierung des SSO über JWT in Zendesk.
Behandelte Themen:
JWT-Algorithmus
Geben Sie HS256 als JWT-Algorithmus im Header der JWT-Payload an:
{
"typ":"JWT",
"alg":"HS256"
}HS256 steht für HMAC SHA 256, einen 256-Bit-Verschlüsselungsalgorithmus der U.S. National Security Agency.
JWT-Endpunkt von Zendesk
Nachdem Sie den Benutzer erfolgreich authentifiziert haben, erstellen Sie die JWT-Payload und reichen eine POST-Anforderung, die die JWT-Payload enthält, beim folgenden Zendesk-Endpunkt ein:
https://meinesubdomäne.zendesk.com/access/jwt
Die Payload muss base64-codiert sein und über ein Formular von einem Client eingereicht werden. Das Einreichen der Payload mit einer clientseitigen AJAX-, Fetch- oder Axios-Anforderung wird nicht funktionieren, da die Anforderung durch die Same-Origin-Policy des Clients blockiert wird. Auch eine POST-Anforderung von Ihrem Server aus wird nicht funktionieren, da dabei die für die Authentifizierung verwendeten Cookies im Browser des Benutzers nicht korrekt gesetzt werden.
Die JWT-Payload muss über das Protokoll https an Ihre Zendesk Support-Subdomäne gesendet werden. Beispiel:
https://yoursubdomain.zendesk.com/access/jwtHost-Mapping-Subdomänen werden nicht unterstützt.
JWT-Attribute
Senden Sie JWT-Attribute als Hash (Ruby) oder Dictionary (Python). Das JWT-Attribut muss base64-codiert sein. Ruby-Beispiel:
payload = JWT.encode({
:email => "bob@example.com", :name => "Bob", :iat => Time.now.to_i, :jti => rand(2<<64).to_s
}, "Our shared secret")Zendesk benötigt eine E-Mail-Adresse, um den Benutzer eindeutig identifizieren zu können. Neben den erforderlichen Attributen, die in der folgenden Tabelle aufgeführt sind, können Sie bei Bedarf auch weitere Benutzerprofildaten übergeben. Diese Daten werden zwischen Ihrem Benutzermanagementsystem und Zendesk Support synchronisiert.
| Attribut | Datentyp | Beschreibung |
|---|---|---|
| iat | Numerisches Datum | „iat“ steht für „issued at“, also Uhrzeit, zu der das Token generiert wurde. Stellt sicher, dass ein Token kurz nach der Generierung benutzt wird. Dieser Wert muss die Anzahl von Sekunden seit der UNIX-Epoche angeben. Zendesk lässt eine Uhrzeittoleranz von bis zu drei Minuten zu; stellen Sie also sicher, dass auf Ihren Servern NTP o. ä. konfiguriert ist. |
| jti | Zeichenfolge | ID des JSON Web Token. Eine eindeutige ID für das Token; wird von Zendesk zur Verhinderung von Token-Replay-Attacken verwendet. |
| Zeichenfolge | E-Mail-Adresse des Benutzers, der angemeldet wird. Dient zur eindeutigen Identifizierung des Benutzerdatensatzes in Zendesk Support. | |
| name | Zeichenfolge | Name des Benutzers. Das Benutzerprofil in Zendesk Support wird entsprechend diesem Wert erstellt oder aktualisiert. |
| Attribut | Datentyp | Beschreibung |
|---|---|---|
| external_id | Zeichenfolge | Wenn Ihre Benutzer anhand eines anderen Werts als der E-Mail-Adresse eindeutig identifiziert werden und die Möglichkeit besteht, dass sich ihre E-Mail-Adresse ändert, müssen Sie eine eindeutige ID aus Ihrem System übergeben. Geben Sie die ID als String an. |
| locale (für Endbenutzer) locale_id (für Agenten) |
Ganzzahl | Das Gebietsschema (Sprache) in Zendesk Support als Zahl. |
| organization | Zeichenfolge | Name einer Organisation, zu der der Benutzer hinzugefügt wird. Wenn die Option Benutzer können mehreren Organisationen angehören aktiviert ist, ergänzen die zusätzlichen Organisationen die ursprüngliche Organisation; vorhandene Zugehörigkeiten werden nicht gelöscht. Wenn Sie mehrere Organisationsnamen gleichzeitig übergeben möchten, verwenden Sie stattdessen das Attribut organizations. Die Organisationsnamen müssen in einer fortlaufenden Zeichenfolge mit Kommas als Trennzeichen übergeben werden. |
| organization_id | Ganzzahl | Die externe ID der Organisation in der Zendesk-API. Wenn sowohl „organization“ als auch „organization_id“ angegeben werden, wird „organization“ ignoriert. Wenn die Option Benutzer können mehreren Organisationen angehören aktiviert ist, ergänzen die zusätzlichen Organisationen die ursprüngliche Organisation; vorhandene Zugehörigkeiten werden nicht gelöscht. Wenn Sie mehrere Organisations-IDs gleichzeitig übergeben möchten, verwenden Sie stattdessen das Attribut organization_ids. Die Organisations-IDs müssen in einer fortlaufenden Zeichenfolge mit Kommas als Trennzeichen übergeben werden. |
| phone | Zeichenfolge | Eine Telefonnummer als Zeichenfolge. Die Telefonnummer muss dem internationalen Telefonnummernplan E.164 entsprechen. Beispiel: +15551234567. E164-Nummern sind internationale Nummern mit einer Landesvorwahl, in der Regel einer Ortsvorwahl und einer Teilnehmernummer. Eine gültige E.164-Telefonnummer muss eine Landesvorwahl enthalten. |
| tags | Array | JSON-Array mit Stichwörtern für den Benutzer. Diese Stichwörter ersetzen die evtl. bereits im Benutzerprofil vorhandenen Stichwörter. |
| remote_photo_url | Zeichenfolge | URL eines Fotos für das Benutzerprofil. |
| role | Zeichenfolge | Rolle des Benutzers. Dieser Wert kann auf end_user, agent oder admin gesetzt werden. Die Standardeinstellung lautet end_user. Wenn die Rolle des Benutzers in Zendesk Support anders ist, wird die Rolle in Zendesk Support geändert. |
| custom_role_id | Ganzzahl | Nur zutreffend, wenn die Benutzerrolle „agent“ lautet. |
| user_fields | Objekt |
Ein JSON-Hash aus dem Schlüssel des angepassten Benutzerfelds und Werten, die für den Benutzer festgelegt werden sollen. Das angepasste Benutzerfeld muss existieren, damit der Feldwert festgelegt werden kann. Jedes angepasste Benutzerfeld wird anhand seines Feldschlüssels identifiziert, der in den Admin-Einstellungen für Benutzerfelder zu finden ist. Das Format von Datumswerten lautet jjjj-mm-tt. Wenn ein Benutzerfeldschlüssel oder -wert ungültig ist, schlägt die Aktualisierung des Feldes ohne Meldung fehl, der Benutzer wird aber trotzdem erfolgreich angemeldet. Weitere Informationen zu angepassten Benutzerfeldern finden Sie unter Hinzufügen von angepassten Feldern zu Benutzern.
Hinweis: Bei Übergabe von Nullwerten im Attribut „user_fields“ werden eventuell vorhandene Werte aus den entsprechenden Feldern entfernt.
|
Parameter für Remote-Login-URL (return_to)
Die Übergabe des return_to-Parameters ist zwar optional, empfiehlt sich aber, um ein angenehmes Benutzererlebnis sicherzustellen. Wenn Zendesk einen Benutzer an die Remote-Anmeldeseite umleitet, wird auch der return_to-Parameter in der URL übergeben. Dieser Parameter gibt die Seite an, an die Zendesk den Benutzer weiterleitet, nachdem Ihr System ihn authentifiziert hat. Hängen Sie den Namen und den Wert des Parameters an den JWT-Endpunkt von Zendesk an.
Angenommen, ein abgemeldeter Agent klickt auf den folgenden Link, um ein Ticket in Zendesk Support zu öffnen: https://meinefirma.zendesk.com/tickets/1232. Der Ablauf ist wie folgt:
- Wenn der Benutzer auf den Link klickt, leitet Zendesk ihn an Ihre Remote-Login-URL um und hängt den folgenden
return_to-Parameter an die URL an:https://mycompany.com/zendesk/sso?return_to=https://mycompany.zendesk.com/tickets/123 - Ihr Authentifizierungssystem hängt den
return_to-Parameter aus der URL an den JWT-Endpunkt von Zendesk oder an den Anforderungskörper an, nachdem der Benutzer erfolgreich authentifiziert wurde. Beispiel:https://mycompany.zendesk.com/access/jwt?&return_to=https://mycompany.zendesk.com/tickets/123 - Zendesk verwendet den Parameter, um die Ticketseite für den Agenten zu öffnen.
Der return_to-Parameter ist eine absolute URL für die Agentenoberfläche und eine relative URL für das Help Center.
return_to-Adresse eigene URL-Parameter enthält, müssen Sie sicherstellen, dass Ihr Skript bei der Übergabe des JWT-Tokens den gesamten return_to-Wert URI-codiert. Fehlerbehandlung
Wenn Zendesk bei der Verarbeitung einer JWT-Anmeldeanforderung einen Fehler erkennt, erscheint eine Meldung, aus der das Problem hervorgeht. Wenn Sie beim Konfigurieren der JWT-Integration eine Remote-Logout-URL angegeben haben, leitet das System den Benutzer zu dieser URL um und übergibt die Parameter message und kind. Bei einem Fehler hat der Parameter kind immer den Wert „error“. Zendesk empfiehlt, eine Remote-Logout-URL anzugeben und Meldungen von Zendesk zusammen mit dem Typ zu protokollieren. Die meisten Fehler, die auftreten, sollten behoben werden. Hierzu gehören beispielsweise Taktabweichungen, Überschreitungen von Ratengrenzen und ungültige Token.
Beispiele für die Formulareinreichung
Die JWT-Payload muss über ein Formular von einem Browser an den folgenden Zendesk-Endpunkt übermittelt werden:
https://yoursubdomain.zendesk.com/access/jwtIm Zendesk-Repository für JWT-SSO auf GitHub sind Beispiele für diverse Technologie-Stacks zu finden: Die JWT-Payload muss über ein Formular von einem Browser aus übermittelt werden, damit Cookies im Browser korrekt gesetzt werden können und die Anforderung nicht durch CORS blockiert wird.
Antwort
Die Antwort sollte HTML-Code mit dem Status 200 OK sein. Die Antwort weist folgendes Format auf:
<html><body>You are being <a href="">redirected</a>.</body></html>Wenn href mit dem return_to-Wert übereinstimmt, wurde der Benutzer erfolgreich authentifiziert und es sollten Cookies gesetzt werden. Wenn href mit https://SUBDOMAIN.zendesk.com/access/unauthenticated beginnt, konnte Zendesk den Benutzer nicht authentifizieren.
Beispiele für die JWT-Generierung
Das eigentliche JWT-Coding ist unkompliziert; für die meisten modernen Sprachen gibt es Bibliotheken, die es unterstützen. Im GitHub-Repository für JWT-SSO sind Beispiele für diverse Stacks zu finden:
Der JWT-Generierungscode ist für die Serverimplementierung bestimmt. Sie können das generierte JWT an Ihre Anmeldeseite zurückgeben und dann die Formularübermittlung vom Browser aus initiieren.
Wenn Sie JWT in einem anderen Stack implementieren, würden wir gerne Ihr Beispiel zum Repository hinzufügen. Lassen Sie uns bitte in einem Kommentar zu diesem Beitrag wissen, was Sie implementiert haben.
Falls Sie IIS/AD verwenden und keine eigene .NET-Lösung erstellen möchten, bieten wir eine vollständige Implementierung in Classic ASP, bei der Sie lediglich ein paar Variablen anpassen müssen. Laden Sie das ASP-Authentifizierungsskript von GitHub herunter.