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.

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 Initialisierung der Benutzerverifizierung 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.

1. Klicken Sie in Authentication Web im linken Navigationsbereich auf Service Desk.
2. Klicken Sie auf die Registerkarte API-Schlüssel.
3. Geben Sie im Benutzerfreundlicher Name-Spalte einen Namen in das Feld Benutzerfreundlichen Namen hier eingeben ein.
4. Wählen Sie im Dropdown-Menü in der Ressource-Spalte Service Desk API aus.
5. Klicken Sie auf Neuen API-Schlüssel generieren.

6. 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.

7. Klicken Sie auf Speichern.

Erwarteter Verifizierungsablauf

Der erwartete Verifizierungsablauf bei API-Aufrufen ist wie folgt:

1. 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.

2. 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.

3. Verifizierung initiieren

   Parameter	Wert
   Methode	POST
   Endpunkt	/api/v1/verifyidentity
   Abfrageparameter	verificationId notificationMethod (nur für Verifizierungsmethoden über Browser-Links) notificationLanguage (nur für Verifizierungsmethoden über Browser-Links)
   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.

4. Verifizierungsstatus überprüfen

   Parameter	Wert
   Methode	GET
   Endpunkt	/api/v1/identityverificationstatus
   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 bei Verwendung von Verifizierungsmethoden über Browser-Links obligatorisch.
notificationLanguage	Gibt die Sprache der Benachrichtigung an, die den Verifizierungslink enthält. Dieser Parameter ist bei Verwendung von Verifizierungsmethoden über Browser-Links obligatorisch.