Trasformazioni e attivita dei claim

Ogni metodo di autenticazione e registrazione applicativa di FoxIDs gestisce i claim e supporta trasformazioni e attivita dei claim. Questo significa che piu insiemi di trasformazioni e attivita dei claim possono essere eseguiti per ogni autenticazione utente. Prima vengono eseguite le trasformazioni e le attivita dei claim sul metodo di autenticazione, poi sulla registrazione applicativa.

Ulteriori sottoinsiemi di trasformazioni e attivita dei claim possono essere eseguiti se viene creato un utente o un utente esterno.

Nei metodi di autenticazione con un elenco Forward claims, aggiungere a tale elenco i claim ordinari creati dalle trasformazioni di primo livello per renderli disponibili nei passaggi successivi, oppure includere * (predefinito). I metodi Login inoltrano questi claim senza tale elenco.

I prefissi riservati _local:, _internal:, _session: e _impersonate: determinano come vengono usati i claim durante l’autenticazione. Vedere Claim locali, interni e di sessione per le diverse durate.

Per emettere un claim ordinario da una registrazione di applicazione, aggiungerlo oppure aggiungere * a Issue claims. Con OpenID Connect è anche possibile aggiungerlo ai Voluntary claims di uno scope e richiedere lo scope dall’applicazione. I claim riservati non vengono emessi, neppure con *.

Consulta gli esempi di trasformazione dei claim.

Abilita Log claim trace nelle impostazioni di log per vedere i claim prima e dopo la trasformazione nei log.

Le trasformazioni dei claim possono essere configurate in un metodo di autenticazione login.

E le attivita dei claim.

Allo stesso modo, trasformazioni e attivita dei claim possono essere configurate come primo e secondo livello in un metodo di autenticazione OpenID Connect.

I claim sono rappresentati per impostazione predefinita come claim JWT. Se il metodo di autenticazione e SAML 2.0, i claim di primo livello sono rappresentati come claim SAML 2.0. Se la registrazione applicativa e SAML 2.0, i claim sono rappresentati come claim SAML 2.0.

Una trasformazione di claim e un'attivita di claim eseguono una delle sette possibili azioni, a seconda del tipo specifico di trasformazione o attivita.

Azioni di trasformazioni e attivita dei claim:

• Add claim - aggiungere un nuovo claim
• Add claim, if not match - eseguire l'azione di aggiunta se la condizione non corrisponde
• Replace claim - aggiungere un nuovo claim e rimuovere i claim esistenti se ne esiste uno o piu
• Replace claim, if not match - eseguire l'azione di sostituzione se la condizione non corrisponde
• Remove claim - rimuovere i claim se ne esiste uno o piu
• If match - eseguire l'azione se la condizione corrisponde
• If not match - eseguire l'azione se la condizione non corrisponde

Le trasformazioni e le attivita dei claim vengono eseguite in ordine, e quindi anche le azioni vengono eseguite in ordine. Questo significa che e possibile creare una variabile locale aggiungendo un claim e piu avanti nella sequenza prendere decisioni basate su quel claim. Un claim e locale nell'insieme di trasformazioni e attivita dei claim se inizia con _local:.

Quando trasformazioni e attivita dei claim vengono eseguite in un flusso di login, FoxIDs aggiunge automaticamente claim locali dalla richiesta di login prima di eseguire le trasformazioni. Questi claim _local: sono destinati a decisioni interne nella sequenza trasformazione/attivita e vengono rimossi dall'output.

Claim locali generali aggiunti dalla richiesta di accesso:

• _local:login_action - l'azione della richiesta di login, memorizzata in camelCase
• _local:user_id - l'ID utente della richiesta di login (solo se fornito)
• _local:max_age - il max age della richiesta di login (solo se impostato e maggiore di 0)
• _local:login_hint - l'hint della richiesta di login (solo se fornito)
• _local:acr - i valori ACR della richiesta di login come elenco delimitato da spazi (solo se fornito)
• _local:params:{name} - un parametro di richiesta dell’applicazione consentito, con il nome del parametro in minuscolo e un claim per valore (solo se fornito)

Quando un metodo di autenticazione viene usato come elemento di Advanced MFA, le sue trasformazioni di claim ricevono i seguenti claim locali per l’utente già autenticato dal metodo di autenticazione Login:

Claim	Valore
_local:mfa:user_id	L’ID utente tecnico stabile dell’utente in FoxIDs.
_local:mfa:user_identifier	L’identificatore usato per l’autenticazione Login. Se non è stato fornito alcun identificatore, FoxIDs usa l’indirizzo e-mail, il numero di telefono o il nome utente.
_local:mfa:username	Il nome utente registrato dell’utente.
_local:mfa:email	L’indirizzo e-mail registrato dell’utente, oppure il valore del suo claim email se l’indirizzo registrato è vuoto.
_local:mfa:phone	Il numero di telefono registrato dell’utente, oppure il valore del suo claim phone_number se il numero registrato è vuoto.

Vengono aggiunti solo i claim con un valore non vuoto. Queste trasformazioni elaborano i claim restituiti dal provider di identità esterno e possono aggiungere il valore AMR richiesto dall’elemento MFA. Il flusso MFA di Login usa la risposta trasformata per convalidare tale valore AMR. Gli altri claim restituiti dal metodo di autenticazione non vengono uniti ai claim del metodo di autenticazione Login né passati alle sue trasformazioni di claim generali.

Con l'azione Add claim, if not match e possibile aggiungere un claim (variabile locale) se un altro claim o un valore di claim non esiste.

Tipi di claim transform che supportano tutte le azioni:

• Match claim - controlla se il tipo di claim selezionato esiste. Per le azioni add e replace, il claim in uscita viene scritto con il nuovo valore quando il claim esiste. Le azioni if not match vengono eseguite quando il claim manca. Un'azione remove rimuove il claim in uscita selezionato quando il claim esiste.
• Match claim and value - controlla se il tipo di claim selezionato esiste con il valore configurato. Per le azioni add e replace, il claim in uscita viene scritto con il nuovo valore quando tipo e valore corrispondono. Le azioni if not match vengono eseguite quando il claim esiste ma il valore non corrisponde. Un'azione remove rimuove il claim in uscita selezionato quando tipo e valore corrispondono.
• Regex match - controlla se il tipo di claim selezionato esiste e se il valore corrisponde all'espressione regolare configurata. Per le azioni add e replace, il claim in uscita viene scritto con il nuovo valore quando l'espressione regolare corrisponde. Le azioni if not match vengono eseguite quando il claim esiste ma il valore non corrisponde all'espressione regolare. Un'azione remove rimuove il claim in uscita selezionato quando l'espressione regolare corrisponde.

Tipi di claim transform che supportano le azioni Add claim, Replace claim e Add claim, if new claim does not exist:

• Map - copia il valore del claim selezionato nel claim in uscita. Con Add claim, if new claim does not exist, il valore viene scritto solo se il claim in uscita non esiste già.
• Regex map - estrae il gruppo regex denominato map dal valore del claim selezionato e scrive il valore estratto nel claim in uscita. Con Add claim, if new claim does not exist, il valore viene scritto solo se il claim in uscita non esiste già.

Tipi di claim transform che supportano le azioni Add claim e Replace claim:

• Constant - scrive sempre il valore costante configurato nel claim in uscita.
• Concatenate - costruisce il claim in uscita dai valori nei claim selezionati. La stringa di formato usa placeholder come {0}, {1} e {2} per i valori selezionati in ordine.
• External claims API - invia i claim selezionati a una API esterna. I claim restituiti dall'API vengono aggiunti o sostituiscono i claim in uscita.
• Impersonation - prepara un target locale selezionato come utente effettivo dopo le trasformazioni del metodo di autenticazione. Vedere Impersonificazione.
• DK XML privilege to JSON - converte un claim XML DK privilege in claim JSON, un claim per ogni elemento XML PrivilegeGroup.

Tipi di claim task che supportano le azioni Add claim e Replace claim:

• Query internal user - usa il valore del lookup claim per trovare esattamente un utente interno, quindi aggiunge o sostituisce i claim selezionati di quell'utente nel claim set corrente.
• Query external user - usa il valore del lookup claim per trovare esattamente un utente esterno, quindi aggiunge o sostituisce i claim selezionati di quell'utente nel claim set corrente.
• Save claim on internal user - usa il valore del lookup claim per trovare esattamente un utente interno, quindi aggiunge o sostituisce il claim selezionato su quell'utente con i valori del claim di update value selezionato nel claim set corrente.
• Save claim on external user - usa il valore del lookup claim per trovare esattamente un utente esterno, quindi aggiunge o sostituisce il claim selezionato su quell'utente con i valori del claim di update value selezionato nel claim set corrente.

Tutte e quattro le attività utente elencate sopra considerano un utente non disponibile quando l'account è disabilitato direttamente o tramite una membership attiva in una struttura di accesso. L'utente viene escluso prima che FoxIDs determini se la ricerca ha trovato esattamente un utente, quindi le attività query non aggiungono claims e le attività save non apportano modifiche.

Quando una delle due attività query user viene eseguita su un metodo di autenticazione e nessun account locale è già associato alla risposta di autenticazione corrente, il primo utente abbinato in modo univoco nell'ordine di esecuzione delle claim transformations diventa l'account locale della risposta. Un'attività Query internal user con Target fornisce solo claims locali e lascia invariata questa associazione dell'account. Se l'autenticazione continua attraverso passaggi Extended UI, FoxIDs conserva lo snapshot di accesso dell'account selezionato nella sequenza server-side e lo usa quando la risposta viene completata. FoxIDs applica quindi l'associazione alle sessioni attive e ai refresh token grants. Un utente interno o un utente esterno connesso autenticato direttamente dal metodo di autenticazione ha la precedenza e un'associazione esistente non viene mai sostituita da una query successiva.

Se una claim transformation avvia interattivamente un altro metodo di autenticazione, l'autenticazione reindirizzata viene eseguita come un nuovo login flow. Un'associazione all'account locale selezionata da una query precedente non viene mantenuta attraverso il reindirizzamento.

Le attività query user su una registrazione applicazione possono aggiungere claims, ma non creano né modificano l'associazione all'account locale del login.

Le attività query user rendono disponibile l'ID stabile dell'utente selezionato come claim locale:

Claim task	Claim locale	Valore
Query internal user	_local:internal_user_id	L'ID utente tecnico e stabile di FoxIDs dell'utente interno selezionato.
Query external user	_local:external_user_id	L'ID utente esterno tecnico e stabile di FoxIDs dell'utente esterno selezionato.

Selezionare esplicitamente il claim locale negli outgoing claims dell'attività, oppure selezionare *, per renderlo disponibile alle trasformazioni successive nella stessa sequenza. I claims locali vengono rimossi dall'output finale, a meno che il loro valore non sia mappato a un claim non locale.

Ad esempio, dopo aver cercato un utente interno tramite e-mail o nome utente, un'attività Match claim and return error può verificare _local:internal_user_id e interrompere il flow se non è stato trovato un utente interno univoco. Una trasformazione Match claim può invece aggiungere un altro claim solo quando la ricerca ha esito positivo. L'ID utente stabile rimane locale alla sequenza di trasformazioni, pur fornendo una base affidabile per le decisioni successive.

Per Query internal user e Save claim on internal user, il lookup claim viene letto dal claim set corrente. Il valore Lookup claim on internal user definisce come viene abbinato l'utente interno:

• sub corrisponde all'ID utente dell'utente interno.
• email, phone_number e preferred_username cercano prima negli identifiers dell'utente interno con matching case-insensitive quando la capitalizzazione è rilevante. Se nessun utente viene trovato tramite identifier, la ricerca continua nei claim memorizzati dell'utente.
• La ricerca continua quindi nei claim memorizzati dell'utente interno per lo stesso tipo di claim e un valore corrispondente senza distinzione tra maiuscole e minuscole. Questo vale per tutti i tipi di lookup claim se prima non è stato trovato un utente.

Se la ricerca trova esattamente un utente interno, Query internal user aggiunge o sostituisce i claim selezionati di quell'utente nel claim set corrente. Save claim on internal user aggiunge o sostituisce il claim selezionato su quell'utente con i valori del claim di update value selezionato. Se non viene trovato alcun utente, o se tramite claim viene trovato più di un utente, non vengono aggiunti o salvati claim utente interni.

Per Query external user e Save claim on external user, il lookup claim viene letto dal claim set corrente e confrontato con la sorgente utente esterna selezionata. Usa link_claim come lookup claim sull'utente esterno per abbinare il valore link claim dell'utente esterno.

Tipi di claim task che supportano le azioni If match e If not match:

• Match claim and return error - restituisce un errore se il tipo di claim corrisponde o non corrisponde.
• Match claim and value and return error - restituisce un errore se il tipo e il valore del claim corrispondono o non corrispondono.
• Regex match and return error - restituisce un errore se il tipo e il valore del claim corrispondono o non corrispondono all'espressione regolare.
• Match claim and log event - scrive il valore del claim selezionato nel log se il tipo di claim corrisponde.
• Match claim and start authentication - avvia un nuovo login flow iniziando un metodo di autenticazione se il tipo di claim corrisponde o non corrisponde.
• Match claim and value and start authentication - avvia un nuovo login flow iniziando un metodo di autenticazione se il tipo e il valore del claim corrispondono o non corrispondono.
• Regex match and start authentication - avvia un nuovo login flow iniziando un metodo di autenticazione se il tipo e il valore del claim corrispondono o non corrispondono all'espressione regolare.

Per i return error task, configura l'errore di protocollo restituito al client o requester. Le configurazioni OpenID Connect e OAuth 2.0 restituiscono un error e una error description opzionale. Le configurazioni SAML 2.0 restituiscono uno status code SAML e un message.

Gli start authentication claim task possono essere usati per step-up quando l'utente ha effettuato l'accesso con un fattore e ne è richiesto un altro, oppure se sono necessarie informazioni aggiuntive (claims).

Caricare un utente interno in claims locali

Impostare il Target facoltativo di Query internal user per caricare i claims di un altro utente per verifiche o trasformazioni, mantenendo l'associazione dell'accesso all'account locale. Inserire un nome come target; FoxIDs aggiunge _local: e posiziona il nome prima di ogni tipo di claim selezionato:

Claim selezionato	Risultato locale con Target target
sub	_local:target:sub
email	_local:target:email
role	_local:target:role
_local:internal_user_id	_local:target:_local:internal_user_id
_local:access_node	_local:target:_local:access_node
_local:access_claim	_local:target:_local:access_claim
_local:access_path_claim	_local:target:_local:access_path_claim

Il tipo di claim originale completo viene conservato sotto il nome del target. Questo distingue i claim ausiliari locali degli account e di Access Structure dai claim ordinari. La ricerca include i claim derivati dalle appartenenze Access Structure attive, rispettando l’impostazione Forward claims della struttura, e i claim ausiliari locali per verificare le appartenenze.

Selezionare i claims tramite i nomi originali in Claims from internal user, oppure usare *. Il nome completo del claim locale, inclusi il prefisso e il nome del target, deve rispettare il limite di 100 caratteri. Lasciare Target vuoto per aggiungere o sostituire i claims selezionati direttamente nella raccolta di claims corrente.

Più ricerche e chiamate a Claims API possono popolare lo stesso target. Add claim aggiunge i valori restituiti. Replace claim sostituisce i valori dei tipi di claim restituiti sotto quel target e conserva gli altri claims già presenti.

Usare i claims del target nelle trasformazioni successive dello stesso insieme. Ad esempio, verificare _local:target:role oppure mappare _local:target:sub su _internal:selected_user_id per conservare il valore per gli insiemi di trasformazioni successivi. I claims locali del target vengono rimossi alla fine dell'insieme.

Claim locali, interni e di sessione

Usare questi prefissi per scegliere la durata di un valore utilizzato dalle trasformazioni e dalle attività sui claim. Un insieme di trasformazioni è un elenco ordinato di trasformazioni e attività: ad esempio, il primo livello del metodo di autenticazione, un elenco Extended UI, il secondo livello oppure l’elenco di una registrazione di applicazione. Il passaggio a un altro insieme è rilevante anche se entrambi appartengono allo stesso metodo.

Prefisso	Utilizzo	Dove è disponibile il valore	Disponibile a un successivo accesso a un’applicazione?
_local:	Valore o decisione temporanei in un insieme	Trasformazioni e attività successive dello stesso insieme. Rimosso al termine dell’insieme.	No. FoxIDs può fornire un nuovo contesto locale di richiesta o attività in un nuovo insieme.
_internal:	Valore necessario agli insiemi successivi del flusso di autenticazione corrente	Trasformazioni del metodo, continuazioni come Extended UI e trasformazioni dell’applicazione. Rimosso prima che la risposta del protocollo lasci FoxIDs.	No. Creare o copiare nuovamente il valore nel nuovo flusso.
_session:	Piccolo valore conservato per lo stesso utente autenticato	Ripristinato prima del primo livello; disponibile nelle trasformazioni intermedie e nel secondo livello. Salvato dopo un secondo livello completato correttamente e rimosso prima delle trasformazioni dell’applicazione.	Sì, tramite lo stesso metodo di autenticazione finché la sessione dell’utente è valida.
_impersonate:	Un’identità di destinazione preparata per l’impersonificazione	Trasformazioni del metodo di autenticazione ed Extended UI fino al completamento dell’impersonificazione dopo le trasformazioni di secondo livello.	Preparare nuovamente il target a ogni flusso di accesso.

Ad esempio, _local:customer_found può controllare l’attività successiva dello stesso elenco; _internal:customer_category può essere letto in seguito da una trasformazione dell’applicazione; _session:profileId può conservare un profilo selezionato per il prossimo accesso a un’applicazione.

Le trasformazioni che creano un utente esterno collegato operano sui claim selezionati per quel passaggio insieme ai claim _session: correnti. Selezionare un claim _internal: come input se le trasformazioni di creazione ne richiedono il valore. I claim di sessione rimangono nel flusso di autenticazione e non vengono salvati nell’account dell’utente esterno.

Trasformazioni come Constant, Map, Match claim e Match claim and value possono creare o usare questi claim con le azioni abituali. Il prefisso controlla la durata. Usare _session: sul metodo di autenticazione: i claim di sessione creati dalle trasformazioni dell’applicazione non vengono salvati nella sessione del metodo.

Copiare un valore in una durata diversa

Una trasformazione Map copia un valore nel claim di output selezionato. Origine e destinazione sono claim distinti con la durata dei rispettivi prefissi. Se i nomi differiscono, Replace claim sostituisce i valori esistenti del claim di destinazione e conserva quello di origine. Modifiche successive a uno non aggiornano automaticamente l’altro.

Ad esempio, quando un’attività Query internal user restituisce _local:internal_user_id, aggiungere nello stesso insieme una trasformazione Map da _local:internal_user_id a _internal:selected_user_id. Gli insiemi successivi possono leggere _internal:selected_user_id dopo la rimozione del claim locale. Una trasformazione del metodo può analogamente copiare un valore _internal: in un claim _session: per conservarlo negli accessi successivi.

Trasmettere un valore di sessione alle trasformazioni dell’applicazione

Supponendo che _session:profileId contenga customer-456 e che le trasformazioni dell’applicazione richiedano il valore, configurare questa trasformazione nell’elenco di secondo livello del metodo, dopo quelle che modificano il profilo selezionato:

Impostazione	Valore
Tipo di trasformazione	Map
Azione	Replace claim
Claim di input	_session:profileId
Claim di output	_internal:profileId

Il flusso prosegue così:

1. Entrambi i claim contengono customer-456 durante le trasformazioni rimanenti del metodo.
2. Al termine del secondo livello, FoxIDs salva _session:profileId per gli accessi successivi e lo rimuove dalla raccolta corrente di claim.
3. _internal:profileId raggiunge le trasformazioni dell’applicazione, che possono usarlo per prendere decisioni senza emetterlo all’applicazione.
4. Se l’applicazione richiede il valore nel token o nell’assertion, aggiungere una trasformazione Map sull’applicazione da _internal:profileId a un claim ordinario come profile_id e configurarne l’emissione.

Al prossimo accesso a un’applicazione, FoxIDs ripristina _session:profileId per lo stesso utente autenticato. La trasformazione del metodo crea un nuovo _internal:profileId per quel flusso. Lo stesso approccio vale quando FoxIDs converte claim tra JWT e SAML.

Inoltro, mapping di protocollo e API esterne

I claim interni e di sessione non richiedono una voce in Forward claims; i limiti generali di lunghezza rimangono applicabili. I nomi riservati non cambiano con il mapping di protocollo JWT/SAML, incluso quello automatico. Usare una trasformazione di claim Map per copiare valori tra prefissi; i mapping di protocollo non possono creare tipi di claim riservati.

Nessuno dei tre namespace riservati viene emesso nei token o nelle assertion, neppure con * in Issue claims. Sono inoltre esclusi dalle richieste e dalle risposte dell’API di claim esterna. Mappare il valore selezionato su un claim ordinario prima di inviarlo a un’API e, se necessario, un claim ordinario della risposta su un claim riservato in seguito.

I prefissi distinguono maiuscole e minuscole e sono riservati da FoxIDs. I claim riservati ricevuti da un protocollo o da un’API di integrazione vengono rimossi prima delle trasformazioni. Quelli salvati su utenti esistenti vengono ignorati; le attività non possono salvarli su utenti interni o esterni. Se un’attività avvia un altro metodo di autenticazione, la raccolta corrente di claim non viene trasferita al nuovo flusso di accesso.

Claim di sessione

Usare i claim _session: per conservare piccole quantità di stato per lo stesso utente autenticato tra accessi dal browser a diverse applicazioni. Le sessioni devono essere abilitate sul metodo di autenticazione; sono abilitate per impostazione predefinita. FoxIDs supporta i claim di sessione per Login, External Login, OpenID Connect, SAML 2.0, WS-Federation ed Environment Link.

FoxIDs rende disponibili i claim di sessione salvati prima delle trasformazioni di primo livello. Rimangono disponibili durante le trasformazioni intermedie, Extended UI e il secondo livello. Quando queste trasformazioni terminano correttamente, FoxIDs salva i claim di sessione risultanti. Rimuovere un claim di sessione in una trasformazione ne elimina anche il valore salvato. Per usare un valore di sessione salvato nelle trasformazioni dell’applicazione, copiarlo in un claim interno prima del completamento del metodo di autenticazione.

I claim di sessione appartengono all’utente autenticato originariamente, indipendentemente dalle modifiche a sub apportate dalle trasformazioni. Vengono ripristinati soltanto con un subject autenticato corrispondente e una sessione valida e attiva sullo stesso metodo. Un metodo che accetta più issuer deve ricevere subject univoci tra tutti questi issuer. Un’attività che avvia l’autenticazione non trasferisce i claim di sessione a un altro metodo; i flussi che gestiscono solo token non leggono né salvano claim della sessione del browser.

Login ed External Login possono riutilizzare la sessione del browser. I metodi basati su protocolli esterni continuano ad autenticare presso il provider di identità esterno a ogni accesso a un’applicazione; FoxIDs ripristina i claim di sessione dopo aver verificato l’identità restituita. I claim seguono la durata della sessione del metodo e non sono disponibili dopo il logout o la revoca della sessione.

Quando un nuovo accesso verifica lo stesso utente mentre la sessione precedente è ancora valida, FoxIDs conserva i valori salvati di quella sessione durante le trasformazioni dei claim ed Extended UI, finché le trasformazioni di secondo livello non terminano correttamente e li sostituiscono. Un nuovo accesso completato riavvia la durata assoluta della sessione del metodo di autenticazione; il riutilizzo di una sessione Login o External Login segue le durate scorrevole e assoluta configurate.

Login ed External Login conservano i claim originali nella sessione del browser prima di eseguire le trasformazioni dei claim. Dopo il corretto completamento delle trasformazioni di secondo livello, FoxIDs aggiorna i claim di sessione dell’utente autenticato, anche dopo Extended UI. Questo aggiornamento conserva i claim ordinari e la scadenza della sessione. Ogni metodo di autenticazione mantiene nel browser un utente corrente e un insieme di claim di sessione. Un nuovo accesso segue il normale comportamento delle sessioni del metodo di autenticazione; il browser usa l’ultimo cookie di sessione ricevuto.

I claim di sessione hanno questi limiti di archiviazione:

Limite	Valore
Nome del claim	100 caratteri, incluso _session:, con un nome di claim JWT valido e un nome dopo il prefisso che non sia vuoto né composto solo da spazi
Valore singolo	1.000 caratteri
Numero di claim	10 coppie nome/valore; ogni valore di un claim multivalore viene contato separatamente
Lunghezza totale dei valori	2.000 caratteri

I claim con nomi non validi o valori vuoti o composti soltanto da spazi vengono omessi. I valori più lunghi vengono troncati. I claim vengono considerati in ordine; il salvataggio si interrompe se il successivo claim valido supererebbe il limite numerico o la lunghezza totale. La convalida generale dei claim durante l’autenticazione rimane applicabile.

Ad esempio, una trasformazione del metodo di autenticazione può conservare un riferimento a un target di impersonificazione autorizzato in _session:impersonation_target_id. Gli accessi successivi alle applicazioni tramite quel metodo possono usare il riferimento per caricare il target e verificare nuovamente i permessi. Vedere Impersonificazione per l’esempio completo.

Claim esterni - API

Puoi chiamare la tua API da FoxIDs con una trasformazione dei claim. L'API viene chiamata con dei claim e i claim restituiti dall'API possono essere aggiunti con un'azione add o replace. L'API viene chiamata solo se esiste almeno un claim selezionato. Puoi usare * per selezionare e inviare tutti i claim alla tua API.

I claim riservati _local:, _internal:, _session: e _impersonate: sono esclusi dalle richieste e risposte API. Per scambiare un valore riservato selezionato, mapparlo su un claim ordinario prima della chiamata oppure mappare in seguito un claim ordinario della risposta su uno riservato.

I claim protetti, come sid e auth_time, vengono scartati dalle risposte API. Gli altri claim della risposta vengono elaborati in base all'azione configurata.

Scenari d'uso:

• Chiamare la tua API da un metodo di autenticazione ogni volta che un utente viene autenticato in FoxIDs o con un identity provider esterno. Puoi quindi trovare l'utente nel tuo database e restituire un user ID e magari un customer ID o qualunque altra informazione rilevante. Ad esempio, puoi anche creare l'utente nel tuo database.
• Chiamare la tua API da una registrazione applicativa con lo user ID (sub) e interrogare i ruoli dell'utente nel tuo database. La tua API restituirebbe allora un elenco vuoto oppure un elenco di role claim o magari una struttura di diritti piu complessa.

Caricare i claims della risposta API in claims locali

Impostare il Target facoltativo di External claims API per usare i claims della risposta in verifiche o trasformazioni successive. Con Target impostato su target, un claim denominato sub nella risposta API diventa _local:target:sub e role diventa _local:target:role. L'API restituisce nomi di claims ordinari; FoxIDs aggiunge il prefisso locale dopo aver filtrato e convalidato la risposta. Il nome completo del claim locale deve rispettare il limite di 100 caratteri. Lasciare Target vuoto per aggiungere o sostituire i claims della risposta direttamente nella raccolta di claims corrente.

Più chiamate API e ricerche di utenti interni possono popolare lo stesso target. Add claim aggiunge i valori restituiti. Replace claim sostituisce i tipi di claim restituiti sotto quel target e conserva gli altri. Una risposta vuota lascia invariati i claims già presenti nel target.

I claims locali del target sono disponibili nell'insieme di trasformazioni corrente. Mappare un valore come _local:target:sub su _internal:selected_user_id per usarlo negli insiemi successivi.

Implementare API

Devi implementare una semplice API che FoxIDs chiamera quando viene eseguita la trasformazione dei claim. Consulta il codice di esempio.

L'API ha un URL base e la funzionalita e suddivisa in cartelle. Attualmente e supportata solo la cartella claims (funzionalita) per richiedere un elenco di claim.

Se l'URL base dell'API e https://somewhere.org/myclaimsstore, l'URL della cartella claims sara https://somewhere.org/myclaimsstore/claims.

FoxIDs Cloud chiama la tua API dall'indirizzo IP 57.128.60.142. L'indirizzo IP di uscita puo cambiare e nel tempo potrebbero esserne aggiunti altri.

Richiesta

Protetta con HTTP Basic auth: username external_claims, password = secret configurato.

L'API viene chiamata con HTTP POST e un body JSON.

Questo e un body JSON di richiesta con due claim in input:

{
  "claims": [
    { "type": "sub", "value": "1b1ac05e-5937-4939-a49c-0e84a89662df" },
    { "type": "email", "value": "some@test.org" }
  ]
}

Risposta - Successo

In caso di successo, l'API dovrebbe restituire codice HTTP 200 e un elenco di claims (l'elenco puo essere vuoto).

FoxIDs ignora i claim il cui type o value è assente, è null, è vuoto o contiene solo caratteri di spaziatura. Quando il tracciamento dei messaggi di log è attivo, la traccia della risposta include i claim ricevuti prima che vengano filtrati. I messaggi di traccia lunghi vengono troncati.

Ad esempio, il sub dell'utente (user ID / username), customer ID e ruoli:

{
    "claims": [
        { "type": "sub", "value": "somewhere/external-some@test.org" },
        { "type": "customer_id", "value": "1234abcd" },
        { "type": "role", "value": "admin_access" },
        { "type": "role", "value": "read_access" },
        { "type": "role", "value": "write_access" }
    ]
}

Risposta - Errore

L'API deve restituire codice HTTP 401 (Unauthorized) e un error (obbligatorio) se il Basic auth viene rifiutato. Facoltativamente, aggiungi una descrizione dell'errore in ErrorMessage.

{
    "error": "invalid_api_id_secret",
    "ErrorMessage": "Invalid API ID or secret"
}

Se si verificano altri errori, l'API dovrebbe 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 nei log; non e mai mostrato all'utente finale).

I messaggi di errore restituiti dall'API in ErrorMessage NON vengono mostrati all'utente; vengono solo registrati nei log.

Esempio API

Il sample ExternalClaimsApiSample mostra come implementare l'API in ASP.NET Core.

Puoi usare questa Postman collection per chiamare e testare la tua API con Postman.

Configurare

Configura FoxIDs per chiamare la tua API da una trasformazione dei claim in FoxIDs Control Client.

1. Vai alla sezione Claim Transform
2. Fai clic su Add claim transform
3. Fai clic su External claims API
4. Seleziona Add claim o Replace claim
5. Aggiungi i claim selezionati, ad esempio sub, in Select claims
6. Aggiungi l'URL base dell'API senza la cartella claims in API URL
7. Aggiungi API secret
8. Imposta facoltativamente Target per caricare i claims della risposta in claims locali
9. Fai clic su Update

Esempi di trasformazione dei claim

Dividere il claim name nei due claim given_name e family_name

La trasformazione divide il valore del claim name al primo spazio trovato e aggiunge rispettivamente i claim given_name e family_name, se non esistono gia. Se nel valore del claim name c'e piu di uno spazio, non verranno aggiunti nuovi claim given_name e family_name perche esisteranno gia.

Usa due trasformazioni di claim Regex map.

• Trovare il valore del claim family_name con la regex ^\S+\s(?<map>\S+)$
• Trovare il valore del claim given_name con la regex ^(?<map>\S+)\s\S+$

Rimuovere da sub il nome del metodo di autenticazione aggiunto di default

Il nome del metodo di autenticazione viene aggiunto di default al valore del claim sub come prefisso separato da una pipe, ad esempio some-auth-method|my-external-user-id.

Puoi usare replace claim sul claim sub per rimuovere il valore prefisso aggiunto di default.

La trasformazione dividera il valore del claim sub e sostituira il claim con un nuovo sub che contiene solo l'ID originale.

Usa una trasformazione di claim Regex map e seleziona l'azione Replace claim.

Trovare l'ID senza il nome del metodo di autenticazione aggiunto di default con la regex ^([^|]+)\|(?<map>.+)$

Puoi fare lo stesso in un metodo di autenticazione SAML 2.0 usando il claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier (che contiene il valore NameID della SAML 2.0 Authn Response) invece del claim sub.

Confrontare email con _local:mfa:email e aggiungere amr

L’esempio viene eseguito in un metodo di autenticazione usato come elemento MFA. Confronta il claim email restituito dal metodo con _local:mfa:email dell’utente Login. Se i due valori e-mail sono uguali e corrispondono a un’espressione regolare, viene aggiunto il claim amr con il nome del metodo di autenticazione come valore (tale nome è configurato come valore di amr).

Il flusso MFA di Login usa il claim amr aggiunto per convalidare il completamento dell’elemento MFA. Il claim email restituito e gli altri claim del metodo di autenticazione non vengono uniti ai claim del metodo di autenticazione Login.

Usa una trasformazione di claim Concatenate seguita da una trasformazione di claim Regex match.

• Concatenate: Nuovo claim _local:compare_emails, azione Replace claim, concatenare i claim email e _local:mfa:email, formato di concatenazione {0}|{1}.
• Regex match: Nuovo claim amr, azione Replace claim, selezionare il claim _local:compare_emails, regex value match ^([^|]+)\|\1$, nuovo valore impostato al nome del metodo di autenticazione (ad esempio 9fk5z3vg).

Impersonificazione

Usare la trasformazione Impersonation su un metodo di autenticazione per emettere claim per un altro utente mantenendo l’utente autenticato originale come attore. Le sessioni devono essere abilitate sul metodo di autenticazione; sono abilitate per impostazione predefinita.

Caricare il target con Query internal user, un’API di claim esterna o entrambe, impostando Target su un nome come target. Verificare il permesso dell’utente autenticato e i claim richiesti del target prima di selezionarlo con una trasformazione Impersonation. Target è obbligatorio e vale target per impostazione predefinita nel Control Client. Un parametro di richiesta dell’applicazione seleziona un target; non concede il permesso di impersonificare.

Conservare un riferimento al target selezionato in un claim di sessione per ripetere la ricerca agli accessi successivi delle applicazioni. Il riferimento può essere un ID utente interno o un ID profilo esterno e non deve necessariamente corrispondere al sub emesso del target. L’esempio di utente interno qui sotto usa impersonation_target_id sia per il parametro di richiesta sia per il claim di sessione; sono nomi di esempio da adattare al proprio flusso.

Il target selezionato deve contenere esattamente un sub distinto e non vuoto. In caso contrario, la trasformazione prosegue senza selezionare quel target. La ricerca di un utente interno disabilitato non restituisce claim. Usare un’attività di errore condizionale se la propria policy richiede di rifiutare l’accesso quando non è possibile selezionare un target.

La trasformazione prepara claim _impersonate: per il completamento dopo la riuscita delle trasformazioni di secondo livello. Ad esempio, _local:target:sub diventa _impersonate:sub e _local:target:_local:internal_user_id diventa _impersonate:_local:internal_user_id. È anche possibile prepararli con trasformazioni ordinarie. Restano disponibili tra gli insiemi di trasformazioni del metodo di autenticazione e attraverso Extended UI.

Al completamento, FoxIDs sostituisce i claim di identità ordinari dell’utente con quelli del target selezionato, mantiene il contesto di autenticazione verificato e aggiunge un claim act il cui sub identifica l’utente autenticato originale. Il subject dell’attore è il sub FoxIDs dell’utente prima che l’impersonificazione ne sostituisca i claim. Le trasformazioni dell’applicazione ricevono questa identità effettiva. I claim ausiliari riservati non vengono emessi alle applicazioni.

Account target interni

Quando è presente _impersonate:_local:internal_user_id, FoxIDs verifica che l’utente interno esista e sia abilitato, inclusa la policy Access Structure applicabile, e associa l’account target alla sessione e ai grant insieme all’account originale. Se l’utente target interno non è valido, non esiste o è disabilitato, non viene eseguita alcuna impersonificazione.

Disabilitare o eliminare uno dei due account associati revoca la sessione attiva e i grant dei token di aggiornamento. La revoca dell’accesso Access Structure e le verifiche delle appartenenze a tempo si applicano anche al target associato. Per un target fornito solo da un’API senza associazione a un account interno, l’API e le trasformazioni configurate ne determinano la disponibilità a ogni accesso.

Esempio: impersonificare un utente interno

Questo esempio consente a un dipendente con il valore allow_impersonation nel claim role di selezionare un utente interno e continuare a impersonificarlo negli accessi successivi alle applicazioni. Un accesso senza target selezionato prosegue come utente originale.

Il diagramma segue le otto trasformazioni configurate di seguito. Il riferimento al target viene conservato tra gli accessi; i claim del target e i permessi del dipendente vengono verificati nuovamente a ogni accesso.

Configurare impersonation_target_id in Allowed request parameters su ogni registrazione di applicazione che lo invia. L’applicazione fornisce un ID utente interno come valore del parametro, che FoxIDs rende disponibile come _local:params:impersonation_target_id. Vedere Parametri di richiesta delle applicazioni. Assicurarsi che i claim del dipendente contengano role=allow_impersonation.

Aggiungere le otto voci seguenti, nell’ordine indicato, alle Second-level claim transforms del metodo di autenticazione Login.

1. Map: ripristinare il riferimento al target salvato. Usare Replace claim, impostare Select claim su _session:impersonation_target_id e New claim su _local:impersonation_target_id.

2. Map: applicare un target dall’applicazione. Usare Replace claim, impostare Select claim su _local:params:impersonation_target_id e New claim su _local:impersonation_target_id. Un parametro fornito sostituisce la selezione salvata. Se manca, viene mantenuto il valore del passaggio 1.

3. Match claim and value: verificare il ruolo del dipendente. Usare Replace claim, impostare Select claim su role, Match value su allow_impersonation, New claim su _local:impersonation_check_passed e New value su true.

4. Match claim: consentire l’accesso senza target. Usare Replace claim, if not match, impostare Select claim su _local:impersonation_target_id, New claim su _local:impersonation_check_passed e New value su true.

Il claim di controllo locale indica che l’accesso può proseguire: il dipendente possiede il ruolo richiesto oppure non è stato selezionato alcun target. Il ruolo viene verificato prima che il target sostituisca i claim dell’utente originale.

5. Match claim and return error: rifiutare una selezione non autorizzata. Usare If not match e selezionare _local:impersonation_check_passed. Impostare Error su access_denied e Error message su You are not allowed to impersonate another user.

6. Query internal user: caricare il target. Usare Replace claim, impostare Lookup claim su _local:impersonation_target_id, Lookup claim on internal user su sub, Claims from internal user su * e Target su target. La ricerca confronta l’ID utente interno e carica i claim dell’utente, inclusi quelli Access Structure inoltrati e i claim ausiliari locali, sotto _local:target:. Ad esempio, fornisce _local:target:sub e _local:target:_local:internal_user_id.

7. Impersonation: selezionare il target caricato. Usare Replace claim e impostare Target su target.

8. Map: conservare il target per gli accessi successivi. Usare Replace claim, impostare Select claim su _local:target:_local:internal_user_id e New claim su _session:impersonation_target_id. Questo salva l’ID stabile dell’utente caricato come riferimento per l’accesso successivo.

Se la policy limita gli utenti che possono essere impersonificati, aggiungere le verifiche del target tra i passaggi 6 e 7. Ad esempio, verificare _local:target:role o il claim ausiliario Access Structure _local:target:_local:access_node.

Se la ricerca non fornisce un target, questi otto passaggi terminano senza impersonificazione e mantengono un eventuale riferimento al target già salvato. Aggiungere un’attività di errore condizionale dopo la ricerca se un target non disponibile deve causare il rifiuto dell’accesso, oppure rimuovere esplicitamente il claim di sessione per cancellare la selezione salvata.

Continuare e modificare l’impersonificazione

Ogni accesso a un’applicazione riesegue le trasformazioni del metodo di autenticazione. Nell’esempio precedente, leggono il riferimento da _session:impersonation_target_id quando manca _local:params:impersonation_target_id, caricano i claim aggiornati del target e ripetono le verifiche dei permessi prima di selezionare l’impersonificazione. Il riferimento salvato rimane legato all’utente autenticato originale e allo stesso metodo di autenticazione.

Per selezionare un altro target, fornire un nuovo riferimento nel parametro di richiesta e sostituire il claim di sessione salvato dopo che il nuovo target ha superato i controlli. Per terminare l’impersonificazione, cancellare il riferimento e completare le trasformazioni senza un target di impersonificazione valido.

Un completamento riuscito con lo stesso target mantiene il suo sid. Selezionare un altro target, iniziare un’impersonificazione o completare senza un target valido crea un nuovo sid e revoca la precedente sessione attiva e i grant dei token di aggiornamento.

UserInfo e l’utilizzo dei grant rifiutano una sessione attiva revocata. Le applicazioni e le API che convalidano i token localmente devono continuare ad applicare le proprie regole su sessioni e durata dei token. Il single logout SAML usa i valori registrati all’emissione per ogni applicazione.

Le sessioni attive e i grant dei token di aggiornamento mostrano il subject impersonificato e l’attore originale nel Control Client e nella Control API. Gli eventi di audit dell’accesso includono l’attore. Eventi di audit di impersonificazione separati registrano avvio, modifica e arresto, inclusi gli ID di sessione precedenti e attuali.

Documentazione correlata

• Claim
• Struttura di accesso
• Login e Home Realm Discovery
• Metodo di autenticazione OpenID Connect
• Metodo di autenticazione SAML 2.0