Control API - ambienti
Utilizza FoxIDs Control API per elencare, creare, configurare ed eliminare ambienti in un tenant. Un ambiente è chiamato track in Control API percorsi e schemi.
Prima di chiamare queste operazioni, configurare Control API i diritti di autenticazione e accesso. Swagger rimane il riferimento esatto per tutte le proprietà dell'ambiente, le regole di convalida e gli schemi di risposta:
Base dell'endpoint
L'amministrazione dell'ambiente viene eseguita tramite l'ambiente master di tenant. Gli esempi utilizzano FoxIDs Cloud:
https://control.foxids.com/api/{tenant_name}/master
Sostituisci {tenant_name} con il nome tecnico di tenant. Modificare l'host per una distribuzione self-hosted. Invia il token di accesso Control API nell'intestazione Authorization: Bearer {access_token}.
Le operazioni sull'ambiente richiedono il tenant corrispondente o il diritto di accesso all'ambiente. Gli ambienti restituiti dalle operazioni di elenco sono limitati a quelli a cui può accedere il chiamante. Utilizza la Control API gerarchia dei diritti di accesso per concedere solo l'operazione read, create, update o delete richiesta.
Operazioni ambientali
Le operazioni dell'ambiente sono raggruppate sotto tenant tracks in Swagger.
| Operazione | Punto finale | Scopo |
|---|---|---|
| Lista | GET /!tracks |
Elenca gli ambienti accessibili con filtraggio e impaginazione opzionali. |
| Ottenere | GET /!track?name={name} |
Ottieni la configurazione completa per un ambiente. |
| Creare | POST /!track |
Creare un ambiente e il relativo metodo di autenticazione di accesso predefinito. |
| Aggiornamento | PUT /!track |
Sostituisci la configurazione dell'ambiente modificabile. |
| Eliminare | DELETE /!track?name={name} |
Elimina definitivamente un ambiente e i relativi dati. |
Aggiungi ciascun endpoint alla base endpoint.
Elencare e identificare gli ambienti
GET /!tracks accetta filterName e paginationToken. Il filtro corrisponde al name tecnico o al displayName, indipendentemente dal caso.
La risposta contiene una raccolta data e un paginationToken opaco. Per leggere la pagina successiva, ripetere la stessa richiesta con il token restituito e lo stesso filtro. Continua finché la risposta non contiene più un token. Non interpretare o modificare il token.
Il tecnico name identifica l'ambiente negli URL Control API e nelle successive operazioni di recupero, aggiornamento ed eliminazione. Trattalo come una chiave di automazione stabile. Utilizzare displayName per il testo presentato agli amministratori.
Crea un ambiente
I nomi degli ambienti sono in minuscolo. Fornisci un name quando un'integrazione richiede un URL prevedibile oppure omettilo e lascia che sia FoxIDs a generare un nome univoco. Una richiesta deve contenere un nome o un nome visualizzato.
La creazione di un ambiente crea anche il metodo di autenticazione di accesso predefinito. Altre applicazioni, metodi di autenticazione, utenti, chiavi e risorse ambientali vengono configurati separatamente dopo la creazione.
Il piano tenant può limitare il numero di ambienti. Una richiesta di creazione può quindi fallire quando viene raggiunto il limite. Le operazioni di creazione simultanee limitate al piano possono restituire 423 Locked; riprovare dopo un breve ritardo.
Aggiorna le impostazioni dell'ambiente
PUT /!track è un aggiornamento completo, non una patch. Per prima cosa ottieni l'ambiente corrente, preserva tutte le proprietà che dovrebbero rimanere invariate, applica le modifiche previste e invia la rappresentazione modificabile completa.
Il tecnico name seleziona l'ambiente e non viene rinominato da un aggiornamento. Le impostazioni modificabili includono la visualizzazione e i dettagli dell'azienda, la durata della sequenza, il comportamento di mappatura delle richieste, la protezione in caso di errore di accesso, le politiche sulla password, la password esterna e l'integrazione della directory e i domini iframe consentiti. Alcune risorse correlate, tra cui SMS, posta elettronica, mappature delle attestazioni, testi, chiavi e certificati, hanno endpoint dedicati e non vengono sostituite tramite l'operazione dell'ambiente.
Le impostazioni aggiornate vengono utilizzate dalle richieste successive dopo che FoxIDs ha invalidato la cache di configurazione dell'ambiente.
Elimina un ambiente
L'eliminazione di un ambiente è un'operazione irreversibile a catena. Rimuove la configurazione dell'ambiente e tutti i dati nell'ambito di tale ambiente, comprese le applicazioni, i metodi di autenticazione, gli utenti, le sessioni, le concessioni, le chiavi e altre risorse. Verranno rimossi anche i collegamenti da altri ambienti all'ambiente eliminato.
Non utilizzare l'eliminazione dell'ambiente come metodo per cancellare le risorse selezionate. Elimina o aggiorna tali risorse individualmente quando l'ambiente deve rimanere disponibile. Prima di eliminare un ambiente, interrompere il traffico verso di esso, esportare eventuali configurazioni o dati che devono essere conservati e verificare il nome tecnico nella richiesta.
Guida all'automazione
- Mantieni stabili i nomi tecnici e archiviali separatamente dai nomi visualizzati.
- Utilizza l'impaginazione dell'elenco anche quando un tenant attualmente dispone solo di pochi ambienti.
- Utilizza un flusso di lavoro get-modifica-metti per evitare di reimpostare involontariamente le impostazioni aggiunte in una versione FoxIDs più recente.
- Crea risorse dipendenti solo dopo che la richiesta di creazione dell'ambiente ha esito positivo.
- Considera l'eliminazione come un'operazione di smontaggio permanente e richiedi una conferma esplicita negli strumenti amministrativi.
- È previsto che le richieste di creazione, aggiornamento ed eliminazione vengano visualizzate nel registro di controllo del controllo. Le operazioni di lettura non vengono scritte come eventi di controllo.
Risposte agli errori comuni
400 Bad Requestquando i dati o il nome dell'ambiente non sono validi, viene utilizzato un nome riservato o viene raggiunto un limite del piano.401 Unauthorizedquando il token di accesso manca o non è valido.403 Forbiddenquando il chiamante non dispone del diritto di accesso richiesto.404 Not Foundquando l'ambiente selezionato non esiste.409 Conflictquando esiste già un ambiente con lo stesso nome tecnico.423 Lockedquando un'operazione di creazione limitata al piano è temporaneamente bloccata.
Utilizza il corpo della risposta per i dettagli di convalida e Swagger UI per le risposte dichiarate da ciascuna operazione.