External Password API

Bruk et eksternt passord-API når du trenger FoxIDs for å (a) delegere passordvalidering til et eksisterende passordlager eller en eksisterende policy-motor, (b) varsle et eksternt system om passordendringer utført i FoxIDs, eller (c) håndtere begge scenariene.

Du implementerer API-et for eksternt passord og konfigurerer FoxIDs til å kalle det opp.

  • Validerings-API: validerer et passord (f.eks. ved innlogging eller før et passordbytte godkjennes) og kan eventuelt varsle deg om et passordbytte i samme oppkall.
  • Varslings-API: varsler om en passordendring etter at passordet har bestått alle retningslinjekontroller. Det påkalles kun ved hendelser knyttet til nye passord (status 200).

Hvis den innebygde passordpolitikken avviser passordet, blir ikke det eksterne passord-API-et påkalt. Det eksterne passord-API-ets varslingsmetode blir kun påkalt dersom passordet har bestått alle konfigurerte policykontroller, og kun når passordstatusen er 200 (nytt passord).

Hvis du trenger både validering og endringsvarsling, og begge deler kan håndteres av det samme systemet, bør du kun implementere validerings-API-et. Når du mottar en valideringsforespørsel der passordet godkjennes, skal du utføre varslingslogikken internt. Implementer begge endepunktene kun hvis det er nødvendig, f.eks. hvis du må kommunisere med to forskjellige backend-systemer.

Eksternt passord-API kan konfigureres som passordkontroll for interne brukere.

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 Configure the external password API
  7. Klikk Update