Control API: applicazioni e metodi di autenticazione

Utilizzare FoxIDs Control API per configurare le applicazioni che ritengono attendibili FoxIDs e i metodi di autenticazione attendibili di FoxIDs. Nelle rotte e negli schemi Control API, la registrazione di un'applicazione è chiamata downparty e un metodo di autenticazione è chiamato upparty.

Prima di chiamare queste operazioni, configurare Control API i diritti di autenticazione e accesso. Swagger rimane il riferimento esatto per proprietà specifiche del protocollo, regole di convalida, operazioni di supporto e schemi di risposta:

• Swagger (OpenAPI) JSON
• Swagger UI

Base dell'endpoint e diritti di accesso

Gli esempi utilizzano FoxIDs Cloud:

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

Sostituisci {tenant_name} e {track_name} con tenant e i nomi tecnici dell'ambiente. Modificare l'host per una distribuzione self-hosted. Invia il token di accesso Control API nell'intestazione Authorization: Bearer {access_token}.

Queste operazioni richiedono un diritto di accesso party per l'ambiente di destinazione. Concedere solo l'operazione read, create, update o delete richiesta tramite la gerarchia dei diritti di accesso Control API.

Elencare e identificare le registrazioni

Utilizza questi endpoint per individuare le registrazioni prima di chiamare un endpoint specifico del tipo:

Le risposte dell'elenco contengono riepiloghi sicuri, il tipo di registrazione e un token di impaginazione opaco. Utilizzare l'operazione get specifica del tipo per la rappresentazione modificabile completa. Ripetere una richiesta impaginata con gli stessi filtri e il token restituito finché non viene restituito alcun token.

Il name tecnico è l'identificatore stabile utilizzato dalle operazioni di acquisizione, aggiornamento, eliminazione, segreto, chiave e relazione. I nomi sono in minuscolo. Fornisci un nome al momento della creazione quando un'integrazione richiede un identificatore prevedibile oppure lascia che sia FoxIDs a generarne uno. Utilizza l'helper !newpartyname quando è necessario un nome univoco prima della creazione di una risorsa.

Operazioni specifiche del tipo

Ogni tipo di risorsa ha il proprio endpoint perché la configurazione del protocollo è diversa. Gli endpoint principali sono:

Le operazioni usuali sono GET ?name={name}, POST per creare, PUT per aggiornare e DELETE ?name={name}. Aggiungi l'endpoint alla base endpoint. Consultare Swagger per le operazioni supportate da ciascun tipo.

La creazione di applicazioni o metodi di autenticazione è soggetta ai limiti dell'ambiente e del piano tenant. Alcune operazioni di creazione simultanee limitate al piano possono restituire 423 Locked; riprovare dopo un breve ritardo.

Aggiorna e rinomina in modo sicuro

Le operazioni del gruppo PUT sono aggiornamenti completi, non patch. Utilizza questo flusso di lavoro:

1. Elenca le risorse o ottieni la risorsa conosciuta in base al nome tecnico.
2. Ottieni la sua rappresentazione completa specifica del tipo.
3. Conserva le proprietà che dovrebbero rimanere invariate e applica le modifiche previste.
4. Invia la rappresentazione modificabile completa all'endpoint PUT specifico del tipo corrispondente.

Utilizza newName quando il nome tecnico deve cambiare. I riferimenti vengono aggiornati come parte del flusso di ridenominazione. Il metodo di autenticazione di accesso predefinito denominato login non può essere rinominato o eliminato.

I segreti client, le chiavi client e alcuni segreti API esterni sono gestiti da endpoint dedicati. Essi non vengono volutamente restituiti come testo in chiaro nella rappresentazione generale del partito e non devono essere copiati in una normale richiesta di aggiornamento.

Connetti le applicazioni ai metodi di autenticazione

La raccolta allowUpParties di un'applicazione controlla quali metodi di autenticazione possono essere utilizzati per accedere a tale applicazione. I metodi di autenticazione a cui si fa riferimento devono esistere nello stesso ambiente ed essere compatibili con la configurazione.

Tratta questa relazione come parte della configurazione completa dell'applicazione durante l'aggiornamento. L'eliminazione di un metodo di autenticazione può modificare il routing di accesso per le applicazioni che vi fanno riferimento; verificare le applicazioni dipendenti prima dell'eliminazione. Utilizza un Environment Link quando il metodo di autenticazione o l'applicazione è intenzionalmente connessa tra gli ambienti FoxIDs.

Gestisci segreti e chiavi

Le applicazioni OAuth 2.0 e OpenID Connect forniscono operazioni client-secret dedicate. Un segreto viene accettato quando viene creato, archiviato come hash e non restituito in testo normale. La risposta dell'elenco contiene gli identificatori e le informazioni sicure necessarie per gestire i segreti esistenti.

Utilizza credenziali sovrapposte per la rotazione:

1. Genera un nuovo segreto client e archivialo in modo sicuro.
2. Crea il segreto client in FoxIDs e distribuisci lo stesso valore all'applicazione che lo utilizza.
3. Verificare che l'applicazione utilizzi il nuovo segreto.
4. Elimina il vecchio segreto tramite la sua applicazione e gli identificatori segreti.

I metodi di autenticazione OpenID Connect e OAuth 2.0 possono utilizzare operazioni client-secret o chiave client dedicate, a seconda del metodo di autenticazione client selezionato. Un'operazione con chiave privata accetta il certificato e il materiale della chiave privata. External Login ha un endpoint segreto dedicato. Utilizza l'endpoint esatto e lo schema di richiesta mostrati in Swagger per il tipo di registrazione selezionato.

I segreti, le chiavi private e i payload completi dei certificati sono sensibili. Utilizza TLS, concedi l'accesso solo ai client di automazione attendibili, proteggi i valori inattivi e non registrare i corpi delle richieste o delle risposte.

Metadati e aiutanti per la scoperta

Le operazioni di supporto del protocollo riducono la configurazione manuale ma non sostituiscono la convalida della risorsa risultante:

• I metodi di autenticazione OpenID Connect e OAuth 2.0 possono leggere i metadati di rilevamento e popolare le impostazioni compatibili.
• SAML 2.0 registrazioni di applicazioni e metodi di autenticazione possono leggere i metadati.
• WS-Federation registrazioni di applicazioni e metodi di autenticazione possono leggere i metadati.
• WS-Federation metodi di autenticazione includono un assistente per la sincronizzazione dell'ID Microsoft Entra.

Dopo aver utilizzato un helper, ispeziona la configurazione restituita, applica la policy locale e le impostazioni delle attestazioni e salvala tramite l'endpoint di creazione o aggiornamento specifico del tipo. I metadati possono cambiare nel tempo, quindi è necessario definire se la sincronizzazione è un'azione amministrativa esplicita o un processo ricorrente controllato.

Eliminazione ed effetti di dipendenza

L'eliminazione di un'applicazione interrompe le nuove richieste di protocollo per quell'applicazione. L'eliminazione di un metodo di autenticazione può impedire alle applicazioni di completare l'accesso e può alterare le scelte di Home Realm Discovery. Rimuovere o aggiornare prima le dipendenze e considerare entrambe le operazioni come modifiche permanenti alla configurazione.

Le richieste di creazione, aggiornamento, segreto/chiave, helper ed eliminazione sono incluse 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 le impostazioni del protocollo, i riferimenti, i metadati, i segreti, le chiavi o i nomi non sono validi o viene raggiunto un limite del piano.
• 401 Unauthorized quando il token di accesso manca o non è valido.
• 403 Forbidden quando il chiamante non dispone del diritto di accesso richiesto.
• 404 Not Found quando la registrazione, il segreto o la chiave selezionati non esistono.
• 409 Conflict quando esiste già un nome tecnico o un identificatore segreto.
• 423 Locked quando 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.

Documentazione correlata

• Control API autenticazione e diritti di accesso
• Applicazioni
• Metodi di autenticazione
• Environment Link
• Rivendicazioni e trasformazioni delle rivendicazioni