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.

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 des utilisateurs. 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.

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

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

7. Cliquez sur Enregistrer.

Flux de vérification attendu

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

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

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

3. 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 les méthodes de vérification par lien de navigateur) notificationLanguage (uniquement pour les méthodes de vérification par lien de navigateur)
   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.

4. Vérifier le statut de la vérification

   Paramètre	Valeur
   Méthode	GET
   Point de terminaison	/api/v1/identityverificationstatus
   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 lors de l'utilisation de méthodes de vérification par lien de navigateur.
notificationLanguage	Spécifie la langue de la notification contenant le lien de vérification. Ce paramètre est obligatoire lors de l'utilisation de méthodes de vérification par lien de navigateur.