External Password API

Brug et external password API når du har brug for at (a) delegere adgangskodevalidering til en eksisterende password store eller policy engine, (b) notificere et eksternt system om adgangskodeændringer udført i FoxIDs, eller (c) håndtere begge scenarier.

Du implementerer det eksterne password API og konfigurerer FoxIDs til at kalde det.

• Validation API: validerer en adgangskode (f.eks. under login eller før en adgangskodeændring accepteres) og kan valgfrit notificere om en adgangskodeændring i samme kald.
• Notification API: notificerer om en adgangskodeændring efter at adgangskoden har bestået alle policy checks. Den kaldes kun for nye adgangskoder (state 200).

Hvis den indbyggede password policy afviser adgangskoden, kaldes det eksterne password API ikke. Det eksterne password API's notification metode kaldes kun hvis adgangskoden har bestået alle konfigurerede policy checks og kun når password state er 200 (new password).

Hvis du kræver både validering og change notification, og begge kan håndteres af samme system, så implementer kun validation API. Når du modtager en validation request hvor adgangskoden accepteres, udfør din notification logik internt. Implementer kun begge endpoints hvis det er nødvendigt, f.eks. hvis du skal kalde to forskellige backend systemer.

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

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