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.

Se crei un nuovo claim con una trasformazione o attivita di claim di primo livello, il claim e locale al metodo di autenticazione, tranne che in un metodo di autenticazione Login.
In un metodo di autenticazione, il claim viene inoltrato se il tipo di claim viene aggiunto alla lista Forward claims, oppure se * (predefinito) e incluso nella lista.

Se crei un nuovo claim con una trasformazione o attivita di claim, il claim e locale alla registrazione applicativa.
In una registrazione applicativa, devi aggiungere il claim o * alla lista Issue claims. In alternativa, per OpenID Connect, aggiungi il claim alla lista Voluntary claims di uno scope e richiedi lo scope dalla tua applicazione.

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 aggiunti in AddLocalClaims:

• _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)

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 trasformazione di claim che supportano tutte le azioni:

• Match claim - eseguire l'azione se il tipo di claim corrisponde
• Match claim and value - eseguire l'azione se il tipo di claim e il valore del claim corrispondono
• Regex match - eseguire l'azione se il tipo di claim corrisponde e il valore del claim corrisponde all'espressione regolare

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

• Map - eseguire l'azione se il tipo di claim corrisponde, quindi mappare il valore del claim in un nuovo claim
• Regex map - eseguire l'azione se il tipo di claim corrisponde e il valore del claim corrisponde al gruppo dell'espressione regolare, quindi mappare il valore del gruppo in un nuovo claim

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

• Constant - eseguire sempre l'azione (aggiungere/sostituire un claim con un valore costante)
• Concatenate - eseguire l'azione se uno o piu tipi di claim corrispondono, quindi concatenare i valori dei claim in un nuovo claim
• External claims API - chiamare una API esterna con i claim selezionati per aggiungere/sostituire claim con claim esterni
• DK XML privilege to JSON - convertire il DK privilege in JSON

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

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

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.
• 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.

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).

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.

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.

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).

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. 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 confronta email dell'utente attualmente autenticato con _local:mfa:email dell'utente MFA gia autenticato. Se i due valori email sono uguali e corrispondono a un'espressione regolare, viene aggiunto il claim amr con il nome del metodo di autenticazione come valore (il nome del metodo di autenticazione e configurato come valore amr).

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).

Documentazione correlata

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