Secure Service Desk API

Die Secure Service Desk API ermöglicht es Kunden, die Benutzerverifizierung des Secure Service Desk in ihre bestehenden Systeme zu integrieren oder ein Verifizierungsportal für ihre Service-Desk-Agenten zu erstellen. Die API ist auf die Benutzerverifizierung beschränkt.

Die API funktioniert wie die meisten APIs, wobei Verifizierungsanfragen über eine URL, die die API-URL enthält, an Specops Authentication gesendet werden, sowie die Suchzeichenfolge, die den zu verifizierenden Benutzer enthält. Der API-Schlüssel wird über den Header gesendet.

Verifizierungstypen

Sowohl die Schnellverifizierung als auch die erweiterte Verifizierung werden über die API unterstützt. Im Falle der Schnellverifizierung können jedoch nur diejenigen Identitätsdienste verwendet werden, die so konfiguriert wurden, dass sie Push-Benachrichtigungen verwenden.

Hinweis

Alle verfügbaren Schnellverifizierungs-Identitätsdienste werden in der Schnellverifizierungsliste angezeigt, unabhängig davon, ob sie für die Verwendung von Push-Benachrichtigungen konfiguriert wurden oder nicht. Wenn ein Service-Desk-Agent einen Identitätsdienst als Schnellverifizierung verwendet, der keine Push-Benachrichtigungen konfiguriert hat, schlägt die Verifizierung fehl.

Voraussetzungen

Konfiguration der Voraussetzungen

Die folgenden Konfigurationen sind erforderlich, um die API nutzen zu können.

API-Schlüssel: Generieren Sie einen API-Schlüssel in Authentication Web (siehe auch den Abschnitt unten zum Generieren eines API-Schlüssels)
Suchattribute konfigurieren: Fügen Sie die Attribute "mail" und/oder "userPrincipalName" zu den "Suchattributen" im Gatekeeper Admin Tool hinzu. Dies stellt sicher, dass Benutzersuchen über die API Ergebnisse liefern. Ohne diese liefern Benutzerabfragen keine Ergebnisse.
1. Klicken Sie im Gatekeeper Admin Tool auf Secure Service Desk
2. Klicken Sie im Abschnitt Benutzersucheinstellungen in der Zeile Suchattribute auf Bearbeiten.
3. Deaktivieren Sie das Kontrollkästchen Standardwert verwenden.
4. Geben Sie die Attribute ein, die Sie verwenden möchten. Trennen Sie mehrere Attribute durch Kommas.
5. Klicken Sie auf OK.

API-Header einfügen

Bei einem API-Aufruf müssen die folgenden Header enthalten sein:

Name	Erforderlich	Beschreibung
x-api-key	Ja	Der im Admin-Portal generierte API-Schlüssel.
x-client-ip	Ja	Die IP-Adresse des Clients. Diese IP-Adresse wird an die Identitätsdienste weitergeleitet, um den Standort der Schnellverifizierungsinitialisierung anzuzeigen. Obwohl erforderlich, unterstützen nicht alle Identitätsdienste die Definition der Client-IP-Adressen.

Generieren von API-Schlüsseln

Kunden können unbegrenzt viele API-Schlüssel generieren, um sie innerhalb ihrer Organisation zu verwenden.

Klicken Sie in Authentication Web im linken Navigationsbereich auf Service Desk.
Klicken Sie auf die Registerkarte API-Schlüssel.
Geben Sie im Benutzerfreundlicher Name-Spalte einen Namen in das Feld Benutzerfreundlichen Namen hier eingeben ein.
Wählen Sie im Dropdown-Menü in der Ressource-Spalte Service Desk API aus.
Klicken Sie auf Neuen API-Schlüssel generieren.
Kopieren Sie die API-URL und den API-Schlüssel an einen sicheren Ort.

Hinweis

Es ist sehr wichtig, diese Daten in diesem Stadium zu kopieren, da sie für die Durchführung der API-Aufrufe erforderlich sind und nicht erneut angezeigt werden können, sobald Sie diese Seite verlassen.
Klicken Sie auf Speichern.

Erwarteter Verifizierungsablauf

Der erwartete Verifizierungsablauf bei API-Aufrufen ist wie folgt:

Benutzerinformationen abrufen

Parameter	Wert
Methode	GET
Endpunkt	/api/v1/findusers
Abfrageparameter	userIdentifier performedBy
Beschreibung	Abrufen der Benutzerinformationen einschließlich einer temporären Benutzer-ID anhand der E-Mail-Adresse eines Benutzers.

Verifizierungsmethoden abrufen

Parameter	Wert
Methode	GET
Endpunkt	/api/v1/verifyidentity
Abfrageparameter	userId
Beschreibung	Abrufen aller verfügbaren Verifizierungsmethoden anhand der in Schritt 1 erhaltenen Benutzer-ID, jede mit einer entsprechenden Verifizierungs-ID.

Verifizierung initiieren

Parameter	Wert
Methode	POST
Endpunkt	/api/v1/verifyidentity
Abfrageparameter	verificationId notificationMethod (nur für erweiterte Verifizierung) notificationLanguage (nur für erweiterte Verifizierung)
Beschreibung	Starten des Verifizierungsprozesses mit einer ausgewählten Verifizierungs-ID, die in Schritt 2 erhalten wurde.

Hinweis

Wenn die Verifizierung fehlschlägt, muss der Ablauf für dieselbe Verifizierungsmethode ab Schritt 1 neu gestartet werden. Alternativ wählen Sie eine andere Verifizierungsmethode, indem Sie eine Verifizierungs-ID aus Schritt 2 verwenden und diesen Schritt erneut starten.

Verifizierungsstatus überprüfen

Parameter	Wert
Methode	GET
Endpunkt	/api/v1/verificationstatus
Abfrageparameter	verificationId
Beschreibung	Verfolgen des Verifizierungsprozesses durch Abfragen des Status mit der Verifizierungs-ID.

Hinweis

Wenn der Status einen Fehler anzeigt, starten Sie den Ablauf ab Schritt 1 neu, um dieselbe Verifizierungsmethode erneut zu versuchen. Alternativ wählen Sie eine andere Verifizierungsmethode, indem Sie eine Verifizierungs-ID aus Schritt 2 verwenden, die dieser Methode entspricht, und starten den Prozess erneut bei Schritt 3. Dieser Endpunkt sollte nicht häufiger als alle 2 Sekunden aufgerufen werden.

Beschreibung der API-Parameter

Parametername	Beschreibung
userIdentifier	Die E-Mail-Adresse oder UPN des abgefragten Benutzers.
performedBy	Die E-Mail-Adresse oder UPN des Benutzers, der die Aktion ausführt.
userId	Eine eindeutige, temporäre Kennung für den Benutzer. Jeder Suchaufruf für denselben Benutzer generiert eine neue eindeutige Benutzer-ID.
verificationId	Eine eindeutige, temporäre Kennung für die Verifizierungsmethode. Diese ID ist spezifisch für den Benutzer und die ausgewählte Verifizierungsmethode. Sie kann nur einmal verwendet werden, um eine Verifizierung zu starten, kann jedoch erneut verwendet werden, um den Verifizierungsstatus abzurufen.
notificationMethod	Gibt die Methode an, mit der der Benutzer den Verifizierungslink erhält. Dieser Parameter ist für erweiterte Verifizierungen obligatorisch.
notificationLanguage	Gibt die Sprache der Benachrichtigung an, die den Verifizierungslink enthält. Dieser Parameter ist für erweiterte Verifizierungen obligatorisch.