Segreti nell’API di Reactor

Nell’API di Reactor, un segreto è una risorsa che rappresenta una credenziale di autenticazione. I segreti vengono utilizzati nell’inoltro degli eventi per l’autenticazione in un altro sistema per lo scambio sicuro dei dati. Pertanto, è possibile creare segreti solo all'interno delle proprietà di inoltro degli eventi (proprietà il cui attributo platform è impostato su edge).

Sono attualmente disponibili tre tipi di segreto supportati identificati nell'attributo type_of:

Questa guida fornisce una panoramica di alto livello sulla configurazione dei segreti da utilizzare nell’inoltro degli eventi. Per istruzioni dettagliate su come gestire i segreti nell'API di Reactor, incluso un esempio di JSON della struttura di un segreto, consulta la guida dell'endpoint dei segreti.

Credenziali

Ogni segreto contiene un attributo credentials che contiene i rispettivi valori delle credenziali. Quando si crea un segreto nell'API, ogni tipo di segreto ha attributi obbligatori diversi, come illustrato nelle sezioni seguenti:

token token

I segreti con un valore type_of di token richiedono un solo attributo in credentials:

Il token viene archiviato come valore statico, pertanto le proprietà expires_at e refresh_at del segreto vengono impostate su null al momento della creazione del segreto.

simple-http simple-http

I segreti con un valore type_of di simple-http richiedono i seguenti attributi in credentials:

Quando viene creato il segreto, i due attributi vengono scambiati con una codifica BASE64 di username:password. Dopo lo scambio, le proprietà expires_at e refresh_at del segreto sono impostate su null.

oauth2-client_credentials oauth2-client_credentials

I segreti con un valore type_of di oauth2-client_credentials richiedono i seguenti attributi in credentials:

Quando viene creato o aggiornato un segreto oauth2-client_credentials, gli elementi client_id e client_secret (e probabilmente options) vengono scambiati in una richiesta POST a token_url, in base al flusso delle credenziali client del protocollo OAuth.

Se il servizio di autorizzazione risponde con 200 OK e un corpo di risposta JSON, il corpo viene analizzato e access_token viene inviato all'ambiente perimetrale e expires_in viene utilizzato per calcolare gli attributi expires_at e refresh_at per il segreto. Se non è presente alcuna associazione di ambiente sul segreto, access_token verrà eliminato.

Uno scambio di credenziali viene considerato riuscito nelle seguenti condizioni:

Se lo scambio ha esito positivo, l'attributo di stato del segreto è impostato su succeeded e i valori per expires_at e refresh_at sono impostati:

Se lo scambio non riesce per qualsiasi motivo, l'attributo status_details nell'oggetto meta viene aggiornato con le informazioni rilevanti.

Aggiornamento di un segreto oauth2-client_credentials

Se a un ambiente è stato assegnato un segreto oauth2-client_credentials e il relativo stato è succeeded (le credenziali sono state scambiate correttamente), viene eseguito automaticamente un nuovo scambio il refresh_at.

Se lo scambio ha esito positivo, l'attributo refresh_status nell'oggetto meta è impostato su succeeded mentre expires_at, refresh_at e activated_at sono aggiornati di conseguenza.

Se lo scambio non riesce, l’operazione viene tentata altre tre volte, con l’ultimo tentativo non più di due ore prima della scadenza del token di accesso. Se tutti i tentativi non vanno a buon fine, l'attributo refresh_status_details dell'oggetto meta viene aggiornato con i relativi dettagli.

oauth2-google oauth2-google

I segreti con un valore type_of di oauth2-google richiedono l'attributo seguente in credentials:

Dopo aver creato il segreto oauth2-google, la risposta include una proprietà meta.authorization_url. È necessario copiare e incollare questo URL in un browser per completare il flusso di autenticazione di Google.

Riautorizza un segreto oauth2-google

L'URL di autorizzazione per un segreto oauth2-google scade un'ora dopo la creazione del segreto (come indicato da meta.authorization_url_expires_at). Trascorso questo periodo, il segreto deve essere nuovamente autorizzato per rinnovare il processo di autenticazione.

Per informazioni dettagliate su come autorizzare nuovamente un segreto oauth2-google effettuando una richiesta PATCH all'API di Reactor, consultare la guida dell'endpoint "secrets".

Relazione ambiente

Quando si crea un segreto, è necessario specificare l'ambiente in cui verrà creato. I segreti vengono distribuiti immediatamente nell’ambiente in cui vengono creati.

Un segreto può essere associato a un solo ambiente. Una volta stabilita la relazione tra un segreto e un ambiente, il segreto non può essere cancellato dall’ambiente e non può essere associato a un ambiente diverso.

Dopo lo scambio delle credenziali di un segreto, per associare un segreto a un ambiente, l'artefatto di scambio (la stringa del token per token, la stringa di codifica Base64 per simple-http o il token di accesso per oauth2-client_credentials) viene salvato in modo sicuro nell'ambiente.

Una volta salvato correttamente l'artefatto di scambio nell'ambiente, l'attributo activated_at del segreto viene impostato sull'ora UTC corrente e ora è possibile farvi riferimento utilizzando un elemento dati. Per ulteriori informazioni sui riferimenti ai segreti, consulta la sezione successiva.

Segreti di riferimento referencing-secrets

Per fare riferimento a un segreto, è necessario creare un elemento dati di tipo "Segreto" (fornito dall'estensione Core) in una proprietà di inoltro eventi. Durante la configurazione di questo elemento dati, viene richiesto di indicare il segreto da utilizzare per ogni ambiente. Puoi quindi creare regole che fanno riferimento a un elemento dati segreto, ad esempio all’interno dell’intestazione di una chiamata HTTP.

In fase di esecuzione, l’elemento dati segreto viene sostituito con il corrispondente artefatto di scambio segreto salvato nell’ambiente.

Passaggi successivi

Questa guida descrive le nozioni di base sull’utilizzo dei segreti nell’API di Reactor. Per informazioni dettagliate su come gestire i segreti tramite chiamate API, consulta la guida dell'endpoint "secrets".