API de mot de passe externe

Utilisez une API de mot de passe externe lorsque vous avez besoin que FoxIDs (a) délègue la validation des mots de passe à un magasin de mots de passe ou moteur de politiques existant, (b) notifie un système externe des changements de mot de passe effectués dans FoxIDs, ou (c) gère les deux scénarios.

Vous implémentez l’API de mot de passe externe et configurez FoxIDs pour l’appeler.

• **API de validation 😗* valide un mot de passe (par ex. lors de la connexion ou avant d’accepter un changement de mot de passe) et peut, en option, vous notifier d’un changement de mot de passe dans le même appel.
• **API de notification 😗* notifie un changement de mot de passe après que le mot de passe a passé toutes les vérifications de politique. Elle n’est invoquée que pour les événements de nouveau mot de passe (état 200).

Si la politique de mot de passe intégrée rejette le mot de passe, l’API de mot de passe externe n’est pas appelée. La méthode de notification de l’API de mot de passe externe n’est appelée que si le mot de passe a passé toutes les vérifications de politique configurées et uniquement lorsque l’état du mot de passe est 200 (nouveau mot de passe).

Si vous avez besoin à la fois de la validation et de la notification de changement, et que les deux peuvent être gérées par le même système, implémentez uniquement l’API de validation. Lorsque vous recevez une demande de validation où le mot de passe est accepté, effectuez votre logique de notification en interne. Implémentez les deux endpoints uniquement si nécessaire, par ex. si vous devez appeler deux systèmes backend différents.

L’API de mot de passe externe peut être configurée comme vérification de mot de passe pour les utilisateurs internes.

Implémenter l’API

Vous devez implémenter une API simple que FoxIDs appelle pour les demandes de validation / notification (voir exemple).

L’API a une URL de base ; la fonctionnalité est regroupée en dossiers : le dossier validation (valider le mot de passe) et le dossier notification (notifier les changements de mot de passe).

Si l’URL de base est https://somewhere.org/mystore,

• l’endpoint de validation est : https://somewhere.org/mystore/validation
• et l’endpoint de notification est : https://somewhere.org/mystore/notification.

FoxIDs Cloud appelle votre API depuis l’IP 57.128.60.142. Les IP peuvent changer ou être étendues.

La requête et la réponse sont identiques pour les méthodes de validation et de notification. La méthode de validation a un cas d’erreur supplémentaire si le mot de passe n’est pas accepté.

Requête

Sécurisée avec l’authentification HTTP Basic : nom d’utilisateur external_password, le mot de passe est le secret configuré.

L’appel est un HTTP POST avec un corps JSON.

Champs :

• email / phone / username (optionnel - au moins un doit être présent)
• password (obligatoire)
• state (obligatoire) - voir état du mot de passe

Voici un corps de requête JSON avec uniquement l’e-mail comme identifiant utilisateur (validation d’un mot de passe existant lors de la connexion) :

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

Voici un corps de requête JSON avec les trois identifiants utilisateur (validation d’un nouveau mot de passe lors de la définition ou du changement) :

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

Les identifiants utilisateur sont optionnels, mais au moins un doit être présent. Le mot de passe et l’état sont obligatoires.

État du mot de passe

L’état du mot de passe permet d’appliquer une logique différente selon le contexte.

Valeurs :

• 100 est le mot de passe actuel, envoyé lorsqu’un utilisateur saisit un mot de passe existant lors de la connexion.
• 200 est le nouveau mot de passe, envoyé lorsqu’un utilisateur définit ou change un nouveau mot de passe (création d’utilisateur, changement ou réinitialisation de mot de passe).

Réponse

Succès En cas de succès, l’API doit retourner le code HTTP 200.

Erreur L’API doit retourner le code HTTP 401 (Unauthorized) et une error (requise) si l’authentification Basic est rejetée. Ajoutez éventuellement une description d’erreur dans ErrorMessage.

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

Erreur - uniquement pour la méthode de validation L’API doit retourner le code HTTP 400 ou 403 et une error (requise) si le mot de passe (en tenant compte de son état) n’est pas accepté. Ajoutez éventuellement une description d’erreur dans ErrorMessage.

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

Si d’autres erreurs surviennent, l’API doit retourner le code HTTP 500 ou un autre code d’erreur approprié. Il est recommandé d’ajouter un message d’erreur technique dans ErrorMessage pour le diagnostic (il est uniquement consigné ; jamais affiché à l’utilisateur final).

Exemple d’API

L’exemple ExternalPasswordApiSample montre comment implémenter l’API en ASP.NET Core.

Utilisez la collection Postman external-password-api.postman_collection.json pour appeler et tester votre API avec Postman.

Configurer

L’API de mot de passe externe est configurée dans les paramètres d’environnement dans FoxIDs Control Client.

1. Sélectionnez l’onglet Settings
2. Puis sélectionnez l’onglet Environment
3. Trouvez la section External password API
4. Sélectionnez Validate on password change pour appliquer une politique de mot de passe externe avant qu’un nouveau mot de passe ne soit défini pour un utilisateur.
5. Ajoutez l’URL de base de l’API sans les dossiers validation et notification dans API URL
6. Ajoutez le API secret
7. Cliquez sur Update