External Password API

Använd ett external password API när du behöver (a) delegera lösenordsvalidering till en befintlig password store eller policy engine, (b) notifiera ett externt system om lösenordsändringar som görs i FoxIDs, eller (c) hantera båda scenarierna.

Du implementerar external password API:et och konfigurerar FoxIDs att anropa det.

• Validation API: validerar ett lösenord (t.ex. vid login eller innan en lösenordsändring accepteras) och kan valfritt notifiera om en lösenordsändring i samma anrop.
• Notification API: notifierar om en lösenordsändring efter att lösenordet klarat alla policy checks. Den anropas endast vid nya lösenord (state 200).

Om den inbyggda password policy avvisar lösenordet anropas external password API:et inte. Notification-metoden i external password API:et anropas endast om lösenordet har klarat alla konfigurerade policy checks och endast när password state är 200 (new password).

Om du behöver både validering och ändringsnotifiering, och båda kan hanteras av samma system, implementera endast validation API. När du får en validation request där lösenordet accepteras, utför din notifieringslogik internt. Implementera båda endpoints endast om det behövs, t.ex. om du måste anropa två olika backend system.

External password API kan konfigureras som password check för internal users.

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
7. Klicka Update