External Password API

Brug et eksternt adgangskode-API, når du har brug for FoxIDs til (a) at delegere adgangskodevalidering til et eksisterende adgangskodelager eller en eksisterende policy-engine, (b) at underrette et eksternt system om adgangskodeændringer, der er foretaget i FoxIDs, eller (c) at håndtere begge scenarier.

Du implementerer API'et til eksterne adgangskoder og konfigurerer FoxIDs til at kalde det.

  • Validerings-API: validerer en adgangskode (f.eks. under login eller før godkendelse af en adgangskodeændring) og kan valgfrit underrette dig om en adgangskodeændring i samme opkald.
  • Notifikations-API: giver besked om en adgangskodeændring, efter at adgangskoden har bestået alle politikkontroller. Den kaldes kun ved hændelser med nye adgangskoder (status 200).

Hvis den indbyggede adgangskodepolitik afviser adgangskoden, kaldes det eksterne adgangskode-API ikke. Det eksterne adgangskode-API's notifikationsmetode kaldes kun, hvis adgangskoden har bestået alle konfigurerede politikkontroller, og kun når adgangskodestatus er 200 (ny adgangskode).

Hvis du har brug for både validering og ændringsmeddelelse, og begge dele kan håndteres af det samme system, skal du kun implementere validerings-API'en. Når du modtager en valideringsanmodning, hvor adgangskoden accepteres, skal du udføre din meddelelseslogik internt. Implementer kun begge endpoints, hvis det er nødvendigt, f.eks. hvis du skal kalde to forskellige backend-systemer.

Det eksterne adgangskode-API kan konfigureres som adgangskodekontrol for interne brugere.

Implementer API

Du skal implementere et simpelt API som FoxIDs kalder for validation / notification requests (se sample).

API'et har en base URL; funktionalitet er grupperet 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 kalder dit API fra IP 57.128.60.142. IP(s) kan ændres eller udvides.

Request og response er ens for både validation og notification metoder. Validation metoden har en ekstra error case returneret hvis adgangskoden ikke accepteres.

Request

Sikret med HTTP Basic authentication: brugernavn external_password, password er det konfigurerede secret.

Kaldet er HTTP POST med en JSON body.

Felter:

  • email / phone / username (optional - mindst én skal være til stede)
  • password (required)
  • state (required) - se password state

Dette er en request JSON body med kun email som user identifier (validering af eksisterende password under login):

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

Dette er en request JSON body med alle tre user identifiers (validering af et nyt password der sættes eller ændres):

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

User identifiers er optional, men mindst én skal være til stede. Password og state er påkrævet.

Password state

Password state gør det muligt at anvende forskellige logikker afhængigt af kontekst.

Værdier:

  • 100 er current password, som sendes når en bruger indtaster en eksisterende adgangskode under login.
  • 200 er new password, som sendes når en bruger sætter eller ændrer til en ny adgangskode (user creation, password change eller reset).

Response

Success Ved succes skal API'et returnere HTTP status code 200.

Error API'et skal returnere HTTP status code 401 (Unauthorized) og en error (påkrævet) hvis Basic authentication afvises. Tilføj valgfrit en fejlbeskrivelse i ErrorMessage.

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

Error - kun for validation metoden API'et skal returnere HTTP status code 400 eller 403 og en error (påkrævet) hvis passwordet (under hensyntagen til state) ikke accepteres. Tilføj valgfrit en fejlbeskrivelse i ErrorMessage.

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

Hvis andre fejl opstår, skal API'et returnere HTTP status code 500 eller en anden passende fejlkode. Det anbefales at tilføje en teknisk fejlmeddelelse i ErrorMessage til diagnosticering (den logges kun; vises aldrig til slutbrugeren).

API Sample

Sample ExternalPasswordApiSample viser hvordan man implementerer API'et i ASP.NET Core.

Brug Postman collection external-password-api.postman_collection.json til at kalde og teste dit API med Postman.

Configure

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

  1. Vælg fanen Settings
  2. Og efterfølgende fanen Environment
  3. Find sektionen External password API
  4. Vælg Validate on password change for at håndhæve en ekstern password policy før en ny adgangskode sættes for en bruger.
  5. Tilføj base API URL uden validation og notification mapperne i API URL
  6. Tilføj API secret Configure the external password API
  7. Klik Update