External Password API

Utilizzare un'API password esterna quando si necessita di FoxIDs per (a) delegare la convalida delle password a un archivio di password o a un motore di policy esistente, (b) notificare a un sistema esterno le modifiche alle password effettuate in FoxIDs, oppure (c) gestire entrambi gli scenari.

Si implementa l'API password esterna e si configura FoxIDs per richiamarla.

API di convalida: convalida una password (ad esempio, durante l'accesso o prima di accettare una modifica della password) e, facoltativamente, può notificare una modifica della password nella stessa chiamata.
API di notifica: invia una notifica relativa a una modifica della password dopo che questa ha superato tutti i controlli previsti dalla politica. Viene invocata solo per gli eventi relativi a una nuova password (stato 200).

Se la politica delle password integrata rifiuta la password, l'API esterna per le password non viene chiamata. Il metodo di notifica dell'API esterna per le password viene chiamato solo se la password ha superato tutti i controlli previsti dalla politica configurata e solo quando lo stato della password è 200 (nuova password).

Se sono necessarie sia la convalida che la notifica delle modifiche, e entrambe possono essere gestite dallo stesso sistema, implementare solo l’API di convalida. Quando si riceve una richiesta di convalida in cui la password viene accettata, eseguire la logica di notifica internamente. Implementare entrambi gli endpoint solo se necessario, ad esempio se si devono chiamare due diversi sistemi di backend.

L'API per le password esterne può essere configurata come verifica della password per gli utenti interni.

Implementare API

Devi implementare una semplice API che FoxIDs chiama per richieste di validazione / notifica (vedi sample).

L'API ha un URL base; la funzionalita e raggruppata in cartelle: la cartella validation (validare password) e la cartella notification (notificare modifiche password).

Se l'URL base e https://somewhere.org/mystore,

l'endpoint di validazione e: https://somewhere.org/mystore/validation
e l'endpoint di notifica e: https://somewhere.org/mystore/notification.

FoxIDs Cloud chiama la tua API dall'IP 57.128.60.142. Gli IP possono cambiare o essere ampliati.

La richiesta e la risposta sono uguali sia per il metodo di validazione sia per il metodo di notifica. Il metodo di validazione ha un caso di errore aggiuntivo restituito se la password non viene accettata.

Richiesta

Protetta con HTTP Basic authentication: username external_password, la password e il secret configurato.

La chiamata e un HTTP POST con body JSON.

Campi:

email / phone / username (facoltativi - deve esserne presente almeno uno)
password (obbligatoria)
state (obbligatorio) - vedi stato password

Questo e un body JSON di richiesta con solo l'email come identificatore utente (validazione di una password esistente durante il login):

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

Questo e un body JSON di richiesta con tutti e tre gli identificatori utente (validazione di una nuova password impostata o modificata):

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

Gli identificatori utente sono facoltativi, ma deve esserne presente almeno uno. Password e state sono obbligatori.

Stato password

Lo stato password rende possibile applicare logiche diverse a seconda del contesto.

Valori:

100 e la password corrente, inviata quando un utente inserisce una password esistente durante il login.
200 e una nuova password, inviata quando un utente imposta o cambia una nuova password (creazione utente, modifica password o reset).

Risposta

Successo In caso di successo l'API deve restituire codice HTTP 200.

Errore L'API deve restituire codice HTTP 401 (Unauthorized) e un error (obbligatorio) se l'autenticazione Basic viene rifiutata. Facoltativamente aggiungi una descrizione dell'errore in ErrorMessage.

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

Errore - solo per il metodo di validazione L'API deve restituire codice HTTP 400 o 403 e un error (obbligatorio) se la password, considerando il suo stato, non viene accettata. Facoltativamente aggiungi una descrizione dell'errore in ErrorMessage.

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

Se si verificano altri errori, l'API deve restituire codice HTTP 500 o un altro codice di errore appropriato. Si raccomanda di aggiungere un messaggio tecnico di errore in ErrorMessage per la diagnostica (viene solo registrato; non viene mai mostrato all'utente finale).

Sample API

Il sample ExternalPasswordApiSample mostra come implementare l'API in ASP.NET Core.

Usa la Postman collection external-password-api.postman_collection.json per chiamare e testare la tua API con Postman.

Configurare

L'API password esterna viene configurata nelle impostazioni dell'ambiente in FoxIDs Control Client.

Seleziona la scheda Settings
Successivamente seleziona la scheda Environment
Trova la sezione External password API
Seleziona Validate on password change per applicare una policy password esterna prima che venga impostata una nuova password per un utente.
Aggiungi l'URL base dell'API senza le cartelle validation e notification in API URL
Aggiungi API secret
Fai clic su Update