Mapeamento do atributo certificateUserIds no Microsoft Entra ID

Os objetos de usuário do Microsoft Entra ID podem ter um atributo de vários valores chamado certificateUserIds.

• O atributo certificateUserIds tem vários valores, podendo 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 outras contas 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 segurança) não roteáveis, como bob@woodgrove ou bob@local.

Padrões com suporte para IDs de usuário de certificado

Os valores armazenados em certificateUserIds deverão estar no formato descrito na tabela a seguir. Os prefixos X509:<Mapping> diferenciam maiúsculas de minúsculas.

Funções para atualizar os IDs de usuários de certificados

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 os 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 a partir do ambiente local.

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

Certificate UserIds segue um determinado padrão para seus valores, de acordo com as configurações de associação de nome de usuário no locatário. O comando do PowerShell a seguir ajuda um administrador a recuperar os valores exatos do atributo UserIds de certificado para um usuário de um certificado de usuário final. O administrador também pode obter os valores atuais no atributo Certificate UserIds de um usuário para uma associação de nome de usuário específica e definir o valor desse atributo.

Mais informações na Instalação do Microsoft Entra PowerShell e no 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. Instalar o módulo do Microsoft Entra PowerShell (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 da ID do Microsoft Entra, 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 pelo Nome do Usuário Principal

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

Resposta:

Esse comando recupera as informações de autorização para o usuário com o User Principal Name 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íficas

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 de Nome Principal.

Get-EntraUserCertificateUserIdsFromCertificate

Retorna um objeto com os valores de certificado necessários para configurar CertificateUserIDs para autenticação baseada em certificado 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ê poderá enviar a saída para um arquivo e copiar a partir daí.

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

Exemplo 1: recuperar o 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

Esse comando retorna a propriedade PrincipalName.

Exemplo 3: recuperar o 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

Esse comando retorna a propriedade PrincipalName.

Set-EntraUserCBACertificateUserId

Define IDs de usuário de autenticação baseadas em certificado para um usuário na ID do Microsoft Entra 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 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 do usuário do certificado para o usuário especificado usando um arquivo de certificado, mapeando os campos Assunto e NomePrincipal. Você pode usar Get-EntraUserCBAAuthorizationInfo comando para exibir os detalhes atualizados.

Exemplo 2: atualizar 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 os detalhes atualizados.

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

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

1. Entre no centro de administração do Microsoft Entra pelo menos como um Administrador de Autenticação Privilegiada para usuários somente na nuvem ou pelo menos como 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 para Editar IDs de usuário do certificado.

   

6. Selecione Adicionar.

   

7. Insira o valor e selecione Salvar. É possível adicionar até quatro valores, cada um com 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.

Pesquisar certificateUserIds

Chamadores autorizados podem executar consultas do Microsoft Graph para encontrar todos os usuários com um valor específico de 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 operadores not e startsWith para corresponder à condição de filtro. Para filtrar o objeto certificateUserIds, a solicitação deve incluir a sequência de consulta $count=true e o cabeçalho ConsistencyLevel deve ser definido como eventual.

Atualizar certificateUserIds

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

Corpo da solicitação

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 esta configuração, é possível usar o PowerShell do Microsoft Graph.

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. Liste o 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 de 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 um 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 de usuário.

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

Atualize os certificateUserIds usando o Microsoft Entra Connect

O Microsoft Entra Connect oferece suporte à sincronização de valores para os certificateUserIds a partir de um ambiente do Active Directory local. O Active Directory local oferece suporte à autenticação baseada em certificado e a várias associações de nome de usuário. Use a última versão do Microsoft Entra Connect.

Para usar esses métodos de mapeamento, é necessário preencher o atributo altSecurityIdentities dos objetos de usuário no Active Directory local. Além disso, depois de aplicar alterações de autenticação baseadas em certificado em controladores de domínio do Windows, conforme descrito no KB5014754, talvez você tenha implementado alguns métodos de mapeamento não reutilizável (Tipo=forte) para atender aos requisitos de vinculação rigorosa de certificados fortes do Active Directory local.

Para evitar erros de sincronização, verifique se os valores que estão sendo sincronizados seguem um dos formatos com suporte para o certificateUserIds.

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

• 10 ou menos valores em seus atributos altSecurityIdentities

• Nenhum valor com mais de 1.024 caracteres

• Nenhum valor duplicado

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

  Observação

  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 do Active Directory local. Examine esses cenários e, quando necessário, implemente métodos de mapeamento separados para mapear para mais de uma conta no Active Directory local e na ID do Microsoft Entra.

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

• Certifique-se de que o processo de provisionamento para preencher os valores no Active Directory local implemente as medidas de higiene adequadas. 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 estas etapas para configurar o Microsoft Entra Connect para sincronizar userPrincipalName com certificateUserIds:

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

2. Selecione Direçãoe selecione Saída.

   

3. Localize a regra Saída para Microsoft Entra ID – Identidade do usuário, selecione Editar e Sim para confirmar.

   

4. Insira um número alto no campo Precedência e selecione Avançar.

   

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 o X509:<PN>PrincipalNameValue, 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, você poderá alterar a expressão adequadamente.

"X509:<PN>"&[userPrincipalName]

Sincronizar X509:<RFC822>RFC822Name

Para sincronizar o 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, você poderá alterar a expressão adequadamente.

"X509:<RFC822>"&[userPrincipalName]

1. Selecione Atributo de Destino, selecione certificateUserIds, selecione Origem, selecione userPrincipalName e selecione Salvar.

   

2. Selecione OK para confirmar.

Para obter mais informações sobre as expressões de provisionamento declarativas, confira Microsoft Entra Connect: expressões de provisionamento declarativas.

Sincronizar o atributo altSecurityIdentities do Active Directory com o certificateUserIds do Microsoft Entra

O atributo altSecurityIdentities não faz parte do conjunto de atributos padrão. Um administrador precisa adicionar um novo atributo ao objeto de pessoa no Metaverso e depois 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 Sequência (não indexável) para criar um tamanho de atributo de até 1024 caracteres, que é o comprimento máximo com suporte para certificateUserIds. Se você selecionar String (indexável), o tamanho máximo de um valor de atributo será de 448 caracteres. Selecione Vários valores.

   

2. Abra o Designer de Metaverso e selecione AlternativeSecurityId para adicioná-lo ao objeto de 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: Entrada do Active Directory – altSecurityIdentities
   Sistema Conectado	Seu domínio do Active Directory local
   Tipo de Objeto do Sistema Conectado	usuário
   Tipo de Objeto de Metaverso	pessoa
   Precedência	Escolha um número abaixo de 100 que não seja usado no momento

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

   

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

   Opção	Valor
   Nome	Nome descritivo da regra, como: Microsoft Entra ID – certificateUserIds
   Sistema Conectado	Seu domínio do Microsoft Entra
   Tipo de Objeto do Sistema Conectado	usuário
   Tipo de Objeto de 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 do atributo de origem alternativeSecurityId para o atributo de destino certificateUserIds, 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 sua opção FlowType para Expressão, o atributo de destino para certificateUserIds e insira a expressão no campo Origem. O exemplo a seguir filtra apenas valores alinhados aos campos de mapeamento de Certificado SKI e SHA1PublicKey:

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 com suporte. Verifique se a configuração da CBA é atualizada para dar suporte às associações de nome de usuário sincronizadas com certificateUserIds e habilitar a autenticação usando esses valores.

Próximas etapas

• Visão geral da CBA do Microsoft Entra
• Imersão técnica no Microsoft Entra CBA
• Como configurar o Microsoft Entra CBA
• Lista de revogação de certificados do Microsoft Entra CBA
• CBA do Microsoft Entra em dispositivos iOS
• CBA do Microsoft Entra em dispositivos Android
• Logon de cartão inteligente do Windows usando a CBA do Microsoft Entra
• Como migrar usuários federados
• perguntas frequentes