Mapping con l'attributo certificateUserIds in Microsoft Entra ID

Gli oggetti utente in Microsoft Entra ID hanno un attributo denominato certificateUserIds.

• L'attributo certificateUserIds è multivalore e può contenere fino a 10 valori.
• Ogni valore non può contenere più di 1024 caratteri.
• Ogni valore deve essere univoco. Quando un valore è presente in un account utente, non può essere scritto in nessun altro account utente nello stesso tenant di Microsoft Entra.
• Il valore non deve essere in formato ID di posta elettronica. L'attributo certificateUserIds può archiviare nomi dell'entità utente (UPN) non indirizzabili, ad esempio bob@woodgrove o bob@local.

Modelli supportati per gli ID utente del certificato

I valori archiviati in certificateUserIds devono essere nel formato descritto nella tabella seguente. I prefissi X509:<Mapping> fanno distinzione tra maiuscole e minuscole.

Ruoli per aggiornare certificateUserIds

Gli utenti solo cloud devono avere almeno il ruolo di Amministratore Privilegiato dell'Autenticazione per aggiornare certificateUserIds. Gli utenti solo cloud possono usare l'interfaccia di amministrazione di Microsoft Entra o Microsoft Graph per aggiornare certificateUserIds.

Gli utenti sincronizzati devono avere almeno il ruolo di amministratore identità ibrida per aggiornare certificateUserIds. Solo Microsoft Entra Connect può essere usato per aggiornare certificateUserIds sincronizzando il valore da locale.

Come trovare i valori di CertificateUserIds corretti per un utente dal certificato utente finale usando il modulo PowerShell

Certificate UserIds segue un determinato modello per i relativi valori in base alle configurazioni di associazione UserName nel tenant. Il comando di PowerShell seguente consente a un amministratore di recuperare i valori esatti per l'attributo Certificate UserIds per un utente da un certificato utente finale. L'amministratore può anche ottenere i valori correnti nell'attributo Certificate UserIds per un utente per un'associazione nome utente specificata e impostare il valore dell'attributo Certificate UserIds.

Per altre informazioni, vedere Installazione di Microsoft Entra PowerShell e Microsoft Graph PowerShell.

1. Avvia PowerShell.

2. Installare e importare Microsoft Graph PowerShell SDK.

   Install-Module Microsoft.Graph -Scope CurrentUser
   Import-Module Microsoft.Graph.Authentication
   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

3. Installare il modulo Microsoft Entra PowerShell (la versione minima richiesta è 1.0.6)

       Install-Module -Name Microsoft.Entra
   

Altre informazioni sul modulo CertificateBasedAuthentication sono disponibili qui

Get-EntraUserCBAAuthorizationInfo

Get-EntraUserCBAAuthorizationInfo consente di recuperare le informazioni di autorizzazione per un utente di Microsoft Entra ID, inclusi gli identificatori di autenticazione basati su certificati.

Sintassi: Get-EntraUserCBAAuthorizationInfo [-UserId] <String>[-Raw][<CommonParameters>]

Esempio 1: Ottenere informazioni di autorizzazione per un utente in base al Nome Principale Utente

Connect-Entra -Scopes 'User.Read.All' 
Get-EntraUserCBAAuthorizationInfo -UserId ‘[email protected]'

Risposta:

Questo comando recupera le informazioni di autorizzazione per l'utente con il nome principale utente (User Principal Name, UPN) specificato.

Esempio 2: Recuperare le informazioni di autorizzazione per un utente

Connect-Entra -Scopes 'User.Read.All'
$userInfo = Get-EntraUserCBAAuthorizationInfo -UserId '[email protected]'
$userInfo.AuthorizationInfo.CertificateUserIds | Format-Table Type, TypeName, Value

Risposta:

In questo esempio vengono recuperate le informazioni di autorizzazione.

Esempio 3: Estrarre gli ID utente specifici del certificato

Connect-Entra -Scopes 'User.Read.All'
$userInfo = Get-EntraUserCBAAuthorizationInfo -UserId [email protected]'
$userInfo.AuthorizationInfo.CertificateUserIds | Where-Object Type -eq "PN" | Select-Object -ExpandProperty Value

Risposta:[email protected]

In questo esempio vengono recuperate le informazioni di autorizzazione e quindi filtrate per visualizzare solo i valori del certificato Nome Principale.

Get-EntraUserCertificateUserIdsFromCertificate

Restituisce un oggetto con i valori del certificato necessari per configurare CertificateUserIDs per l'autenticazione Certificate-Based in Microsoft Entra ID.

Sintassi: Get-EntraUserCertificateUserIdsFromCertificate [-Path] <string>[[-Certificate] <System.Security.Cryptography.X509Certificates.X509Certificate2> [-CertificateMapping] <string>][<CommonParameters>]

Se i valori del certificato sono troppo lunghi, è possibile inviare l'output a un file e copiarlo da questa posizione.

Connect-Entra -Scopes 'User.Read.All'
Get-EntraUserCertificateUserIdsFromCertificate -Path C:\Downloads\test.pem | Format-List | Out-File -FilePath ".\certificateUserIds.txt"

Esempio 1: Recuperare l'oggetto certificato da un percorso del certificato

Get-EntraUserCertificateUserIdsFromCertificate -Path 'C:\path\to\certificate.cer'

Risposta:

In questo esempio viene illustrato come ottenere tutte le potenziali mappature dei certificati come oggetto.

Esempio 2: Recuperare l'oggetto certificato da un percorso del certificato e dal mapping dei certificati

Get-EntraUserCertificateUserIdsFromCertificate -Path 'C:\path\to\certificate.cer' -CertificateMapping 'Subject' 

Risposta:X509:<S>DC=com,DC=contoso,OU=UserAccounts,CN=user

Questo comando restituisce la proprietà PrincipalName.

Esempio 3: Recuperare l'oggetto certificato da un certificato

$text = "-----BEGIN CERTIFICATE-----
MIIDiz...=
-----END CERTIFICATE-----"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($text)
$certificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($bytes)
Get-EntraUserCertificateUserIdsFromCertificate -Certificate $certificate -CertificateMapping 'Subject'

Risposta:X509:<S>DC=com,DC=contoso,OU=UserAccounts,CN=user

Questo comando restituisce la proprietà PrincipalName.

Set-EntraUserCBACertificateUserId

Imposta gli ID utente di autenticazione basati su certificati per un utente in Microsoft Entra ID usando un file di certificato o un oggetto.

Syntax Set-EntraUserCBACertificateUserId-UserId <string>[-CertPath <string>][-Cert <System.Security.Cryptography.X509Certificates.X509Certificate2>]-CertificateMapping <string[]>[<CommonParameters>]

Esempio 1: Aggiornare le informazioni di autorizzazione del certificato dell'utente usando il percorso del certificato

Connect-Entra -Scopes 'Directory.ReadWrite.All', 'User.ReadWrite.All'
Set-EntraUserCBACertificateUserId -UserId ‘[email protected]' -CertPath 'C:\path\to\certificate.cer' -CertificateMapping @('Subject', 'PrincipalName')

In questo esempio vengono impostati gli ID utente del certificato per l'utente specificato usando un file di certificato, eseguendo il mapping dei campi Subject e PrincipalName. È possibile usare Get-EntraUserCBAAuthorizationInfo comando per visualizzare i dettagli aggiornati.

Esempio 2: Aggiornare le informazioni di autorizzazione del certificato dell'utente usando un certificato

Connect-Entra -Scopes 'Directory.ReadWrite.All', 'User.ReadWrite.All'
$text = '-----BEGIN CERTIFICATE-----
MIIDiz...=
-----END CERTIFICATE-----'
$bytes = [System.Text.Encoding]::UTF8.GetBytes($text)
$certificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($bytes)
Set-EntraUserCBACertificateUserId -UserId [email protected]' -Cert $certificate -CertificateMapping @('RFC822Name', 'SKI')

In questo esempio vengono impostati gli ID utente del certificato per l'utente specificato usando un oggetto certificato, eseguendo il mapping dei campi RFC822Name e SKI. È possibile usare Get-EntraUserCBAAuthorizationInfo comando per visualizzare i dettagli aggiornati.

Aggiornare certificateUserIds usando l'interfaccia di amministrazione di Microsoft Entra

Usare la procedura seguente per aggiornare certificateUserIds per gli utenti:

1. Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un amministratore di autenticazione con privilegi per gli utenti solo cloud o almeno un amministratore di identità ibrida per gli utenti sincronizzati.

2. Cercare e selezionare Tutti gli utenti.

   

3. Selezionare un utente e selezionare Modifica proprietà.

4. Accanto a Informazioni di autorizzazione, selezionare Visualizza.

   

5. Selezionare Modificare gli ID utente del certificato.

   

6. Selezionare Aggiungi.

   

7. Immettere il valore e selezionare Salva. È possibile aggiungere fino a quattro valori, ognuno di 120 caratteri.

   

Aggiornare certificateUserIds usando query di Microsoft Graph

Gli esempi seguenti illustrano come usare Microsoft Graph per cercare certificateUserIds e aggiornarli.

Cerca certificateUserIds

I chiamanti autorizzati possono eseguire query di Microsoft Graph per trovare tutti gli utenti con un determinato valore certificateUserId. Nell'oggetto utente di Microsoft Graph la raccolta di certificateUserIds viene archiviata nella proprietà authorizationInfo.

Per recuperare i certificateUserIds di tutti gli oggetti utente:

GET https://graph.microsoft.com/v1.0/users?$select=authorizationinfo
ConsistencyLevel: eventual

Per recuperare certificateUserIds per un determinato utente in base all'ObjectId dell'utente:

GET https://graph.microsoft.com/v1.0/users/{user-object-id}?$select=authorizationinfo
ConsistencyLevel: eventual

Per recuperare l'oggetto utente con un valore specifico in certificateUserIds:

GET https://graph.microsoft.com/v1.0/users?$select=authorizationinfo&$filter=authorizationInfo/certificateUserIds/any(x:x eq 'X509:<PN>[email protected]')&$count=true
ConsistencyLevel: eventual

È anche possibile usare gli operatori not e startsWith per trovare la corrispondenza con la condizione di filtro. Per filtrare in base all'oggetto certificateUserIds, la richiesta deve includere la $count=true stringa di query e l'intestazione ConsistencyLevel deve essere impostata su eventual.

Aggiornare certificateUserIds

Eseguire una richiesta PATCH per aggiornare i certificateUserIds per un determinato utente.

Testo della richiesta

PATCH https://graph.microsoft.com/v1.0/users/{user-object-id}
Content-Type: application/json
{
    "authorizationInfo": {
        "certificateUserIds": [
            "X509:<PN>123456789098765@mil"
        ]
    }
}

Aggiornare certificateUserIds usando i comandi di PowerShell di Microsoft Graph

Per questa configurazione, è possibile usare Microsoft Graph PowerShell.

1. Avviare PowerShell con privilegi di amministratore.

2. Installare e importare Microsoft Graph PowerShell SDK.

       Install-Module Microsoft.Graph -Scope CurrentUser
       Import-Module Microsoft.Graph.Authentication
       Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

3. Connettersi al tenant e accettare tutto.

      Connect-MGGraph -Scopes "Directory.ReadWrite.All", "User.ReadWrite.All" -TenantId <tenantId>
   

4. Elencare l'attributo certificateUserIds di un determinato utente.

     $results = Invoke-MGGraphRequest -Method get -Uri 'https://graph.microsoft.com/v1.0/users/<userId>?$select=authorizationinfo' -OutputType PSObject -Headers @{'ConsistencyLevel' = 'eventual' }
     #list certificateUserIds
     $results.authorizationInfo
   

5. Creare una variabile con i valori certificateUserIds.

     #Create a new variable to prepare the change. Ensure that you list any existing values you want to keep as this operation will overwrite the existing value
     $params = @{
           authorizationInfo = @{
                 certificateUserIds = @(
                 "X509:<SKI>gH4iJ5kL6mN7oP8qR9sT0uV1wX", 
                 "X509:<PN>[email protected]"
                 )
           }
     }
   

6. Aggiornare l'attributo certificateUserIds.

      $results = Invoke-MGGraphRequest -Method patch -Uri 'https://graph.microsoft.com/v1.0/users/<UserId>/?$select=authorizationinfo' -OutputType PSObject -Headers @{'ConsistencyLevel' = 'eventual' } -Body $params
   

Aggiorna certificateUserIds utilizzando l'oggetto utente

1. Ottieni l'oggetto utente.

     $userObjectId = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
     $user = Get-MgUser -UserId $userObjectId -Property AuthorizationInfo
   

2. Aggiornare l'attributo certificateUserIds dell'oggetto utente.

      $user.AuthorizationInfo.certificateUserIds = @("X509:<SKI>iJ5kL6mN7oP8qR9sT0uV1wX2yZ", "X509:<PN>[email protected]") 
      Update-MgUser -UserId $userObjectId -AuthorizationInfo $user.AuthorizationInfo
   

Aggiornare gli ID utente del certificato con Microsoft Entra Connect

Microsoft Entra Connect supporta la sincronizzazione dei valori con certificateUserIds da un ambiente Active Directory locale. Active Directory locale supporta l'autenticazione basata su certificati e più associazioni di nomi utente. Assicurarsi di usare la versione più recente di Microsoft Entra Connect.

Per usare questi metodi di mapping, è necessario popolare l'attributo altSecurityIdentities degli oggetti utente nella Active Directory locale. Inoltre, dopo aver applicato modifiche all'autenticazione basata su certificati nei controller di dominio Windows, come descritto in KB5014754, è possibile che siano stati implementati alcuni dei metodi di mapping non riutilizzabili (Tipo=forte) per soddisfare i requisiti di imposizione dell'associazione di certificati forti degli Active Directory locali.

Per evitare errori di sincronizzazione, assicurarsi che i valori sincronizzati seguano uno dei formati supportati per certificateUserIds.

Prima di iniziare, assicurarsi che tutti gli account utente sincronizzati da Active Directory locale abbiano:

• 10 o un numero inferiore di valori negli attributi altSecurityIdentities

• Nessun valore con più di 1.024 caratteri

• Nessun valore duplicato

  Considerare attentamente se un valore duplicato deve associare un singolo certificato a più account di Active Directory locali. Per altre informazioni, vedere Associazioni di più nomi utente.

  Nota

  In scenari specifici, un subset di utenti potrebbe avere una giustificazione aziendale valida per eseguire il mapping di un singolo certificato a più di un account Active Directory locale. Esaminare questi scenari e, se necessario, implementare metodi di mapping separati per eseguire il mapping a più account sia in Active Directory locale che in Microsoft Entra ID.

Considerazioni sulla sincronizzazione continua di certificateUserIds

• Assicurarsi che il processo di provisioning per popolare i valori in Active Directory locale implementi pratiche di sicurezza adeguate. Vengono popolati solo i valori associati ai certificati validi correnti.
• I valori vengono rimossi quando il certificato corrispondente è scaduto o revocato.
• I valori maggiori di 1024 caratteri non vengono popolati.
• Non viene effettuato il provisioning dei valori duplicati.
• Usare Microsoft Entra Connect Health per monitorare la sincronizzazione.

Seguire questa procedura per configurare Microsoft Entra Connect per sincronizzare userPrincipalName con certificateUserIds:

1. Sul server Microsoft Entra Connect, trovare e avviare l'Editor delle regole di sincronizzazione.

2. Selezionare Direzionee selezionare In uscita.

   

3. Trova la regola Out to Microsoft Entra ID - User Identity, seleziona Modificae seleziona Sì per confermare.

   Screenshot dell'identità utente.

4. Immettere un numero elevato nel campo Precedenza e quindi selezionare Avanti.

   

5. Selezionare trasformazioni >e aggiungere trasformazione. Potrebbe essere necessario scorrere verso il basso l'elenco delle trasformazioni prima di crearne uno nuovo.

Sincronizza X509:<PN>NomePrincipale

Per sincronizzare X509:<PN>PrincipalNameValue, creare una regola di sincronizzazione in uscita e scegliere Espressione nel tipo di flusso. Scegliere l'attributo di destinazione come certificateUserIds e nel campo di origine aggiungere l'espressione seguente. Se l'attributo di origine non è userPrincipalName, è possibile modificare l'espressione di conseguenza.

"X509:<PN>"&[userPrincipalName]

Sincronizzare X509:<RFC822>RFC822Name

Per sincronizzare X509:<RFC822>RFC822Name, creare una regola di sincronizzazione in uscita e scegliere Espressione nel tipo di flusso. Scegliere l'attributo di destinazione come certificateUserIds e nel campo di origine aggiungere l'espressione seguente. Se l'attributo di origine non è userPrincipalName, è possibile modificare l'espressione di conseguenza.

"X509:<RFC822>"&[userPrincipalName]

1. Selezionare Attributo di destinazione, selezionare certificateUserIds, selezionare Origine, selezionare userPrincipalNamee quindi selezionare Salva.

   

2. Selezionare OK per confermare.

Per ulteriori informazioni sulle espressioni di provisioning dichiarativo, vedere Microsoft Entra Connect: Declarative Provisioning Expressions.

Sincronizzare l'attributo altSecurityIdentities da Active Directory al certificato Microsoft EntraUserIds

L'attributo altSecurityIdentities non fa parte del set di attributi predefiniti. Un amministratore deve aggiungere un nuovo attributo all'oggetto person nel Metaverse e quindi creare le regole di sincronizzazione appropriate per inoltrare questi dati a certificateUserIds in Microsoft Entra ID.

1. Apri "Metaverse Designer" e seleziona l'oggetto person. Per creare l'attributo alternativeSecurityId, selezionare Nuovo attributo. Selezionare String (non indicizzato) per creare una dimensione dell'attributo fino a 1024 caratteri, ovvero la lunghezza massima supportata per certificateUserIds. Se si seleziona String (indicizzato), la dimensione massima di un valore di attributo è di 448 caratteri. Assicurarsi di selezionare Multivalore.

   

2. Aprire Metaverse Designer e selezionare alternativeSecurityId per aggiungerlo al person object.

   

3. Creare una regola di sincronizzazione in ingresso per trasformare da altSecurityIdentities alla variabile alternativeSecurityId.

   Nella regola in ingresso, utilizza le opzioni seguenti.

   Opzione	valore
   Nome	Nome descrittivo della regola, come ad esempio: Ingressi da Active Directory - altSecurityIdentities
   Sistema Connesso	Dominio di Active Directory locale
   Tipo di Oggetto del Sistema Connesso	utente
   Tipo di Oggetto del Metaverso	persona
   Precedenza	Scegliere un numero inferiore a 100 attualmente non usato

   Selezionare quindi Trasformazioni e creare una mappatura diretta all'attributo di destinazione alternativeSecurityId dall'attributo di origine altSecurityIdentities, come mostrato nello screenshot seguente.

   

4. Creare una regola di sincronizzazione in uscita per trasformare dall'attributo alternativeSecurityId all'attributo certificateUserIds in Microsoft Entra ID.

   Opzione	valore
   Nome	Nome descrittivo della regola, ad esempio: Out to Microsoft Entra ID - certificateUserIds
   Sistema Connesso	Il tuo dominio Microsoft Entra
   Tipo di Oggetto del Sistema Connesso	utente
   Tipo di Oggetto del Metaverso	persona
   Precedenza	Scegliere un numero elevato non attualmente usato sopra tutte le regole predefinite, ad esempio 150

   Selezionare quindi Trasformazioni e creare una mappatura diretta all'attributo di destinazione certificateUserIds dall'attributo di origine alternativeSecurityId, come illustrato nello screenshot seguente.

   

5. Eseguire la sincronizzazione per popolare i dati nell'attributo certificateUserIds.

6. Per verificare l'esito positivo, visualizzare le informazioni di autorizzazione di un utente in Microsoft Entra ID.

   

Per eseguire il mapping di un subset di valori dall'attributo altSecurityIdentities, sostituire la trasformazione nel passaggio 4 con un'espressione. Per usare un'espressione, passare alla scheda Trasformazioni e modificare l'opzione FlowType su Expression, l'attributo di destinazione in certificateUserIds e quindi immettere l'espressione nel campo Origine. Nell'esempio seguente vengono filtrati solo i valori allineati ai campi di mapping dei certificati SKI e SHA1PublicKey:

Screenshot di un'espressione.

Codice dell'espressione:

IIF(IsPresent([alternativeSecurityId]),
                Where($item,[alternativeSecurityId],BitOr(InStr($item, "X509:<SKI>"),InStr($item, "X509:<SHA1-PUKEY>"))>0),[alternativeSecurityId]
)

Gli amministratori possono filtrare i valori da altSecurityIdentities allineati ai modelli supportati. Assicurarsi che la configurazione CBA sia aggiornata per supportare le associazioni di nome utente sincronizzate con certificateUserIds e abilitare l'autenticazione utilizzando questi valori.

Passaggi successivi

• Panoramica di Microsoft Entra CBA
• Approfondimento tecnico su Microsoft Entra CBA
• Come configurare Microsoft Entra CBA
• Microsoft Entra CBA su dispositivi iOS
• Microsoft Entra CBA su dispositivi Android
• Accesso tramite smart card di Windows con Microsoft Entra CBA
• Come eseguire la migrazione di utenti federati
• Domande frequenti