External Password API

Z zewnętrznego interfejsu API haseł należy korzystać, gdy FoxIDs musi: (a) przekazać weryfikację haseł do istniejącego magazynu haseł lub silnika zasad, (b) powiadomić system zewnętrzny o zmianach haseł dokonanych w FoxIDs lub (c) obsłużyć oba powyższe scenariusze.

Należy zaimplementować zewnętrzny interfejs API haseł i skonfigurować usługę FoxIDs tak, aby z niego korzystała.

Interfejs API walidacji: sprawdza poprawność hasła (np. podczas logowania lub przed zaakceptowaniem zmiany hasła) i opcjonalnie może powiadomić o zmianie hasła w ramach tego samego wywołania.
Interfejs API powiadomień: powiadamia o zmianie hasła po tym, jak hasło przeszło wszystkie kontrole zgodności z polityką. Jest wywoływany wyłącznie w przypadku zdarzeń związanych z nowym hasłem (stan 200).

Jeśli wbudowana polityka haseł odrzuci hasło, zewnętrzny interfejs API haseł nie zostanie wywołany. Metoda powiadomień zewnętrznego interfejsu API haseł jest wywoływana tylko wtedy, gdy hasło przeszło wszystkie skonfigurowane kontrole zgodności z polityką i tylko wtedy, gdy stan hasła wynosi 200 (nowe hasło).

Jeśli potrzebujesz zarówno walidacji, jak i powiadomień o zmianach, a oba te zadania mogą być obsługiwane przez ten sam system, zaimplementuj wyłącznie interfejs API walidacji. Po otrzymaniu żądania walidacji, w którym hasło zostało zaakceptowane, wykonaj logikę powiadomień wewnętrznie. Zaimplementuj oba punkty końcowe tylko w razie potrzeby, np. jeśli musisz wywołać dwa różne systemy zaplecza.

Zewnętrzny interfejs API haseł można skonfigurować jako sprawdzanie haseł 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