API de Secure Service Desk

La API de Secure Service Desk permite a los clientes integrar la verificación de usuarios de Secure Service Desk en sus sistemas existentes o construir un portal de verificación para que lo utilicen sus agentes de servicio. La API está limitada a la verificación de usuarios.

La API funciona como la mayoría de las APIs, con solicitudes de verificación enviadas a Specops Authentication a través de una URL que contiene la URL de la API, así como la cadena de búsqueda que contiene al usuario que se va a verificar. La clave de la API se envía a través del encabezado.

Tipos de verificación

Tanto la Verificación Rápida como la Verificación Avanzada son compatibles a través de la API. Sin embargo, en el caso de la verificación rápida, solo se pueden utilizar aquellos servicios de identidad que se hayan configurado para usar notificaciones push.

Nota

Todos los servicios de identidad disponibles para la Verificación Rápida se mostrarán en la lista de Verificación Rápida, independientemente de si se han configurado o no para usar notificaciones push. Si un agente de servicio utiliza un servicio de identidad como Verificación Rápida que no tiene notificaciones push configuradas, la verificación fallará.

Requisitos previos

Configuración de requisitos previos

Se requieren las siguientes configuraciones para comenzar a usar la API.

Clave de API: Genere una clave de API en Authentication Web (consulte también la sección a continuación sobre cómo generar una clave de API)
Configurar atributos de búsqueda: Agregue los atributos "mail" y/o "userPrincipalName" a los "Atributos de búsqueda" en la herramienta de administración de Gatekeeper. Esto asegura que las búsquedas de usuarios a través de la API devuelvan resultados. Sin estos, las consultas de usuario no arrojarán resultados.
1. En la herramienta de administración de Gatekeeper, haga clic en Secure Service Desk
2. En la sección Configuración de búsqueda de usuarios, haga clic en Editar en la fila de atributos de búsqueda.
3. Desmarque la casilla Usar valor predeterminado.
4. Ingrese los atributos que desea usar. Separe múltiples atributos con comas.
5. Haga clic en OK.

Incluir encabezados de API

Al realizar una llamada a la API, se deben incluir los siguientes encabezados:

Nombre	Requerido	Descripción
x-api-key	Sí	La clave de API generada en el Portal de Administración.
x-client-ip	Sí	La dirección IP del cliente. Esta dirección IP se enviará a los Servicios de Identidad para indicar la ubicación de la inicialización de la verificación rápida. Aunque es obligatorio, no todos los Servicios de Identidad admiten la definición de las direcciones IP del cliente.

Generación de claves de API

Los clientes pueden generar claves de API ilimitadas para usar dentro de su organización.

En Authentication Web, haga clic en Service Desk en la navegación izquierda.
Haga clic en la pestaña API Keys.
En la columna Nombre Amigable, ingrese un nombre en el campo Ingrese nombre amigable aquí.
Elija Service Desk API en el menú desplegable en la columna Recurso.
Haga clic en Generar nueva clave de API.
Copie la URL de la API y la clave de API en una ubicación segura.

Nota

Es muy importante copiar estos datos en esta etapa ya que se requieren para realizar las llamadas a la API, y no se pueden mostrar nuevamente una vez que abandone esta página.
Haga clic en Guardar.

Flujo de verificación esperado

El flujo de verificación esperado al realizar llamadas a la API es el siguiente:

Recuperar información del usuario

Parámetro	Valor
Método	GET
Punto final	/api/v1/findusers
Parámetros de consulta	userIdentifier performedBy
Descripción	Usando la dirección de correo electrónico de un usuario, recupere la información del usuario, incluido un ID de usuario temporal.

Obtener métodos de verificación

Parámetro	Valor
Método	GET
Punto final	/api/v1/verifyidentity
Parámetros de consulta	userId
Descripción	Usando el ID de usuario obtenido en el paso 1, recupere todos los métodos de verificación disponibles, cada uno con un ID de verificación correspondiente.

Iniciar verificación

Parámetro	Valor
Método	POST
Punto final	/api/v1/verifyidentity
Parámetros de consulta	verificationId notificationMethod (solo para verificación avanzada) notificationLanguage (solo para verificación avanzada)
Descripción	Inicie el proceso de verificación utilizando un ID de verificación seleccionado obtenido en el paso 2.

Nota

Si la verificación falla, el flujo debe reiniciarse desde el paso 1 para el mismo método de verificación. Alternativamente, seleccione un método de verificación diferente utilizando un ID de verificación del paso 2 y reinicie este paso.

Verificar estado de la verificación

Parámetro	Valor
Método	GET
Punto final	/api/v1/identityverificationstatus
Parámetros de consulta	verificationId
Descripción	Realice un seguimiento del proceso de verificación consultando el estado utilizando el ID de verificación.

Nota

Si el estado indica un fallo, reinicie el flujo desde el paso 1 para intentar el mismo método de verificación. Alternativamente, seleccione un método de verificación diferente utilizando un ID de verificación del paso 2 correspondiente a ese método e inicie el proceso nuevamente en el paso 3. Este punto final no debe llamarse con más frecuencia que una vez cada 2 segundos.

Descripción de los parámetros de la API

Nombre del parámetro	Descripción
userIdentifier	La dirección de correo electrónico o UPN del usuario que se consulta.
performedBy	La dirección de correo electrónico o UPN del usuario que realiza la acción.
userId	Un identificador temporal único para el usuario. Cada llamada de búsqueda para el mismo usuario generará un nuevo ID de usuario único.
verificationId	Un identificador temporal único para el método de verificación. Este ID es específico para el usuario y el método de verificación seleccionado. Solo se puede usar una vez para iniciar una verificación, pero se puede reutilizar para recuperar el estado de la verificación.
notificationMethod	Especifica el método por el cual el usuario recibirá el enlace de verificación. Este parámetro es obligatorio para verificaciones avanzadas.
notificationLanguage	Especifica el idioma de la notificación que contiene el enlace de verificación. Este parámetro es obligatorio para verificaciones avanzadas.