Mapeando para o atributo certificateUserIds no Microsoft Entra ID

Os objetos de usuário no Microsoft Entra ID têm um atributo chamado certificateUserIds.

• O atributo certificateUserIds é multivalorado e pode conter até 10 valores.
• Cada valor não pode ter mais de 1024 caracteres.
• Cada valor deve ser único. Quando um valor está presente em uma conta de usuário, ele não pode ser gravado em nenhuma outra conta de usuário no mesmo locatário do Microsoft Entra.
• O valor não precisa estar no formato de ID de e-mail. O atributo certificateUserIds pode armazenar UPNs (nomes principais de usuário) não roteáveis, como bob@woodgrove ou bob@local.

Padrões suportados para IDs de usuário de certificado

Os valores armazenados em certificateUserIds devem estar no formato descrito na tabela a seguir. Os prefixos X509:<Mapping> são sensíveis a maiúsculas e minúsculas.

Funções para atualizar certificateUserIds

Os usuários somente na nuvem devem ter pelo menos a função de Administrador de Autenticação Privilegiada para atualizar certificateUserIds. Os usuários somente na nuvem podem usar o centro de administração do Microsoft Entra ou o Microsoft Graph para atualizar certificateUserIds.

Os usuários sincronizados devem ter pelo menos a função de Administrador de Identidade Híbrida para atualizar certificateUserIds. Somente o Microsoft Entra Connect pode ser usado para atualizar certificateUserIds sincronizando o valor localmente.

Como encontrar os valores CertificateUserIds corretos para um usuário a partir do certificado de usuário final usando o módulo PowerShell

Os UserIds de certificado seguem um determinado padrão para seus valores de acordo com as configurações de vinculação UserName no locatário. O comando PowerShell a seguir ajuda um administrador a recuperar os valores exatos do atributo Certificate UserIds para um usuário de um certificado de usuário final. Admin também pode obter os valores atuais no atributo Certificate UserIds para um utilizador tendo em conta uma determinada associação de nome de utilizador e definir o valor do atributo Certificate UserIds.

Mais informações em Instalação do Microsoft Entra PowerShell e Microsoft Graph PowerShell.

1. Inicie o PowerShell.

2. Instale e importe o SDK do Microsoft Graph PowerShell.

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

3. Instale o módulo PowerShell do Microsoft Entra (a versão mínima necessária é 1.0.6)

       Install-Module -Name Microsoft.Entra
   

Mais informações sobre o módulo CertificateBasedAuthentication aqui

Get-EntraUserCBAAuthorizationInfo

Get-EntraUserCBAAuthorizationInfo ajuda a recuperar informações de autorização para um usuário do Microsoft Entra ID, incluindo identificadores de autenticação baseados em certificado.

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

Exemplo 1: Obter informações de autorização para um usuário por Nome Principal de Usuário

Connect-Entra -Scopes 'User.Read.All' 
Get-EntraUserCBAAuthorizationInfo -UserId ‘user@contoso.com'

Resposta:

Este comando recupera as informações de autorização para o usuário com o Nome Principal do Usuário especificado.

Exemplo 2: Recuperar informações de autorização para um usuário

Connect-Entra -Scopes 'User.Read.All'
$userInfo = Get-EntraUserCBAAuthorizationInfo -UserId 'user@contoso.com'
$userInfo.AuthorizationInfo.CertificateUserIds | Format-Table Type, TypeName, Value

Resposta:

Este exemplo recupera as informações de autorização.

Exemplo 3: Extrair IDs de usuário de certificado específicos

Connect-Entra -Scopes 'User.Read.All'
$userInfo = Get-EntraUserCBAAuthorizationInfo -UserId user@contoso.com'
$userInfo.AuthorizationInfo.CertificateUserIds | Where-Object Type -eq "PN" | Select-Object -ExpandProperty Value

Resposta:user@contoso.com

Este exemplo recupera as informações de autorização e, em seguida, filtra para exibir apenas os valores do certificado Nome Principal.

Get-EntraUserCertificateUserIdsFromCertificate

Retorna um objeto com os valores de certificado necessários para configurar CertificateUserIDs para autenticação Certificate-Based no Microsoft Entra ID.

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

Se os valores do certificado forem muito longos, você pode enviar a saída para um arquivo e copiar de lá.

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

Exemplo 1: Recuperar objeto de certificado de um caminho de certificado

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

Resposta:

Este exemplo mostra como obter todos os mapeamentos de certificado possíveis como um objeto.

Exemplo 2: Recuperar objeto de certificado de um caminho de certificado e mapeamento de certificado

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

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

Este comando retorna a propriedade PrincipalName.

Exemplo 3: Recuperar objeto de certificado de um certificado

$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'

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

Este comando retorna a propriedade PrincipalName.

Set-EntraUserCBACertificateUserId

Define IDs de usuário de autenticação baseada em certificado para um usuário no Microsoft Entra ID usando um arquivo ou objeto de certificado.

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

Exemplo 1: Atualizar as informações de autorização de certificado do usuário usando o caminho do certificado

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

Este exemplo define as IDs de usuário de certificado para o usuário especificado usando um arquivo de certificado, mapeando os campos Subject e PrincipalName. Você pode usar Get-EntraUserCBAAuthorizationInfo comando para exibir detalhes atualizados.

Exemplo 2: Atualizar as informações de autorização de certificado do usuário usando um certificado

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 user@contoso.com' -Cert $certificate -CertificateMapping @('RFC822Name', 'SKI')

Este exemplo define as IDs de usuário do certificado para o usuário especificado usando um objeto de certificado, mapeando os campos RFC822Name e SKI. Você pode usar Get-EntraUserCBAAuthorizationInfo comando para exibir detalhes atualizados.

Atualizar certificateUserIds usando o centro de administração do Microsoft Entra

Use as seguintes etapas para atualizar certificateUserIds para usuários:

1. Entre no centro de administração do Microsoft Entra como pelo menos um Administrador de Autenticação Privilegiada para usuários somente na nuvem ou como pelo menos um Administrador de Identidade Híbrida para usuários sincronizados.

2. Pesquise e selecione Todos os usuários.

   

3. Selecione um usuário e selecione Editar propriedades.

4. Ao lado de Informações de autorização, selecione Exibir.

   

5. Selecione Editar IDs de usuário do certificado.

   

6. Selecione Adicionar.

   

7. Insira o valor e selecione Salvar. Você pode adicionar até quatro valores, cada um de 120 caracteres.

   

Atualizar certificateUserIds usando consultas do Microsoft Graph

Os exemplos a seguir mostram como usar o Microsoft Graph para procurar certificateUserIds e atualizá-los.

Consultar certificateUserIds

Os chamadores autorizados podem executar consultas do Microsoft Graph para localizar todos os usuários com um determinado valor certificateUserId. No objeto de usuário do Microsoft Graph, a coleção de certificateUserIds é armazenada na propriedade authorizationInfo .

Para recuperar certificateUserIds de todos os objetos de usuário:

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

Para recuperar certificateUserIds para um determinado usuário pelo ObjectId do usuário:

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

Para recuperar o objeto de usuário com um valor específico em certificateUserIds:

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

Você também pode usar os not operadores e startsWith para corresponder à condição do filtro. Para filtrar em relação ao objeto certificateUserIds, a solicitação deve incluir a string de consulta $count=true e o cabeçalho ConsistencyLevel deve ser definido como eventual.

Atualizar IDs de Utilizador de Certificado

Execute uma solicitação PATCH para atualizar o certificateUserIds para um determinado usuário.

Corpo do pedido

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

Atualizar certificateUserIds usando comandos do Microsoft Graph PowerShell

Para essa configuração, você pode usar o Microsoft Graph PowerShell.

1. Inicie o PowerShell com privilégios de administrador.

2. Instale e importe o SDK do Microsoft Graph PowerShell.

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

3. Conecte-se ao locatário e aceite tudo.

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

4. Listar atributo certificateUserIds de um determinado usuário.

     $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. Crie uma variável com valores 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>user@contoso.com"
                 )
           }
     }
   

6. Atualize o atributo certificateUserIds.

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

Atualizar certificateUserIds usando objeto de usuário

1. Obtenha o objeto de usuário.

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

2. Atualize o atributo certificateUserIds do objeto user.

      $user.AuthorizationInfo.certificateUserIds = @("X509:<SKI>iJ5kL6mN7oP8qR9sT0uV1wX2yZ", "X509:<PN>user1@contoso.com") 
      Update-MgUser -UserId $userObjectId -AuthorizationInfo $user.AuthorizationInfo
   

Atualizar certificateUserIds utilizando o Microsoft Entra Connect

O Microsoft Entra Connect oferece suporte à sincronização de valores para certificateUserIds a partir de um ambiente local do Active Directory. O Ative Directory local oferece suporte à autenticação baseada em certificado e a várias associações de nome de usuário. Certifique-se de usar a versão mais recente do Microsoft Entra Connect.

Para usar esses métodos de mapeamento, você precisa preencher o atributo altSecurityIdentities de objetos de usuário no Ative Directory local. Além disso, depois de aplicar alterações de autenticação baseada em certificado em controladores de domínio do Windows, conforme descrito em KB5014754, você pode ter implementado alguns dos métodos de mapeamento não reutilizáveis (Type=strong) para atender aos requisitos de imposição de vinculação de certificado forte do Ative Directory local.

Para evitar erros de sincronização, certifique-se de que os valores que estão sendo sincronizados sigam um dos formatos suportados para o certificateUserIds.

Antes de começar, verifique se todas as contas de usuário sincronizadas do Ative Directory local têm:

• 10 ou menos valores em seus atributos altSecurityIdentities

• Nenhum valor com mais de 1.024 caracteres

• Sem valores duplicados

  Considere cuidadosamente se um valor duplicado se destina a mapear um único certificado para várias contas locais do Ative Directory. Para obter mais informações, consulte Várias associações de nome de usuário.

  Nota

  Em cenários específicos, um subconjunto de usuários pode ter uma justificativa comercial válida para mapear um único certificado para mais de uma conta local do Ative Directory. Analise esses cenários e, quando necessário, implemente métodos de mapeamento separados para mapear para mais de uma conta no Ative Directory local e na ID do Microsoft Entra.

Considerações para a sincronização contínua de certificateUserIds

• Certifique-se de que o processo de provisionamento para preencher os valores no Active Directory local garanta boas práticas de higiene. Somente os valores associados aos certificados válidos atuais são preenchidos.
• Os valores são removidos quando o certificado correspondente expira ou é revogado.
• Valores maiores que 1024 caracteres não são preenchidos.
• Valores duplicados não são provisionados.
• Use o Microsoft Entra Connect Health para monitorar a sincronização.

Siga estes passos para configurar o Microsoft Entra Connect para sincronizar o userPrincipalName aos certificateUserIds.

1. No servidor Microsoft Entra Connect, localize e inicie o Editor de Regras de Sincronização.

2. Selecione Direção e selecione Saída.

   

3. Encontre a regra Out to Microsoft Entra ID – User Identity, selecione Editar e selecione Sim para confirmar.

   

4. Introduza um número elevado no campo Precedência e, em seguida, selecione Seguinte.

   

5. Selecione Transformações>Adicionar transformação. Talvez seja necessário rolar a lista de transformações para baixo antes de criar uma nova.

Sincronizar X509:<PN>PrincipalNameValue

Para sincronizar X509:<PN>PrincipalNameValue, crie uma regra de sincronização de saída e escolha Expression no tipo de fluxo. Escolha o atributo de destino como certificateUserIds e, no campo de origem, adicione a seguinte expressão. Se o atributo de origem não for userPrincipalName, pode alterar a expressão em conformidade.

"X509:<PN>"&[userPrincipalName]

Sincronizar X509:<RFC822>RFC822Name

Para sincronizar X509:<RFC822>RFC822Name, crie uma regra de sincronização de saída e escolha Expressão no tipo de fluxo. Escolha o atributo de destino como certificateUserIds e, no campo de origem, adicione a seguinte expressão. Se o atributo de origem não for userPrincipalName, pode alterar a expressão em conformidade.

"X509:<RFC822>"&[userPrincipalName]

1. Selecione Atributo de Destino, selecione certificateUserIds, selecione Source, selecione userPrincipalName e selecione Save.

   

2. Selecione OK para confirmar.

Para obter mais informações sobre expressões de provisionamento declarativo, consulte Microsoft Entra Connect: expressões de provisionamento declarativo.

Sincronizar o atributo altSecurityIdentities do Ative Directory para o Microsoft Entra certificateUserIds

O atributo altSecurityIdentities não faz parte do conjunto de atributos padrão. Um administrador precisa adicionar um novo atributo ao objeto person no Metaverso e, em seguida, criar as regras de sincronização apropriadas para retransmitir esses dados para certificateUserIds no Microsoft Entra ID.

1. Abra o Metaverse Designer e selecione o objeto pessoa. Para criar o atributo alternativeSecurityId, selecione Novo atributo. Selecione String (não indexável) para criar um tamanho de atributo de até 1024 caracteres, que é o comprimento máximo suportado para certificateUserIds. Se você selecionar String (indexável), o tamanho máximo de um valor de atributo será de 448 caracteres. Certifique-se de selecionar Multivalor.

   

2. Abra o Metaverse Designer e selecione alternativeSecurityId para adicioná-lo ao objeto pessoa.

   

3. Crie uma regra de sincronização de entrada para transformar de altSecurityIdentities para o atributo alternativeSecurityId.

   Na regra de entrada, use as seguintes opções.

   Opção	Valor
   Nome	Nome descritivo da regra, como: In do Ative Directory - altSecurityIdentities
   Sistema conectado	Seu domínio do Ative Directory local
   Tipo de objeto do sistema conectado	utilizador
   Tipo de objeto Metaverso	pessoa
   Precedência	Escolha um número inferior a 100 que não seja usado atualmente

   Em seguida, selecione Transformações e crie um mapeamento direto para o atributo de destino alternativeSecurityId a partir do atributo de origem altSecurityIdentities, conforme mostrado na captura de tela a seguir.

   

4. Crie uma regra de sincronização de saída para transformar do atributo alternativeSecurityId para o atributo certificateUserIds no Microsoft Entra ID.

   Opção	Valor
   Nome	Nome descritivo da regra, como: Out to Microsoft Entra ID - certificateUserIds
   Sistema conectado	O seu domínio Microsoft Entra
   Tipo de objeto do sistema conectado	utilizador
   Tipo de objeto Metaverso	pessoa
   Precedência	Escolha um número alto não usado atualmente acima de todas as regras padrão, como 150

   Em seguida, selecione Transformações e crie um mapeamento direto para o atributo de destino certificateUserIds a partir do atributo de origem alternativeSecurityId, conforme mostrado na captura de tela a seguir.

   

5. Execute a sincronização para preencher dados para o atributo certificateUserIds.

6. Para verificar o êxito, exiba as informações de autorização de um usuário no Microsoft Entra ID.

   

Para mapear um subconjunto de valores do atributo altSecurityIdentities, substitua a Transformação na etapa 4 por uma Expressão. Para usar uma expressão, vá para a guia Transformações e altere a opção FlowType para Expression, o atributo de destino para certificateUserIds e, em seguida, insira a expressão no campo Source. O exemplo a seguir filtra apenas valores que se alinham aos campos de mapeamento SKI e SHA1PublicKey Certificate:

Código de expressão:

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

Os administradores podem filtrar valores de altSecurityIdentities que se alinham com os padrões suportados. Certifique-se de que a configuração do CBA esteja atualizada para suportar as associações de nome de usuário sincronizadas com certificateUserIds e habilite a autenticação usando esses valores.

Próximos passos

• Visão geral do Microsoft Entra CBA
• Análise técnica aprofundada para Microsoft Entra CBA
• Como configurar o Microsoft Entra CBA
• Lista de Revogação de Certificados CBA do Microsoft Entra
• Microsoft Entra CBA em dispositivos iOS
• Microsoft Entra CBA em dispositivos Android
• Início de sessão com cartão inteligente do Windows usando o Microsoft Entra CBA
• Como migrar usuários federados
• Perguntas Frequentes