External Password API

Bruk et external password API når du må (a) delegere passordvalidering til en eksisterende passordlager eller policy engine, (b) varsle et eksternt system om passordendringer utført i FoxIDs, eller (c) håndtere begge scenarier.

Du implementerer external password API-et og konfigurerer FoxIDs til å kalle det.

• Validation API: validerer et passord (f.eks. under login eller før en passordendring aksepteres) og kan valgfritt varsle om en passordendring i samme kall.
• Notification API: varsler om en passordendring etter at passordet har bestått alle policy checks. Den kalles kun for nye passord (state 200).

Hvis den innebygde password policy avviser passordet, blir external password API-et ikke kalt. Notification-metoden til external password API-et kalles bare hvis passordet har bestått alle konfigurerte policy checks og kun når password state er 200 (new password).

Hvis du trenger både validering og endringsvarsling, og begge kan håndteres av samme system, implementer kun validation API. Når du mottar en validation request der passordet aksepteres, utfør varsellogikken internt. Implementer begge endepunktene kun hvis nødvendig, f.eks. hvis du må kalle to forskjellige backend systemer.

External password API kan konfigureres som password check for internal users.

Implementer API

Du må implementere et enkelt API som FoxIDs kaller for validation / notification requests (se sample).

API-et har en base URL; funksjonaliteten er gruppert i mapper: validation-mappen (validate password) og notification-mappen (notify about password changes).

Hvis base URL er https://somewhere.org/mystore,

• validation endpoint er: https://somewhere.org/mystore/validation
• og notification endpoint er: https://somewhere.org/mystore/notification.

FoxIDs Cloud kaller API-et ditt fra IP 57.128.60.142. IP(s) kan endres eller utvides.

Request og response er de samme for både validation og notification metoder. Validation metoden har en ekstra error case returnert hvis passordet ikke aksepteres.

Request

Sikret med HTTP Basic authentication: brukernavn external_password, passord er det konfigurerte secret.

Kallet er HTTP POST med en JSON body.

Felt:

• email / phone / username (valgfritt - minst én må være til stede)
• password (påkrevd)
• state (påkrevd) - se password state

Dette er en request JSON body med kun e-post som user identifier (validering av eksisterende passord under login):

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

Dette er en request JSON body med alle tre user identifiers (validering av et nytt passord som settes eller endres):

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

User identifiers er valgfrie, men minst én må være til stede. Passord og state er påkrevd.

Password state

Password state gjør det mulig å bruke forskjellig logikk avhengig av kontekst.

Verdier:

• 100 er current password, som sendes når en bruker oppgir et eksisterende passord ved login.
• 200 er new password, som sendes når en bruker setter eller endrer til et nytt passord (user creation, password change eller reset).

Response

Success Ved suksess skal API-et returnere HTTP status code 200.

Error API-et må returnere HTTP status code 401 (Unauthorized) og en error (påkrevd) hvis Basic authentication avvises. Legg valgfritt til en feilbeskrivelse i ErrorMessage.

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

Error - kun for validation metoden API-et må returnere HTTP status code 400 eller 403 og en error (påkrevd) hvis passordet (med hensyn til state) ikke aksepteres. Legg valgfritt til en feilbeskrivelse i ErrorMessage.

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

Hvis andre feil oppstår, skal API-et returnere HTTP status code 500 eller en annen passende feilkode. Det anbefales å legge til en teknisk feilmelding i ErrorMessage for diagnostikk (den logges bare; aldri vist til sluttbrukeren).

API Sample

Sample ExternalPasswordApiSample viser hvordan du implementerer API-et i ASP.NET Core.

Bruk Postman collection external-password-api.postman_collection.json for å kalle og teste API-et ditt med Postman.

Configure

External password API er konfigurert i environment settings i FoxIDs Control Client.

1. Velg fanen Settings
2. Og deretter fanen Environment
3. Finn seksjonen External password API
4. Velg Validate on password change for å håndheve en ekstern password policy før et nytt passord settes for en bruker.
5. Legg til base API URL uten validation og notification-mappene i API URL
6. Legg til API secret
7. Klikk Update