Zewnętrzne API haseł

Użyj zewnętrznego API haseł, gdy potrzebujesz, aby FoxIDs (a) delegował walidację hasła do istniejącego magazynu haseł lub silnika polityk, (b) powiadamiał system zewnętrzny o zmianach hasła wykonanych w FoxIDs lub (c) obsługiwał oba scenariusze.

Implementujesz zewnętrzne API haseł i konfigurujesz FoxIDs do jego wywoływania.

Validation API: waliduje hasło (np. podczas logowania lub przed zaakceptowaniem zmiany hasła) i może opcjonalnie powiadomić o zmianie hasła w tym samym wywołaniu.
Notification API: powiadamia o zmianie hasła po tym, jak hasło przeszło wszystkie kontrole polityki. Jest wywoływane wyłącznie dla zdarzeń nowego hasła (stan 200).

Jeśli wbudowana polityka haseł odrzuci hasło, zewnętrzne API haseł nie jest wywoływane. Metoda powiadomień zewnętrznego API haseł jest wywoływana tylko wtedy, gdy hasło przeszło wszystkie skonfigurowane kontrole polityki i tylko wtedy, gdy stan hasła wynosi 200 (nowe hasło).

Jeśli potrzebujesz zarówno walidacji, jak i powiadomienia o zmianie, a oba mogą być obsługiwane przez ten sam system, zaimplementuj tylko Validation API. Gdy otrzymasz żądanie walidacji, w którym hasło zostało zaakceptowane, wykonaj logikę powiadomień wewnętrznie. Implementuj oba punkty końcowe tylko wtedy, gdy to konieczne, np. jeśli musisz wywołać dwa różne systemy backendowe.

Zewnętrzne API haseł można skonfigurować jako kontrolę hasła dla użytkowników wewnętrznych.

Implementuj API

Musisz zaimplementować proste API, które FoxIDs wywołuje dla żądań walidacji lub powiadomień (zobacz przykład).

API ma bazowy URL; funkcjonalność jest pogrupowana w foldery: validation (walidacja hasła) i notification (powiadomienie o zmianach hasła).

Jeśli bazowy URL to https://somewhere.org/mystore,

punkt końcowy walidacji to: https://somewhere.org/mystore/validation
a punkt końcowy powiadomień to: https://somewhere.org/mystore/notification.

FoxIDs Cloud wywołuje Twoje API z adresu IP 57.128.60.142.
Adresy IP mogą się zmieniać lub zostać rozszerzone.

Żądanie i odpowiedź są takie same dla metod walidacji i powiadomień. Metoda walidacji ma dodatkowy przypadek błędu zwracany, jeśli hasło nie zostanie zaakceptowane.

Żądanie

Zabezpieczone HTTP Basic authentication: nazwa użytkownika external_password, hasło to skonfigurowany sekret.

Wywołanie jest HTTP POST z treścią JSON.

Pola:

email / phone / username (opcjonalne - co najmniej jedno musi być obecne)
password (wymagane)
state (wymagane) - zobacz stan hasła

To jest treść JSON żądania tylko z adresem e-mail jako identyfikatorem użytkownika (walidacja istniejącego hasła podczas logowania):

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

To jest treść JSON żądania ze wszystkimi trzema identyfikatorami użytkownika (walidacja nowego hasła ustawianego lub zmienianego):

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

Identyfikatory użytkownika są opcjonalne, ale co najmniej jeden musi być obecny. Hasło i stan są wymagane.

Stan hasła

Stan hasła umożliwia stosowanie różnej logiki w zależności od kontekstu.

Wartości:

100 to bieżące hasło, które jest wysyłane, gdy użytkownik wprowadza istniejące hasło podczas logowania.
200 to nowe hasło, które jest wysyłane, gdy użytkownik ustawia lub zmienia nowe hasło (tworzenie użytkownika, zmiana hasła lub reset).

Odpowiedź

Sukces
W przypadku sukcesu API powinno zwrócić kod HTTP 200.

Błąd
API musi zwrócić kod HTTP 401 (Unauthorized) oraz error (wymagany), jeśli Basic authentication zostanie odrzucone. Opcjonalnie dodaj opis błędu w ErrorMessage.

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

Błąd - tylko dla metody walidacji
API musi zwrócić kod HTTP 400 lub 403 oraz error (wymagany), jeśli hasło (uwzględniając jego stan) nie zostanie zaakceptowane. Opcjonalnie dodaj opis błędu w ErrorMessage.

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

Jeśli wystąpią inne błędy, API powinno zwrócić kod HTTP 500 lub inny odpowiedni kod błędu.
Zaleca się dodanie technicznego komunikatu błędu w ErrorMessage do diagnostyki (jest tylko logowany; nigdy nie jest pokazywany użytkownikowi końcowemu).

Przykład API

Przykład ExternalPasswordApiSample pokazuje, jak zaimplementować API w ASP.NET Core.

Użyj kolekcji Postman external-password-api.postman_collection.json, aby wywoływać i testować API w Postman.

Konfiguracja

Zewnętrzne API haseł jest konfigurowane w ustawieniach środowiska w FoxIDs Control Client.

Wybierz kartę Settings
Następnie wybierz kartę Environment
Znajdź sekcję External password API
Wybierz Validate on password change, aby wymusić zewnętrzną politykę haseł przed ustawieniem nowego hasła dla użytkownika.
Dodaj bazowy URL API bez folderów validation i notification w API URL
Dodaj API secret
Kliknij Update