API externa de contraseña

Use una API externa de contraseña cuando necesite que FoxIDs (a) delegue la validación de contraseñas en un almacén de contraseñas o motor de políticas existente, (b) notifique a un sistema externo sobre cambios de contraseña realizados en FoxIDs, o (c) gestione ambos escenarios.

Usted implementa la API externa de contraseña y configura FoxIDs para llamarla.

• API de validación: valida una contraseña (p. ej., durante el inicio de sesión o antes de aceptar un cambio de contraseña) y opcionalmente puede notificarle un cambio de contraseña en la misma llamada.
• API de notificación: notifica sobre un cambio de contraseña después de que la contraseña haya pasado todas las comprobaciones de política. Solo se invoca para eventos de nueva contraseña (estado 200).

Si la política de contraseña integrada rechaza la contraseña, la API externa de contraseña no se llama. El método de notificación de la API externa de contraseña solo se llama si la contraseña ha pasado todas las comprobaciones de política configuradas y solo cuando el estado de la contraseña es 200 (nueva contraseña).

Si necesita tanto validación como notificación de cambio, y ambas pueden gestionarse por el mismo sistema, implemente solo la API de validación. Cuando reciba una solicitud de validación donde la contraseña sea aceptada, realice su lógica de notificación internamente. Implemente ambos endpoints solo si es necesario, p. ej. si necesita llamar a dos sistemas backend diferentes.

La API externa de contraseña se puede configurar como verificación de contraseña para usuarios internos.

Implementar API

Debe implementar una API simple que FoxIDs llama para solicitudes de validación / notificación (ver ejemplo).

La API tiene una URL base; la funcionalidad se agrupa en carpetas: la carpeta validation (validar contraseña) y la carpeta notification (notificar cambios de contraseña).

Si la URL base es https://somewhere.org/mystore,

• el endpoint de validación es: https://somewhere.org/mystore/validation
• y el endpoint de notificación es: https://somewhere.org/mystore/notification.

FoxIDs Cloud llama a su API desde la IP 57.128.60.142. Las IP pueden cambiar o ampliarse.

La solicitud y la respuesta son las mismas para los métodos de validación y notificación. El método de validación tiene un caso de error adicional si la contraseña no es aceptada.

Solicitud

Protegida con HTTP Basic authentication: nombre de usuario external_password, la contraseña es el secreto configurado.

La llamada es HTTP POST con un cuerpo JSON.

Campos:

• email / phone / username (opcional - al menos uno debe estar presente)
• password (obligatorio)
• state (obligatorio) - ver estado de contraseña

Este es un cuerpo de solicitud JSON con solo el email como identificador de usuario (validando una contraseña existente durante el inicio de sesión):

{
  "email": "user1@somewhere.org",
  "password": "testpass1",
  "state": 100
}

Este es un cuerpo de solicitud JSON con los tres identificadores de usuario (validando una nueva contraseña que se establece o cambia):

{
  "email": "user1@somewhere.org",
  "phone": "+4011223344",
  "username": "user1",
  "password": "testpass1",
  "state": 200
}

Los identificadores de usuario son opcionales, pero al menos uno debe estar presente. La contraseña y el estado son obligatorios.

Estado de contraseña

El estado de contraseña permite aplicar una lógica diferente según el contexto.

Valores:

• 100 es la contraseña actual, que se envía cuando un usuario introduce una contraseña existente durante el inicio de sesión.
• 200 es la nueva contraseña, que se envía cuando un usuario establece o cambia a una nueva contraseña (creación de usuario, cambio o restablecimiento de contraseña).

Respuesta

Éxito En caso de éxito, la API debe devolver el código de estado HTTP 200.

Error La API debe devolver el código de estado HTTP 401 (Unauthorized) y un error (requerido) si se rechaza la autenticación Basic. Opcionalmente agregue una descripción del error en ErrorMessage.

{
  "error": "invalid_api_id_secret",
  "ErrorMessage": "Invalid API ID or secret"
}

Error - solo para el método de validación La API debe devolver el código de estado HTTP 400 o 403 y un error (requerido) si la contraseña (teniendo en cuenta su estado) no es aceptada. Opcionalmente agregue una descripción del error en ErrorMessage.

{
  "error": "password_not_accepted",
  "ErrorMessage": "Password not accepted."
}

Si se producen otros errores, la API debe devolver el código de estado HTTP 500 u otro código de error apropiado. Se recomienda agregar un mensaje de error técnico en ErrorMessage para diagnóstico (solo se registra; nunca se muestra al usuario final).

Ejemplo de API

El ejemplo ExternalPasswordApiSample muestra cómo implementar la API en ASP.NET Core.

Use la colección de Postman external-password-api.postman_collection.json para llamar y probar su API con Postman.

Configurar

La API externa de contraseña se configura en la configuración del entorno en FoxIDs Control Client.

1. Seleccione la pestaña Settings
2. Y posteriormente seleccione la pestaña Environment
3. Busque la sección External password API
4. Seleccione Validate on password change para aplicar una política de contraseña externa antes de que se establezca una nueva contraseña para un usuario.
5. Agregue la URL base de la API sin las carpetas validation y notification en API URL
6. Agregue el API secret
7. Haga clic en Update