External Password API

Använd ett externt lösenords-API när du behöver FoxIDs för att (a) delegera lösenordsvalidering till ett befintligt lösenordslager eller en befintlig policy-motor, (b) meddela ett externt system om lösenordsändringar som utförts i FoxIDs, eller (c) hantera båda scenarierna.

Du implementerar det externa lösenords-API:et och konfigurerar FoxIDs för att anropa det.

  • Validerings-API: validerar ett lösenord (t.ex. vid inloggning eller innan en lösenordsändring godkänns) och kan valfritt meddela dig om en lösenordsändring i samma anrop.
  • Meddelande-API: meddelar om en lösenordsändring efter att lösenordet har klarat alla policykontroller. Det anropas endast vid händelser som gäller nya lösenord (status 200).

Om den inbyggda lösenordspolicyn avvisar lösenordet anropas inte det externa lösenords-API:et. Det externa lösenords-API:ets meddelandemetod anropas endast om lösenordet har klarat alla konfigurerade policykontroller och endast när lösenordets status är 200 (nytt lösenord).

Om du behöver både validering och ändringsmeddelanden, och båda kan hanteras av samma system, implementerar du endast validerings-API:et. När du tar emot en valideringsförfrågan där lösenordet godkänns, utför du din meddelandekontroll internt. Implementera båda ändpunkterna endast om det behövs, t.ex. om du måste anropa två olika backend-system.

Externt lösenords-API kan konfigureras som lösenordskontroll för interna användare.

Implementera API

Du måste implementera ett enkelt API som FoxIDs anropar för validation / notification requests (se sample).

API:et har en base URL; funktionalitet är grupperad i mappar: validation-mappen (validate password) och notification-mappen (notify about password changes).

Om base URL är https://somewhere.org/mystore,

  • validation endpoint är: https://somewhere.org/mystore/validation
  • och notification endpoint är: https://somewhere.org/mystore/notification.

FoxIDs Cloud anropar ditt API från IP 57.128.60.142. IP(s) kan ändras eller utökas.

Request och response är samma för både validation och notification metoder. Validation metoden har ett extra error case om lösenordet inte accepteras.

Request

Säkrad med HTTP Basic authentication: användarnamn external_password, lösenord är det konfigurerade secret.

Anropet är HTTP POST med en JSON body.

Fält:

  • email / phone / username (valfritt - minst ett måste finnas)
  • password (required)
  • state (required) - se password state

Detta är en request JSON body med endast e-post som user identifier (validering av ett befintligt lösenord vid login):

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

Detta är en request JSON body med alla tre user identifiers (validering av ett nytt lösenord som sätts eller ändras):

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

User identifiers är valfria, men minst ett måste finnas. Lösenord och state krävs.

Password state

Password state gör det möjligt att tillämpa olika logik beroende på kontext.

Värden:

  • 100 är current password, som skickas när en användare anger ett befintligt lösenord vid login.
  • 200 är new password, som skickas när en användare sätter eller ändrar till ett nytt lösenord (user creation, password change eller reset).

Response

Success Vid framgång ska API:et returnera HTTP status code 200.

Error API:et måste returnera HTTP status code 401 (Unauthorized) och en error (krävs) om Basic authentication avvisas. Lägg valfritt till en felbeskrivning i ErrorMessage.

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

Error - endast för validation metoden API:et måste returnera HTTP status code 400 eller 403 och en error (krävs) om lösenordet (med hänsyn till state) inte accepteras. Lägg valfritt till en felbeskrivning i ErrorMessage.

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

Om andra fel uppstår ska API:et returnera HTTP status code 500 eller annan lämplig felkod. Det rekommenderas att lägga till ett tekniskt felmeddelande i ErrorMessage för diagnostik (loggas bara; visas aldrig för slutanvändaren).

API Sample

Sample ExternalPasswordApiSample visar hur du implementerar API:et i ASP.NET Core.

Använd Postman collection external-password-api.postman_collection.json för att anropa och testa ditt API med Postman.

Configure

External password API konfigureras i environment settings i FoxIDs Control Client.

  1. Välj fliken Settings
  2. Och därefter fliken Environment
  3. Hitta sektionen External password API
  4. Välj Validate on password change för att tvinga en extern password policy innan ett nytt lösenord sätts för en användare.
  5. Lägg till base API URL utan validation och notification mapparna i API URL
  6. Lägg till API secret Configure the external password API
  7. Klicka Update