External Password API

Gebruik een external password API wanneer je (a) wachtwoordvalidatie wilt delegeren aan een bestaande password store of policy engine, (b) een extern systeem wilt informeren over wachtwoordwijzigingen die in FoxIDs worden uitgevoerd, of (c) beide scenario's wilt afhandelen.

Je implementeert de external password API en configureert FoxIDs om deze aan te roepen.

• Validation API: valideert een wachtwoord (bijv. tijdens login of voordat een wachtwoordwijziging wordt geaccepteerd) en kan optioneel een wachtwoordwijziging melden in dezelfde call.
• Notification API: meldt een wachtwoordwijziging nadat het wachtwoord alle policy checks heeft doorstaan. Het wordt alleen aangeroepen bij nieuwe wachtwoorden (state 200).

Als de ingebouwde password policy het wachtwoord afwijst, wordt de external password API niet aangeroepen. De notification-methode van de external password API wordt alleen aangeroepen als het wachtwoord alle geconfigureerde policy checks heeft doorstaan en alleen wanneer de password state 200 is (new password).

Als je zowel validatie als wijzigingsmelding nodig hebt, en beide door hetzelfde systeem kunnen worden afgehandeld, implementeer dan alleen de validation API. Wanneer je een validation request ontvangt waarbij het wachtwoord wordt geaccepteerd, voer je notificatielogica intern uit. Implementeer beide endpoints alleen indien nodig, bijvoorbeeld als je twee verschillende backend systemen moet aanroepen.

External password API kan worden geconfigureerd als password check voor internal users.

API implementeren

Je moet een eenvoudige API implementeren die FoxIDs aanroept voor validation / notification requests (zie sample).

De API heeft een base URL; functionaliteit is gegroepeerd in mappen: de validation map (validate password) en de notification map (notify about password changes).

Als de base URL https://somewhere.org/mystore is,

• het validation endpoint is: https://somewhere.org/mystore/validation
• en het notification endpoint is: https://somewhere.org/mystore/notification.

FoxIDs Cloud roept je API aan vanaf IP 57.128.60.142. IP(s) kunnen wijzigen of worden uitgebreid.

Request en response zijn hetzelfde voor zowel validation als notification methoden. De validation methode heeft een extra error case als het wachtwoord niet wordt geaccepteerd.

Request

Beveiligd met HTTP Basic authentication: gebruikersnaam external_password, wachtwoord is de geconfigureerde secret.

De call is HTTP POST met een JSON body.

Velden:

• email / phone / username (optioneel - minimaal één moet aanwezig zijn)
• password (required)
• state (required) - zie password state

Dit is een request JSON body met alleen e-mail als user identifier (validatie van een bestaand wachtwoord tijdens login):

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

Dit is een request JSON body met alle drie user identifiers (validatie van een nieuw wachtwoord dat wordt ingesteld of gewijzigd):

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

User identifiers zijn optioneel, maar minimaal één moet aanwezig zijn. Wachtwoord en state zijn vereist.

Password state

De password state maakt het mogelijk om verschillende logica toe te passen afhankelijk van de context.

Waarden:

• 100 is current password, dat wordt verzonden wanneer een gebruiker een bestaand wachtwoord invoert tijdens login.
• 200 is new password, dat wordt verzonden wanneer een gebruiker een nieuw wachtwoord instelt of wijzigt (user creation, password change of reset).

Response

Success Bij succes moet de API HTTP status code 200 retourneren.

Error De API moet HTTP status code 401 (Unauthorized) retourneren en een error (vereist) als Basic authentication wordt afgewezen. Voeg optioneel een foutbeschrijving toe in ErrorMessage.

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

Error - alleen voor de validation methode De API moet HTTP status code 400 of 403 retourneren en een error (vereist) als het wachtwoord (rekening houdend met state) niet wordt geaccepteerd. Voeg optioneel een foutbeschrijving toe in ErrorMessage.

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

Als er andere fouten optreden, moet de API HTTP status code 500 of een andere passende foutcode retourneren. Het wordt aanbevolen om een technische foutmelding in ErrorMessage toe te voegen voor diagnostiek (alleen gelogd; nooit aan de eindgebruiker getoond).

API Sample

De sample ExternalPasswordApiSample laat zien hoe je de API implementeert in ASP.NET Core.

Gebruik de Postman collection external-password-api.postman_collection.json om je API aan te roepen en te testen met Postman.

Configure

De external password API wordt geconfigureerd in de environment settings in FoxIDs Control Client.

1. Selecteer het tabblad Settings
2. En vervolgens het tabblad Environment
3. Zoek de sectie External password API
4. Selecteer Validate on password change om een externe password policy af te dwingen voordat een nieuw wachtwoord voor een gebruiker wordt ingesteld.
5. Voeg de base API URL zonder de validation en notification mappen toe in API URL
6. Voeg de API secret toe
7. Klik Update