API password esterna

Usa un'API password esterna quando hai bisogno che FoxIDs (a) deleghi la validazione della password a uno store password o motore di policy esistente, (b) notifichi a un sistema esterno le modifiche password eseguite in FoxIDs, oppure (c) gestisca entrambi gli scenari.

Tu implementi l'API password esterna e configuri FoxIDs per chiamarla.

• Validation API: valida una password, ad esempio durante il login o prima di accettare una modifica password, e puo facoltativamente notificare la modifica password nella stessa chiamata.
• Notification API: notifica una modifica password dopo che la password ha superato tutti i controlli di policy. Viene invocata solo per eventi di nuova password (state 200).

Se la policy password integrata rifiuta la password, l'API password esterna non viene chiamata. Il metodo di notifica dell'API password esterna viene chiamato solo se la password ha superato tutti i controlli di policy configurati e solo quando lo stato password e 200 (nuova password).

Se richiedi sia la validazione sia la notifica della modifica, e entrambe possono essere gestite dallo stesso sistema, implementa solo la Validation API. Quando ricevi una richiesta di validazione in cui la password viene accettata, esegui internamente la logica di notifica. Implementa entrambi gli endpoint solo se necessario, ad esempio se devi chiamare due sistemi backend diversi.

L'API password esterna puo essere configurata come controllo 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.

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