External Password API

Gebruik een externe wachtwoord-API wanneer u FoxIDs nodig hebt om (a) de wachtwoordvalidatie te delegeren aan een bestaande wachtwoordopslag of beleidsengine, (b) een extern systeem op de hoogte te stellen van wachtwoordwijzigingen die zijn doorgevoerd in FoxIDs, of (c) beide scenario's af te handelen.

U implementeert de externe wachtwoord-API en configureert FoxIDs om deze aan te roepen.

Validatie-API: valideert een wachtwoord (bijvoorbeeld tijdens het inloggen of voordat een wachtwoordwijziging wordt geaccepteerd) en kan u optioneel in dezelfde aanroep op de hoogte stellen van een wachtwoordwijziging.
Meldings-API: meldt een wachtwoordwijziging nadat het wachtwoord alle beleidscontroles heeft doorstaan. Deze wordt alleen aangeroepen bij gebeurtenissen met betrekking tot een nieuw wachtwoord (status 200).

Als het ingebouwde wachtwoordbeleid het wachtwoord afwijst, wordt de externe wachtwoord-API niet aangeroepen. De meldingsmethode van de externe wachtwoord-API wordt alleen aangeroepen als het wachtwoord alle geconfigureerde beleidscontroles heeft doorstaan en alleen wanneer de wachtwoordstatus 200 is (nieuw wachtwoord).

Als u zowel validatie als wijzigingsmelding nodig hebt en beide door hetzelfde systeem kunnen worden afgehandeld, implementeer dan alleen de validatie-API. Wanneer u een validatieverzoek ontvangt waarbij het wachtwoord wordt geaccepteerd, voer dan uw meldingslogica intern uit. Implementeer beide eindpunten alleen indien nodig, bijvoorbeeld als u twee verschillende backend-systemen moet aanroepen.

De externe wachtwoord-API kan worden geconfigureerd als wachtwoordcontrole voor interne gebruikers.

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.

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