API de Secure Service Desk

L'API Secure Service Desk permet aux clients d'intégrer la vérification des utilisateurs de Secure Service Desk dans leurs systèmes existants ou de créer un portail de vérification pour que leurs agents du service desk puissent l'utiliser. L'API est limitée à la vérification des utilisateurs.

L'API fonctionne comme la plupart des API, avec des demandes de vérification envoyées à Specops Authentication via une URL contenant l'URL de l'API, ainsi que la chaîne de recherche contenant l'utilisateur à vérifier. La clé API est envoyée via l'en-tête.

Types de vérification

La vérification rapide et la vérification avancée sont toutes deux prises en charge via l'API. Cependant, dans le cas de la vérification rapide, seuls les services d'identité qui ont été configurés pour utiliser les notifications push peuvent être utilisés.

Remarque

Tous les services d'identité de vérification rapide disponibles seront affichés dans la liste de vérification rapide, qu'ils aient été configurés ou non pour utiliser les notifications push. Si un agent du service desk utilise un service d'identité comme vérification rapide qui n'a pas de notifications push configurées, la vérification échouera.

Prérequis

Configuration préalable

Les configurations suivantes sont nécessaires pour commencer à utiliser l'API.

Clé API : Générez une clé API dans Authentication Web (voir également la section ci-dessous sur la génération d'une clé API)
Configurer les attributs de recherche : Ajoutez les attributs "mail" et/ou "userPrincipalName" aux "Attributs de recherche" dans l'outil d'administration Gatekeeper. Cela garantit que les recherches d'utilisateurs via l'API renvoient des résultats. Sans cela, les requêtes utilisateur ne donneront aucun résultat.
1. Dans l'outil d'administration Gatekeeper, cliquez sur Secure Service Desk
2. Dans la section Paramètres de recherche d'utilisateur, cliquez sur Modifier dans la ligne des attributs de recherche.
3. Décochez la case Utiliser la valeur par défaut.
4. Entrez les attributs que vous souhaitez utiliser. Séparez plusieurs attributs par des virgules.
5. Cliquez sur OK.

Inclure les en-têtes API

Lors d'un appel API, les en-têtes suivants doivent être inclus :

Nom	Requis	Description
x-api-key	Oui	La clé API générée dans le portail d'administration.
x-client-ip	Oui	L'adresse IP du client. Cette adresse IP sera transmise aux services d'identité pour indiquer l'emplacement de l'initialisation de la vérification rapide. Bien que requis, tous les services d'identité ne prennent pas en charge la définition des adresses IP des clients.

Génération de clés API

Les clients peuvent générer un nombre illimité de clés API à utiliser au sein de leur organisation.

Dans Authentication Web, cliquez sur Service Desk dans la navigation de gauche.
Cliquez sur l'onglet Clés API.
Dans la colonne Nom convivial, entrez un nom dans le champ Entrez le nom convivial ici.
Choisissez Service Desk API dans le menu déroulant de la colonne Ressource.
Cliquez sur Générer une nouvelle clé API.
Copiez l'URL de l'API et la clé API dans un endroit sécurisé.

Remarque

Il est très important de copier ces données à ce stade car elles sont nécessaires pour effectuer les appels API, et ne peuvent pas être affichées à nouveau une fois que vous quittez cette page.
Cliquez sur Enregistrer.

Flux de vérification attendu

Le flux de vérification attendu lors des appels API est le suivant :

Récupérer les informations de l'utilisateur

Paramètre	Valeur
Méthode	GET
Point de terminaison	/api/v1/findusers
Paramètres de requête	userIdentifier performedBy
Description	À l'aide de l'adresse e-mail d'un utilisateur, récupérez les informations de l'utilisateur, y compris un ID utilisateur temporaire.

Récupérer les méthodes de vérification

Paramètre	Valeur
Méthode	GET
Point de terminaison	/api/v1/verifyidentity
Paramètres de requête	userId
Description	En utilisant l'ID utilisateur obtenu à l'étape 1, récupérez toutes les méthodes de vérification disponibles, chacune avec un ID de vérification correspondant.

Initier la vérification

Paramètre	Valeur
Méthode	POST
Point de terminaison	/api/v1/verifyidentity
Paramètres de requête	verificationId notificationMethod (uniquement pour la vérification avancée) notificationLanguage (uniquement pour la vérification avancée)
Description	Démarrez le processus de vérification en utilisant un ID de vérification sélectionné obtenu à l'étape 2.

Remarque

Si la vérification échoue, le flux doit être redémarré à partir de l'étape 1 pour la même méthode de vérification. Alternativement, sélectionnez une méthode de vérification différente en utilisant un ID de vérification de l'étape 2 et redémarrez cette étape.

Vérifier le statut de la vérification

Paramètre	Valeur
Méthode	GET
Point de terminaison	/api/v1/verificationstatus
Paramètres de requête	verificationId
Description	Suivez le processus de vérification en interrogeant le statut à l'aide de l'ID de vérification.

Remarque

Si le statut indique un échec, redémarrez le flux à partir de l'étape 1 pour réessayer la même méthode de vérification. Alternativement, sélectionnez une méthode de vérification différente en utilisant un ID de vérification de l'étape 2 correspondant à cette méthode et initiez à nouveau le processus à l'étape 3. Ce point de terminaison ne doit pas être appelé plus fréquemment qu'une fois toutes les 2 secondes.

Description des paramètres de l'API

Nom du paramètre	Description
userIdentifier	L'adresse e-mail ou UPN de l'utilisateur interrogé.
performedBy	L'adresse e-mail ou UPN de l'utilisateur effectuant l'action.
userId	Un identifiant temporaire unique pour l'utilisateur. Chaque appel de recherche pour le même utilisateur générera un nouvel ID utilisateur unique.
verificationId	Un identifiant temporaire unique pour la méthode de vérification. Cet ID est spécifique à l'utilisateur et à la méthode de vérification sélectionnée. Il peut être utilisé une seule fois pour démarrer une vérification mais peut être réutilisé pour récupérer le statut de la vérification.
notificationMethod	Spécifie la méthode par laquelle l'utilisateur recevra le lien de vérification. Ce paramètre est obligatoire pour les vérifications avancées.
notificationLanguage	Spécifie la langue de la notification contenant le lien de vérification. Ce paramètre est obligatoire pour les vérifications avancées.