Emettere claim personalizzati con attributi di estensione in Microsoft Entra ID

Panoramica

Microsoft Entra ID consente di aggiungere attributi di estensione (directory extension attributes) a un’app e di esporli come claim nei token SSO. Questo metodo è utile quando dovete inviare identificatori o dati specializzati a un’app solo per utenti appartenenti a gruppi specifici. I claim possono essere inclusi nei token SAML o OIDC durante l’accesso.

Breve definizione: attributo di estensione — campo personalizzato registrato su un’app che può essere mappato come claim in un token.

Procedura raccomandata (passo per passo)

Passo 1: Registrare gli attributi di estensione

Usate Graph Explorer per registrare due attributi personalizzati nell’app target (ad esempio sponsorid1 e sponsorid2). Inviare una richiesta POST a:

POST https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties

Esempio di corpo della richiesta:

{
  "name": "sponsorid1",
  "dataType": "String",
  "targetObjects": ["User"]
}

Ripetere la procedura per sponsorid2. Dopo la registrazione il sistema restituirà i nomi completi degli attributi nel formato:

extension__sponsorid1
extension__sponsorid2

Annotate questi nomi esatti per l’uso successivo.

Passo 2: Assegnare gli attributi di estensione agli utenti

Sempre tramite Graph Explorer aggiornate (PATCH) gli oggetti utente per assegnare un valore agli attributi di estensione:

PATCH https://graph.microsoft.com/v1.0/users/{UserObjectId}

Esempio di corpo:

{
  "extension__sponsorid1": "ABC123"
}

Ripetete per ciascun utente, impostando il valore corrispondente per sponsorid1 o sponsorid2.

Passo 3: Creare i claim nell’Enterprise Application

Nel portale:

• Entra ID > Enterprise Applications > [Nome App] > Single Sign-On > Attributes & Claims
• Cliccare Aggiungi nuovo claim
• Dare un nome al claim (es. sponsorClaim1)
• Sotto Condizioni del claim, selezionare Member e scegliere il gruppo che deve ricevere il claim
• Come attributo sorgente usare il nome dell’attributo di estensione (es. extension__sponsorid1)

Ripetere per il secondo gruppo e il secondo attributo.

Passo 4: Risolvere l’errore di mappatura claim

Se compare l’errore “Application requires custom signing key to customize claims”, è possibile aggirarlo temporaneamente aggiornando il manifest della registrazione dell’app:

"acceptMappedClaims": true

Nota: questa impostazione permette la personalizzazione dei claim senza richiedere una chiave di firma personalizzata. Valutate i rischi e le policy aziendali prima dell’uso in produzione.

Passo 5: Testare la configurazione

Chiamare l’app con l’endpoint di autorizzazione e accedere con utenti che appartengono ai gruppi definiti:

https://login.microsoftonline.com/(Tenant ID)/oauth2/v2.0/authorize?client_id=(Client ID)&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

Dopo l’accesso, verificate il token su https://jwt.ms: dovreste vedere i claim personalizzati (sponsorid1 o sponsorid2) solo per gli utenti dei gruppi configurati. Gli utenti non nei gruppi non riceveranno il claim.

Esempi pratici e suggerimenti

• Usate valori sintetici (es. ABC123) durante i test; in produzione inserite solo identificatori autorizzati.
• Conservate la mappatura extension_ in un file di configurazione per manutenzione futura.

Importante

• Limitate l’uso di dati sensibili: inviate solo ciò che è strettamente necessario all’app.
• Quando abilitate “acceptMappedClaims”, documentate la decisione e rivalutatela prima della produzione.

Playbook operativo (SOP) per l’amministratore

1. Preparazione: identificare l’app e i gruppi destinatari.
2. Registrazione attributi: usare Graph Explorer come descritto al Passo 1.
3. Assegnazione valori: aggiornare gli utenti o popolare tramite script automatizzati.
4. Creazione claim: mappare attributi su Enterprise Application.
5. Test: eseguire accessi di prova e verificare token su jwt.ms.
6. Revisione sicurezza: verificare policy di accesso e conservazione dei dati.

Checklist per ruoli

Amministratore Entra ID:

• Registrare gli attributi
• Aggiornare manifest se necessario
• Creare claim e associare ai gruppi

Sviluppatore dell’app:

• Comunicare il formato del claim all’app
• Gestire l’assenza del claim (fallback) nell’app

Auditor / Sicurezza:

• Verificare che i claim siano emessi solo ai gruppi attesi
• Valutare impatto privacy

Casi di test e criteri di accettazione

Casi di test principali:

• Utente A in Gruppo 1 riceve sponsorid1 nel token
• Utente B in Gruppo 2 riceve sponsorid2 nel token
• Utente C non in Gruppo 1 o 2 non riceve claim sponsor

Criteri di accettazione:

• I token mostrano il claim corretto per utenti appartenenti ai gruppi specificati
• Nessun utente al di fuori dei gruppi riceve i claim

Risoluzione problemi comuni

Problema: il claim non appare nel token.

• Verificare che l’attributo di estensione sia registrato e che il nome usato nella mappatura sia esatto (extension…)
• Controllare che l’utente abbia il valore impostato sull’attributo
• Assicurarsi che l’utente appartenga al gruppo selezionato nella condizione del claim

Problema: errore “Application requires custom signing key to customize claims”

• Aggiornare temporaneamente il manifest con “acceptMappedClaims”: true
• Valutare soluzione a lungo termine: usare chiavi di firma personalizzate se richiesto dalle policy

Rollback rapido

• Rimuovere le mappature dei claim dall’Enterprise Application
• Ripristinare i valori degli attributi utente se necessari

Note su sicurezza e privacy (GDPR e buone pratiche)

• Minimizzo dei dati: non aggiungete dati personali non necessari come claim.
• Consenso e base giuridica: assicuratevi che l’invio di dati a terze parti sia conforme alle policy aziendali e al GDPR.
• Logging: limitare i log contenenti valori sensibili e proteggerli con controlli di accesso.

Compatibilità e limiti

• Questo approccio si applica a SAML e OIDC dove Entra ID è identity provider.
• Alcune app potrebbero richiedere la firma personalizzata dei token per accettare claim mappati; consultate la documentazione dell’app.

Glossario rapido

• Entra ID: servizio di identity e access management di Microsoft.
• Claim: affermazione (es. attributo) presente in un token di autenticazione.
• Attributo di estensione: campo personalizzato registrato su un’applicazione nel tenant.

Sommario finale

Seguendo i passaggi descritti potete emettere claim personalizzati in modo selettivo per gruppi specifici, migliorando il controllo su quali informazioni raggiungono le applicazioni. Testate ampiamente e documentate eventuali eccezioni legate alla sicurezza.