Control API - tenant amministrazione

FoxIDs dispone di superfici Control API separate per gli operatori di distribuzione che amministrano tenants e per un tenant che amministra il proprio account. Utilizza le operazioni dell'operatore per il provisioning di tenant e l'amministrazione tra tenant. Utilizza le operazioni self-service quando un'integrazione deve essere limitata al proprio tenant.

Prima di chiamare queste operazioni, configurare Control API i diritti di autenticazione e accesso. Swagger rimane il riferimento esatto per proprietà tenant, opzioni di piano e pagamento, regole di convalida e schemi di risposta:

API superfici

Operatore di distribuzione

Le operazioni dell'operatore vengono chiamate in master tenant:

https://control.foxids.com/api/master/master

Operazione	Punto finale	Scopo
Lista	`GET /!tenants`	Elenca non master tenants con filtri e impaginazione opzionali.
Ottenere	`GET /!tenant?name={name}`	Leggi la risorsa amministrativa di un tenant.
Creare	`POST /!tenant`	Effettua il provisioning di un tenant, dell'amministratore iniziale e delle risorse predefinite.
Aggiornamento	`PUT /!tenant`	Sostituisci le proprietà tenant modificabili gestite dall'operatore.
Eliminare	`DELETE /!tenant?name={name}`	Elimina definitivamente un tenant e tutti i dati tenant.

Queste operazioni richiedono diritti di accesso master-tenant. Sono destinati all'amministrazione di distribuzioni attendibili e ai servizi di provisioning di SaaS.

Tenant self-service

A tenant richiama le proprie operazioni attraverso il suo ambiente master:

https://control.foxids.com/api/{tenant_name}/master

Operazione	Punto finale	Scopo
Ottenere	`GET /!mytenant`	Leggere l'account tenant del chiamante e le impostazioni disponibili.
Aggiornamento	`PUT /!mytenant`	Aggiorna le proprietà self-service consentite.
Eliminare	`DELETE /!mytenant`	Elimina definitivamente i dati tenant e tutti i dati tenant del chiamante.

Il self-service utilizza i diritti di accesso tenant e non può amministrare un altro tenant. Anche le modifiche al piano, le impostazioni di pagamento e i domini personalizzati sono soggetti alle policy configurate della distribuzione.

Modifica l'host in questi esempi per una distribuzione self-hosted e invia il token di accesso nell'intestazione Authorization: Bearer {access_token}.

Elenca e identifica tenants

GET /!tenants accetta filterName, filterCustomDomain e paginationToken. Quando vengono forniti entrambi i filtri, viene restituito un tenant quando il suo nome o il dominio personalizzato corrispondono. I record master tenant e tenant di solo utilizzo interno non sono inclusi.

Ripetere una richiesta impaginata con gli stessi filtri e il token opaco restituito finché non viene restituito alcun token. Non interpretare o modificare il token.

Il minuscolo tenant name è l'identificatore stabile utilizzato negli URL FoxIDs e Control API. Trattatelo come una chiave di automazione immutabile. Un dominio personalizzato è una proprietà di routing e branding separata e non deve essere utilizzato come nome del percorso Control API tenant.

Fornisci un tenant

La creazione di Tenant è un'operazione di provisioning composta. Una richiesta riuscita crea:

il record tenant;
l'ambiente master di tenant e il relativo metodo di autenticazione di accesso predefinito;
l'utente amministratore iniziale;
la risorsa Control API e l'applicazione Control Client;
gli ambienti predefiniti configurati della distribuzione.

L'amministratore iniziale può ricevere una password fornita o stabilire una password tramite il flusso di posta elettronica configurato. Proteggi qualsiasi password fornita e non registrare il corpo della richiesta.

La richiesta può anche selezionare un piano e inizializzare le impostazioni del cliente, delle richieste e del dominio personalizzato laddove la distribuzione lo consente. Tenant l'unicità del nome, le regole del piano, il supporto del dominio personalizzato e i dati amministrativi richiesti vengono convalidati prima del completamento del provisioning. Se un errore nell'account o nei dati interrompe il provisioning, FoxIDs tenta di pulire le risorse create da tale richiesta; tuttavia, i client devono considerare qualsiasi errore come non riuscito e verificare lo stato prima di riprovare con lo stesso nome tenant.

Aggiorna tenant impostazioni

Tenant PUT operazioni sono aggiornamenti completi, non patch. Ottieni la risorsa corrente, conserva tutte le proprietà modificabili che dovrebbero rimanere invariate, applica la modifica prevista e invia il modello di richiesta completo per l'operatore selezionato o l'endpoint self-service.

La risorsa dell'operatore include proprietà gestite dalla distribuzione come l'assegnazione del piano, la verifica del dominio personalizzato, la configurazione dell'utilizzo e del pagamento, la valuta, l'IVA, il prezzo orario e i dati del cliente. La risorsa self-service espone solo le impostazioni che tenant può gestire.

La modifica di un dominio personalizzato tramite self-service contrassegna il dominio come non verificato fino al completamento della verifica richiesta. Il piano selezionato deve supportare un dominio personalizzato. Utilizza l'operatore API per gestire lo stato di verifica; non consentire a un client tenant non attendibile di affermare che il proprio dominio è verificato.

Elimina un tenant

L'eliminazione di Tenant è irreversibile e a catena. Elimina ogni ambiente in tenant e tutte le applicazioni con ambito, metodi di autenticazione, utenti, sessioni, concessioni, chiavi e altri dati FoxIDs. Rimuove inoltre la configurazione a livello di tenant e il routing del dominio personalizzato. Impossibile eliminare master tenant. I log già inviati a un repository esterno rimangono soggetti alla politica di conservazione ed eliminazione di tale repository.

Prima dell'eliminazione, interrompi il traffico, esporta la configurazione o i dati che devono essere conservati, annulla o riconcilia la fatturazione esterna, ove applicabile, e verifica il nome tecnico di tenant. Richiedere conferma esplicita negli strumenti dell'operatore. Non utilizzare l'eliminazione di tenant per disabilitare temporaneamente l'accesso; disabilitare o aggiornare invece gli utenti, le applicazioni o i metodi di autenticazione pertinenti.

Guida all'automazione e alla sicurezza

Preferisci endpoint self-service quando un client deve gestire solo il proprio tenant.
Limita le credenziali dell'operatore a un servizio di provisioning piccolo e affidabile.
Mantieni stabile il nome tecnico tenant e memorizzalo indipendentemente dai dati di visualizzazione, cliente e dominio personalizzato.
Utilizza get-modify-put in modo che le nuove proprietà non vengano reimpostate da un'integrazione precedente.
Utilizza l'impaginazione per gli inventari tenant ed effettua la riconciliazione in base al nome tecnico.
Tratta la creazione e l'eliminazione di tenant come azioni amministrative composte a lunga esecuzione; utilizzare timeout client appropriati e verificare lo stato finale dopo una risposta interrotta.
È 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 Request quando i dati di tenant, amministratore, piano, pagamento, cliente o dominio personalizzato non sono validi.
401 Unauthorized quando il token di accesso manca o non è valido.
403 Forbidden quando il chiamante non dispone del diritto di accesso master o tenant richiesto.
404 Not Found quando il tenant selezionato non esiste.
409 Conflict quando esiste già un nome tenant o un altro valore univoco.

Utilizza il corpo della risposta per i dettagli di convalida e Swagger UI per le risposte dichiarate da ciascuna operazione.