Configurare le attestazioni di gruppo per le applicazioni usando Microsoft Entra ID
Microsoft Entra ID può fornire informazioni sull'appartenenza al gruppo di un utente nei token da usare all'interno delle applicazioni. Questa funzionalità supporta tre modelli principali:
- Gruppi identificati dall'attributo OID (Microsoft Entra Object Identifier)
- Gruppi identificati dall'attributo
sAMAccountName
oGroupSID
per i gruppi e gli utenti sincronizzati con Active Directory - Gruppi identificati dall'attributo Display Name per i gruppi solo cloud
Importante
Il numero di gruppi generati in un token è limitato a 150 per le asserzioni SAML e 200 per JWT, inclusi i gruppi annidati. Nelle organizzazioni di grandi dimensioni, il numero di gruppi in cui un utente è membro potrebbe superare il limite applicato dall'ID Entra di Microsoft prima di emettere attestazioni di gruppo in un token. Superare questo limite farà sì che l'ID Microsoft Entra ometta completamente l'invio delle attestazioni di gruppo nel token. Per le soluzioni alternative a questi limiti, vedere Avvertenze importanti per questa funzionalità.
Avvertenze importanti per questa funzionalità
Il supporto per l'uso di
sAMAccountName
e degli attributi SID (Security Identifier) sincronizzati dall'ambiente locale è progettato per consentire lo spostamento delle applicazioni esistenti da Active Directory Federation Services (AD FS) e da altri provider di identità. I gruppi gestiti in Microsoft Entra ID non contengono gli attributi necessari per generare queste attestazioni.Per evitare il numero di gruppi limite se gli utenti hanno un numero elevato di appartenenze ai gruppi, è possibile limitare i gruppi generati nelle attestazioni ai gruppi pertinenti per l'applicazione. Ulteriori informazioni sui gruppi di emissione assegnati all'applicazione per i token JWT e i token SAML. Se non è possibile assegnare gruppi alle applicazioni, è anche possibile configurare un filtro di gruppo per ridurre il numero di gruppi generati nell'attestazione. Il filtro dei gruppi si applica ai token generati per le app in cui le attestazioni di gruppo e il filtro sono stati configurati nel pannello App aziendali nel portale. Tenere presente che nelle organizzazioni di grandi dimensioni, il numero di gruppi in cui un utente è membro potrebbe superare il limite applicato dall'ID Entra di Microsoft prima di emettere attestazioni di gruppi in un token. Se si supera questo limite, Microsoft Entra ID omette completamente di inviare attestazioni di gruppo nel token.
Le dichiarazioni di gruppo hanno un limite di cinque gruppi se il token viene emesso tramite il flusso implicito. I token richiesti tramite il flusso implicito avranno un'attestazione
"hasgroups":true
solo se l'utente si trova in più di cinque gruppi.È consigliabile basare l'autorizzazione in-app sui ruoli dell'applicazione anziché sui gruppi quando:
- Si sta sviluppando una nuova applicazione oppure è possibile configurare un'applicazione esistente.
- Non è necessario il supporto per i gruppi annidati.
L'uso dei ruoli applicazione limita la quantità di informazioni che devono essere inserite nel token, è più sicuro e separa l'assegnazione dell'utente dalla configurazione dell'app.
Raggruppare le attestazioni per le applicazioni che eseguono la migrazione da AD FS e da altri provider di identità
Molte applicazioni configurate per l'autenticazione con AD FS si basano sulle informazioni sull'appartenenza al gruppo sotto forma di attributi del gruppo di Active Directory di Windows Server. Questi attributi sono il gruppo sAMAccountName
, che potrebbe essere qualificato dal nome di dominio o dall'identificatore di sicurezza del gruppo di Windows (GroupSID
). Quando l'applicazione è federata con AD FS, AD FS usa la TokenGroups
funzione per recuperare le appartenenze ai gruppi per l'utente.
Un'app spostata da AD FS richiede attestazioni nello stesso formato. Le attestazioni di gruppo e ruolo generate dall'ID Microsoft Entra possono contenere l'attributo qualificato dal dominio sAMAccountName
o l'attributo GroupSID
sincronizzato da Active Directory, anziché l'attributo Microsoft Entra ID objectID
del gruppo.
I formati supportati per le attestazioni di gruppo sono:
- Microsoft Entra group ObjectId: disponibile per tutti i gruppi.
- sAMAccountName: disponibile per i gruppi sincronizzati da Active Directory.
- NetbiosDomain\sAMAccountName: disponibile per i gruppi sincronizzati da Active Directory.
- DNSDomainName\sAMAccountName: disponibile per i gruppi sincronizzati da Active Directory.
- Identificatore di sicurezza del gruppo locale: disponibile per i gruppi sincronizzati da Active Directory.
Nota
sAMAccountName
e gli attributi locali GroupSID
sono disponibili solo sugli oggetti gruppo sincronizzati da Active Directory. Non sono disponibili nei gruppi creati in Microsoft Entra ID o Office 365. Le applicazioni configurate in Microsoft Entra ID per ottenere gli attributi del gruppo locale sincronizzati li ottengono solo per i gruppi sincronizzati.
Opzioni per le applicazioni per l'utilizzo delle informazioni sui gruppi
Le applicazioni possono chiamare l'endpoint del gruppo Microsoft Graph per ottenere informazioni sul gruppo per l'utente autenticato. Questa chiamata garantisce che tutti i gruppi in cui un utente sia membro siano disponibili, anche quando è coinvolto un numero elevato di gruppi. L'enumerazione del gruppo è quindi indipendente dalle limitazioni per le dimensioni del token.
Tuttavia, se un'applicazione esistente prevede di utilizzare informazioni sui gruppi tramite attestazioni, è possibile configurare l'ID Microsoft Entra con diversi formati di attestazione. Valutare le opzioni seguenti:
Quando si usa l'appartenenza al gruppo per l'autorizzazione all'interno dell'applicazione, è preferibile usare l'attributo di gruppo
ObjectID
. L'attributo di gruppoObjectID
non è modificabile e univoco in Microsoft Entra ID. È disponibile per tutti i gruppi.Se si usa l'attributo del gruppo
sAMAccountName
locale per l'autorizzazione, usare nomi qualificati di dominio. Riduce la probabilità che i nomi si scontrano.sAMAccountName
potrebbe essere univoco all'interno di un dominio di Active Directory, ma se più domini di Active Directory sono sincronizzati con un tenant di Microsoft Entra, è possibile che più di un gruppo abbia lo stesso nome.Prova a usare i ruoli dell'applicazione per fornire un livello di indirezione tra l'appartenenza al gruppo e l'applicazione. L'applicazione prende quindi decisioni di autorizzazione interne in base alle attestazioni di ruolo nel token.
Se l'applicazione è configurata per ottenere gli attributi di gruppo sincronizzati da Active Directory e un gruppo non contiene tali attributi, non verrà incluso nelle attestazioni.
Le attestazioni di gruppo nei token includono gruppi annidati, tranne quando si usa l'opzione per limitare le attestazioni di gruppo ai gruppi assegnati all'applicazione.
Se un utente è membro di GroupB e GroupB è membro di GroupA, le attestazioni di gruppo per l'utente conterranno sia GroupA che GroupB. Quando gli utenti di un'organizzazione hanno un numero elevato di appartenenze ai gruppi, il numero di gruppi elencati nel token può aumentare le dimensioni del token. Microsoft Entra ID limita il numero di gruppi che verrà generato in un token a 150 per le asserzioni SAML e 200 per JWT. Se un utente è membro di un numero maggiore di gruppi, i gruppi vengono omessi. Viene invece incluso un collegamento all'endpoint di Microsoft Graph per ottenere informazioni sul gruppo.
Prerequisiti per l'uso degli attributi di gruppo sincronizzati da Active Directory
Le attestazioni di appartenenza al gruppo possono essere emesse nei token per qualsiasi gruppo se si usa il formato ObjectId
. Per utilizzare attestazioni di gruppo in formati diversi da ObjectId
, i gruppi devono essere sincronizzati da Active Directory tramite Microsoft Entra Connect.
Per configurare Microsoft Entra ID per generare nomi di gruppo per i gruppi di Active Directory:
Sincronizzare i nomi dei gruppi da Active Directory
Prima che Microsoft Entra ID possa generare i nomi dei gruppi o il SID del gruppo locale in attestazioni di gruppo o ruolo, è necessario sincronizzare gli attributi necessari da Active Directory. È necessario eseguire Microsoft Entra Connect versione 1.2.70 o successiva. Le versioni precedenti di Microsoft Entra Connect di 1.2.70 sincronizzano gli oggetti gruppo da Active Directory, ma non includono gli attributi del nome del gruppo necessari.
Configurare la registrazione dell'applicazione in Microsoft Entra ID per includere le attestazioni di gruppo nei token
È possibile configurare le attestazioni di gruppo nella sezione Applicazioni aziendali del portale o usando il manifesto dell'applicazione nella sezione Registrazioni dell'applicazione. Per configurare le attestazioni di gruppo nel manifesto dell'applicazione, vedere Configurare la registrazione dell'applicazione Microsoft Entra per gli attributi del gruppo più avanti in questo articolo.
Aggiungere attestazioni di gruppo ai token per le applicazioni SAML usando la configurazione SSO
Per configurare le attestazioni di gruppo per un'applicazione SAML di galleria o non-galleria tramite accesso singolo (SSO):
Aprire Applicazioni aziendali, selezionare l'applicazione nell'elenco, selezionare Configurazione Single Sign-On e quindi selezionare Attributi utente e attestazioni.
Selezionare Aggiungi un'attestazione di gruppo.
Usare le opzioni per selezionare i gruppi da includere nel token.
Selezione Descrizione Tutti i gruppi Emette gruppi di sicurezza, liste di distribuzione e ruoli. Gruppi di sicurezza Emette i gruppi di sicurezza di cui l'utente è membro nella dichiarazione dei gruppi. Se all'utente vengono assegnati ruoli della directory, questi vengono emessi come ID oggetto. Ruoli della directory Se all'utente vengono assegnati ruoli della directory, vengono emessi come reclamo wids
. La rivendicazione del gruppo non verrà emessa.Gruppi assegnati all'applicazione Genera solo i gruppi assegnati in modo esplicito all'applicazione e che l'utente è membro di . Consigliato per le organizzazioni di grandi dimensioni a causa del limite di numeri di gruppo nel token. Ad esempio, per generare tutti i gruppi di sicurezza di cui l'utente è membro, selezionare Gruppi di sicurezza.
Per emettere gruppi utilizzando gli attributi di Active Directory sincronizzati anziché quelli di
objectID
Microsoft Entra ID, selezionare il formato richiesto dall'elenco a discesa Attributo di origine. Nelle attestazioni verranno inclusi solo i gruppi sincronizzati da Active Directory.Per generare solo i gruppi assegnati all'applicazione, selezionare Gruppi assegnati all'applicazione.
I gruppi assegnati all'applicazione verranno inclusi nel token. Altri gruppi di cui l'utente è membro verranno omessi. Con questa opzione, i gruppi annidati non sono inclusi e l'utente deve essere un membro diretto del gruppo assegnato all'applicazione.
Per modificare i gruppi assegnati all'applicazione, selezionare l'applicazione dall'elenco Applicazioni aziendali. Quindi selezionare Utenti e Gruppi dal menu a sinistra dell'applicazione.
Per altre informazioni sulla gestione dell'assegnazione di gruppi alle applicazioni, vedere Assegnare un utente o un gruppo a un'app aziendale.
Emettere il nome visualizzato del gruppo cloud-only nel token
È possibile configurare l'attestazione di gruppo in modo da includere il nome visualizzato del gruppo per i gruppi solo cloud.
Aprire Applicazioni aziendali, selezionare l'applicazione nell'elenco, selezionare Configurazione Single Sign-On e quindi selezionare Attributi utente e attestazioni.
Se sono già state configurate attestazioni di gruppo, selezionarla nella sezione Attestazioni aggiuntive . In caso contrario, è possibile aggiungere l'attestazione di gruppo come descritto nei passaggi precedenti.
Per il tipo di gruppo generato nel token selezionare Gruppi assegnati all'applicazione:
Per emettere il nome visualizzato del gruppo solo per gruppi cloud, nel menu a discesa Attributo di origine seleziona nomi visualizzati dei gruppi solo cloud:
Per una configurazione ibrida, per generare l'attributo del gruppo locale per i gruppi sincronizzati e il nome visualizzato per i gruppi cloud, è possibile selezionare l'attributo di origini locali desiderato e selezionare la casella di controllo Emit group name for cloud-only groups (Genera nome gruppo per i gruppi solo cloud):
Nota
È possibile aggiungere solo i nomi dei gruppi cloud assegnati a un'applicazione. La restrizione a groups assigned to the application
è dovuta al fatto che un nome di gruppo non è univoco e i nomi visualizzati possono essere emessi solo per i gruppi assegnati esplicitamente all'applicazione per ridurre i rischi per la sicurezza. In caso contrario, qualsiasi utente potrebbe creare un gruppo con nome duplicato e ottenere l'accesso sul lato applicazione.
Impostare le opzioni avanzate
Personalizzare il nome della dichiarazione di gruppo
È possibile modificare la modalità di emissione delle attestazioni di gruppo usando le impostazioni in Opzioni avanzate.
Se si seleziona Personalizza il nome dell'attestazione di gruppo, è possibile specificare un tipo di attestazione diverso per le attestazioni di gruppo. Immettere il tipo di reclamo nella casella Nome e nella casella opzionale Spazio dei nomi per il reclamo.
Alcune applicazioni richiedono che le informazioni sull'appartenenza al gruppo vengano visualizzate nell'attestazione del ruolo. Facoltativamente, è possibile emettere i gruppi dell'utente come ruoli selezionando la casella di controllo Emetti gruppi come attestazioni di ruolo.
Nota
Se si usa l'opzione per emettere dati di gruppo come ruoli, solo i gruppi verranno visualizzati nella dichiarazione di ruolo. Tutti i ruoli delle applicazioni assegnati all'utente non verranno visualizzati nella dichiarazione del ruolo.
Filtro dei gruppi
Il filtro dei gruppi permette un controllo preciso dell'elenco dei gruppi inclusi come parte dell'attestazione di gruppo. Quando viene configurato un filtro, solo i gruppi che corrispondono al filtro verranno inclusi nell'attestazione del gruppo inviata a tale applicazione. Il filtro verrà applicato a tutti i gruppi indipendentemente dalla gerarchia di gruppi.
Nota
Il filtro dei gruppi si applica ai token generati per le app in cui le attestazioni di gruppo e il filtro sono stati configurati nel pannello App aziendali nel portale.
Il filtro dei gruppi non si applica ai ruoli di Microsoft Entra.
È possibile configurare i filtri da applicare al nome visualizzato o SAMAccountName
all'attributo del gruppo. Sono supportate le operazioni di filtro seguenti:
- Prefisso: corrisponde all'inizio dell'attributo selezionato.
- Suffisso: corrisponde alla fine dell'attributo selezionato.
- Contiene: corrisponde a qualsiasi posizione nell'attributo selezionato.
Trasformazione Gruppo
Alcune applicazioni potrebbero richiedere i gruppi in un formato diverso da quello in cui sono rappresentati in Microsoft Entra ID. Per supportare questo requisito, è possibile applicare una trasformazione a ogni gruppo che verrà generato nella rivendicazione di gruppo. A tale scopo, è possibile configurare un'espressione regolare (regex) e un valore di sostituzione per le attestazioni di gruppo personalizzate.
\
-
Modello regex: utilizza un'espressione regolare per analizzare le stringhe di testo secondo il modello impostato in questa casella. Se il modello regex descritto restituisce
true
, verrà eseguito il modello di sostituzione regex. -
Modello di sostituzione regex: struttura nella notazione regex come si vuole sostituire la stringa se il modello regex descritto restituisce
true
. Usare i gruppi di acquisizione per trovare le corrispondenze di sottoespressioni in questa espressione regolare sostitutiva.
Per altre informazioni sui gruppi regex replace e capture, vedere The Regular Expression Object Model: The Captured Group.For more information about regex replace and capture groups, see The Regular Expression Object Model: The Captured Group.
Nota
Come descritto nella documentazione di Microsoft Entra, non è possibile modificare un'attestazione con restrizioni usando una policy. L'origine dati non può essere modificata e non viene applicata alcuna trasformazione quando si generano queste attestazioni. L'attestazione di gruppo è ancora un'attestazione con restrizioni, quindi è necessario personalizzare i gruppi modificando il nome. Se si seleziona un nome con restrizioni per il nome dell'attestazione del gruppo personalizzato, l'attestazione verrà ignorata in fase di esecuzione.
È anche possibile usare la funzionalità di trasformazione regex come filtro, perché tutti i gruppi che non corrispondono al modello regex non verranno generati nell'attestazione risultante.
Se la trasformazione applicata all'attestazione dei gruppi originali genera una nuova attestazione personalizzata, l'attestazione dei gruppi originali verrà omessa dal token. Tuttavia, se l'espressione regolare configurata non corrisponde a un valore presente nell'elenco originale, l'attestazione personalizzata non sarà presente e l'attestazione dei gruppi originali sarà inclusa nel token.
Modificare la configurazione della dichiarazione di gruppo
Dopo aver aggiunto una configurazione dell'attestazione di gruppo alla configurazione Attributi utente e attestazioni , l'opzione per aggiungere un'attestazione di gruppo non sarà disponibile. Per modificare la configurazione dell'attestazione di gruppo, selezionare l'attestazione di gruppo nell'elenco Attestazioni aggiuntive .
Configurare la registrazione dell'applicazione Microsoft Entra per gli attributi del gruppo
È anche possibile configurare attestazioni di gruppo nella sezione attestazioni facoltative del manifesto dell'applicazione.
Nel portale, seleziona Identità>Applicazioni>Registrazioni app>Seleziona Applicazione>Manifest.
Abilitare le attestazioni di appartenenza al gruppo modificando
groupMembershipClaims
.I valori validi sono:
Selezione Descrizione All
Genera gruppi di sicurezza, liste di distribuzione e ruoli. SecurityGroup
Genera gruppi di sicurezza e ruoli di Microsoft Entra di cui l'utente è membro nell'attestazione di gruppo. DirectoryRole
Se all'utente vengono assegnati ruoli della directory, vengono emessi come wids
claim. Una richiesta di gruppo non verrà emessa.ApplicationGroup
Genera solo i gruppi assegnati in modo esplicito all'applicazione e che l'utente è membro di . None
Non vengono restituiti gruppi. (Non fa distinzione tra maiuscole e minuscole, quindi none
funziona anche. Può essere impostato direttamente nel manifesto dell'applicazione.Ad esempio:
"groupMembershipClaims": "SecurityGroup"
Per impostazione predefinita, gli attributi del gruppo
ObjectID
verranno inclusi nel valore della dichiarazione di gruppo. Per modificare il valore dell'attestazione in modo che contenga attributi del gruppo locale o per modificare il tipo di attestazione in un ruolo, usare laoptionalClaims
configurazione descritta nel passaggio successivo.Impostare dichiarazioni facoltative per la configurazione del nome del gruppo.
Se si desidera che i gruppi nel token contengano gli attributi del gruppo Active Directory locale, specificare quale attestazione facoltativa di tipo token deve essere applicata nella
optionalClaims
sezione . È possibile elencare più tipi di token:-
idToken
per il token ID OIDC -
accessToken
per il token di accesso OAuth/OIDC -
Saml2Token
per i token SAML
Nota
Il
Saml2Token
tipo si applica ai token in formato SAML1.1 e SAML2.0.Per ogni tipo di token pertinente, modificare l'attestazione di gruppo per usare la sezione
optionalClaims
nel manifesto. LooptionalClaims
schema è il seguente:{ "name": "groups", "source": null, "essential": false, "additionalProperties": [] }
Schema delle dichiarazioni facoltative Valore name
Deve essere "groups"
.source
Non utilizzato. Omettere o specificare null
.essential
Non utilizzato. Omettere o specificare false
.additionalProperties
Elenco di proprietà aggiuntive. Le opzioni valide sono "sam_account_name"
,"dns_domain_and_sam_account_name"
,"netbios_domain_and_sam_account_name"
"cloud_displayname"
, e"emit_as_roles"
.In
additionalProperties
è necessario solo uno di"sam_account_name"
,"dns_domain_and_sam_account_name"
o"netbios_domain_and_sam_account_name"
. Se sono presenti più di uno, viene usato il primo e tutti gli altri vengono ignorati.Per alcune applicazioni sono necessarie informazioni sul gruppo relative all'utente nell'attestazione del ruolo. Per modificare il tipo di attestazione da un'attestazione di gruppo a un'attestazione di ruolo, aggiungere
"emit_as_roles"
ad altre proprietà. I valori del gruppo verranno emessi nell'attestazione del ruolo.Per generare il nome visualizzato del gruppo per i gruppi solo cloud, è possibile aggiungere
"cloud_displayname"
aadditional properties
. Questa opzione funzionerà solo quando“groupMembershipClaims”
è impostato suApplicationGroup
Nota
Se si usa
"emit_as_roles"
, tutti i ruoli dell'applicazione configurati a cui viene assegnato l'utente non verranno visualizzati nell'attestazione del ruolo.-
Esempi
Emettere gruppi come nomi dei gruppi nei token di accesso OAuth in formato DNSDomainName\sAMAccountName
.
"optionalClaims": {
"accessToken": [{
"name": "groups",
"additionalProperties": ["dns_domain_and_sam_account_name"]
}]
}
Emettere i nomi dei gruppi da restituire nel formato NetbiosDomain\sAMAccountName
come attestazione di ruolo nei token di identificazione SAML e OIDC.
"optionalClaims": {
"saml2Token": [{
"name": "groups",
"additionalProperties": ["netbios_domain_and_sam_account_name", "emit_as_roles"]
}],
"idToken": [{
"name": "groups",
"additionalProperties": ["netbios_domain_and_sam_account_name", "emit_as_roles"]
}]
}