映射到 Microsoft Entra ID 中的 CertificateUserIds 属性

Microsoft Entra ID 中的用户对象拥有一个名为 CertificateUserIds 的属性。

• certificateUserIds 属性是多值属性，最多可以容纳 10 个值。
• 每个值的长度不能超过 1024 个字符。
• 每个值必须是唯一值。 一旦某个值出现在一个用户帐户上，它便无法写入同一 Microsoft Entra 租户中的任何用户帐户。
• 该值无需使用电子邮件 ID 格式。 CertificateUserIds 属性可以存储不可路由的用户主体名称 (UPN)，例如 bob@woodgrove 或 bob@local。

证书用户 ID 的支持模式

存储在 certificateUserIds 中的值应采用下表中所述的格式。 X509：<映射>前缀区分大小写。

更新 certificateUserIds 的角色

云专用用户必须至少具有特权身份验证管理员角色才能更新证书用户ID。 仅限云的用户可使用 Microsoft Entra 管理中心或 Microsoft Graph 更新 CertificateUserIds。

已同步用户必须至少具有“混合标识管理员”角色才能更新 CertificateUserIds。 只有 Microsoft Entra Connect 可用于通过同步本地值来更新 CertificateUserIds。

如何使用 PowerShell 模块从最终用户证书中查找用户的正确 CertificateUserIds 值

根据租户上的 UserName 绑定配置，证书 UserId 遵循其值的特定模式。 以下 PowerShell 命令可帮助管理员从最终用户证书中检索用户的 Certificate UserIds 属性的确切值。 管理员还可以获取给定用户名绑定的用户的 Certificate UserIds 属性中的当前值，并设置 Certificate UserIds 属性的值。

更多信息请访问 Microsoft Entra PowerShell 安装 和 Microsoft Graph PowerShell。

1. 启动 PowerShell。

2. 安装和导入 Microsoft Graph PowerShell SDK。

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

3. 安装Microsoft Entra PowerShell 模块（最低所需版本为 1.0.6）

       Install-Module -Name Microsoft.Entra
   

有关 CertificateBasedAuthentication 模块的更多信息，请点击此处

Get-EntraUserCBAAuthorizationInfo

Get-EntraUserCBAAuthorizationInfo 有助于检索Microsoft Entra ID 用户的授权信息，包括基于证书的身份验证标识符。

语法： Get-EntraUserCBAAuthorizationInfo [-UserId] <String>[-Raw][<CommonParameters>]

示例 1：按用户主体名称获取用户的授权信息

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

响应：

此命令检索具有指定用户主体名称的用户的授权信息。

示例 2：检索用户的授权信息

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

响应：

此示例检索授权信息。

示例 3：提取特定证书用户 ID

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

响应：user@contoso.com

此示例检索授权信息，然后筛选以仅显示主体名称证书值。

Get-EntraUserCertificateUserIdsFromCertificate

返回一个对象，其中包含在 Microsoft Entra ID 中为 Certificate-Based 身份验证配置 CertificateUserID 所需的证书值。

语法： Get-EntraUserCertificateUserIdsFromCertificate [-Path] <string>[[-Certificate] <System.Security.Cryptography.X509Certificates.X509Certificate2> [-CertificateMapping] <string>][<CommonParameters>]

如果证书中的值太长，则可以将输出发送到文件并从中复制。

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

示例 1：从证书路径检索证书对象

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

响应：

此示例演示如何以对象的形式获取所有可能的证书映射。

示例 2：从证书路径和证书映射中检索证书对象

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

响应：X509:<S>DC=com,DC=contoso,OU=UserAccounts,CN=user

此命令返回 PrincipalName 属性。

示例 3：从证书检索证书对象

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

响应：X509:<S>DC=com,DC=contoso,OU=UserAccounts,CN=user

此命令返回 PrincipalName 属性。

Set-EntraUserCBACertificateUserId

使用证书文件或对象为Microsoft Entra ID 中的用户设置基于证书的身份验证用户 ID。

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

示例 1：使用证书路径更新用户的证书授权信息

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

此示例使用证书文件为指定用户设置证书用户 ID，并映射 Subject 和 PrincipalName 字段。 可以使用 Get-EntraUserCBAAuthorizationInfo 命令查看更新的详细信息。

示例 2：使用证书更新用户的证书授权信息

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

此示例使用证书对象为指定用户设置证书用户 ID，并映射 RFC822Name 和 SKI 字段。 可以使用 Get-EntraUserCBAAuthorizationInfo 命令查看更新的详细信息。

使用 Microsoft Entra 管理中心更新证书用户ID

按照以下步骤更新用户的 CertificateUserIds：

1. 至少以仅限云用户的特权身份验证管理员或已同步用户的混合标识管理员身份登录到 Microsoft Entra 管理中心。

2. 搜索并选择“所有用户”。

   

3. 选择用户，然后选择“编辑属性”。

4. 在 授权信息旁边，选择 查看。

   

5. 选择编辑证书用户 ID。

   

6. 选择“添加”。

   

7. 输入值并选择 保存。 最多可以添加四个值，每个值 120 个字符。

   

使用 Microsoft Graph 查询更新 certificateUserIds

以下示例介绍如何使用 Microsoft Graph 查找并更新 CertificateUserIds。

查找 certificateUserIds

获得授权的调用方可以运行 Microsoft Graph 查询来查找具有给定 certificateUserId 值的所有用户。 在 Microsoft Graph 用户对象上，certificateUserIds 的集合存储在 authorizationInfo 属性中。

若要检索所有用户对象的 certificateUserIds：

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

若要按用户的 ObjectId 检索给定用户的 certificateUserIds：

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

若要检索 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

还可以使用 not 和 startsWith 运算符来匹配筛选条件。 若要根据 CertificateUserIds 对象进行筛选，请求必须包含 $count=true 查询字符串，并且“ConsistencyLevel”标头必须设置为 eventual。

更新 certificateUserIds

运行 PATCH 请求以更新给定用户的 certificateUserIds。

请求正文

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

使用 Microsoft Graph PowerShell 命令更新 certificateUserIds

对于此配置，可以使用 Microsoft Graph PowerShell。

1. 使用管理员特权启动 PowerShell。

2. 安装和导入 Microsoft Graph PowerShell SDK。

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

3. 连接到租户并全部接受。

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

4. 列出给定用户的 CertificateUserIds 属性。

     $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. 使用 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. 更新 CertificateUserIds 属性。

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

使用用户对象更新 CertificateUserIds

1. 获取用户对象。

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

2. 更新用户对象的 CertificateUserIds 属性。

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

使用 Microsoft Entra Connect 更新 CertificateUserIds

Microsoft Entra Connect 支持将值从本地 Active Directory 环境同步到 certificateUserIds。 本地 Active Directory 支持基于证书的身份验证和多个用户名绑定。 确保使用最新版本的 Microsoft Entra Connect。

若要使用这些映射方法，需要在本地 Active Directory 中填充用户对象的 altSecurityIdentities 属性。 此外，在 Windows 域控制器上应用基于证书的身份验证更改（如 KB5014754 中所述），你可能已经实现了一些不可重用的映射方法 (Type=strong) 映射方法，以满足本地 Active Directory 强证书绑定强制要求。

若要防止同步错误，请确保同步的值使用 CertificateUserIds 支持的格式。

在开始之前，请确保从本地 Active Directory 同步的所有用户帐户均满足下列条件：

• 其 altSecurityIdentities 属性中的值不超过 10 个

• 任何值不得超过 1,024 个字符

• 无重复值

  请仔细考虑是否打算将单个证书映射到多个本地 Active Directory 帐户。 有关详细信息，请参阅多个用户名绑定。

  注意

  在特定应用场景中，一部分用户可能有有效的业务理由将单个证书映射到多个本地 Active Directory 帐户。 查看这些方案，并在需要的地方实现单独的映射方法，以在本地 Active Directory 和 Microsoft Entra ID 中映射到多个帐户。

有关持续同步 CertificateUserIds 的注意事项

• 确保用于填充本地 Active Directory 值的预配过程实现适当的机制。 仅填充与当前有效证书相关联的值。
• 若相应的证书过期或被撤销则删除值。
• 不会填充大于 1024 个字符的值。
• 系统不会预配重复值。
• 使用 Microsoft Entra Connect Health 监视同步状态。

按照以下步骤配置 Microsoft Entra Connect，将 userPrincipalName 同步到 CertificateUserIds：

1. 在 Microsoft Entra Connect 服务器上，查找并启动“同步规则编辑器”。

2. 选择方向，然后选择出站。

   

3. 查找规则输出到 Microsoft Entra ID - 用户标识，选择编辑，然后选择是以确认。

   

4. 在优先级字段中输入一个高的数字，然后选择下一步。

   

5. 选择转换>添加转换。 在创建新的转换前，你可能需要向下滚动转换列表。

同步 X509:<PN>PrincipalNameValue

若要同步 X509:<PN>PrincipalNameValue，请创建出站同步规则，并在流类型中选择表达式。 将目标属性选择为 certificateUserIds，并在源字段中添加以下表达式。 如果源属性不是 userPrincipalName，则可以相应地更改表达式。

"X509:<PN>"&[userPrincipalName]

同步 X509:<RFC822>RFC822Name

若要同步 X509:<RFC822>RFC822Name，请创建出站同步规则，并在流类型中选择“表达式”。 将目标属性选择为 certificateUserIds，并在源字段中添加以下表达式。 如果源属性不是 userPrincipalName，则可以相应地更改表达式。

"X509:<RFC822>"&[userPrincipalName]

1. 选择“目标属性”，选择“CertificateUserIds”，选择“源”，选择“UserPrincipalName”，然后选择“保存”。

   

2. 选择 “OK” 进行确认。

有关声明性预配表达式的详细信息，请参阅 Microsoft Entra Connect：声明性预配表达式。

将 altSecurityIdentities 属性从 Active Directory 同步到 Microsoft Entra certificateUserIds

altSecurityIdentities 属性不属于默认属性集的内容。 管理员需要向 Metaverse 中的 person 对象添加新属性，然后创建适当的同步规则，以将此数据中继到 Microsoft Entra ID 中的 certificateUserIds。

1. 打开 Metaverse 设计器并选择人员对象。 若要创建 alternativeSecurityId 属性，请选择 新属性。 选择“字符串（不可索引）”以创建大小上限为 1024 个字符（这是 CertificateUserIds 支持的长度上限）的属性。 如果选择“字符串（可索引）”，则属性值的大小上限为 448 个字符。 请确保选择“多值”。

   

2. 打开 Metaverse 设计器，然后选择 alternativeSecurityId 以将其添加到 person 对象。

   

3. 创建入站同步规则，以从 altSecurityIdentities 转换为 alternativeSecurityId 属性。

   在入站规则中，使用以下选项。

   选项	值
   名称	规则的描述性名称，例如：In from Active Directory - altSecurityIdentities
   连接的系统	本地 Active Directory 域
   连接的系统对象类型	用户
   Metaverse 对象类型	人
   优先级	选择当前未使用的 100 以下的数字

   然后单击“转换”，并创建从源属性 altSecurityIdentities 到目标属性 alternativeSecurityId 的直接映射，如以下屏幕截图所示。

   

4. 创建出站同步规则，以便从 alternativeSecurityId 属性转换为 Microsoft Entra ID 中的 certificateUserIds 属性。

   选项	值
   名称	规则的描述性名称，例如：输出到 Microsoft Entra ID - certificateUserIds
   连接的系统	Microsoft Entra 域
   连接的系统对象类型	用户
   Metaverse 对象类型	人
   优先级	选择当前未使用的高于所有默认规则的数字，例如 150

   然后选择“转换”，并创建从源属性 alternativeSecurityId 到目标属性 certificateUserId 的直接映射，如以下屏幕截图所示。

   用于将 alternateSecurityId 属性转换为 certificateUserIds 的出站同步规则的屏幕截图。

5. 运行同步将数据填充到“certificateUserIds”属性中。

6. 若要验证成功，请查看 Microsoft Entra ID 中用户的授权信息。

   

若要映射 altSecurityIdentities 属性中的值子集，请使用表达式替换步骤 4 中的转换。 若要使用表达式，转到“转换”选项卡，将 FlowType 选项改为“表达式”，目标属性改为 CertificateUserIds，然后在“源”字段中输入下列表达式。 以下示例仅筛选与 SKI 和 SHA1PublicKey 证书映射字段一致的值：

表达式代码：

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

管理员可以从与支持的模式一致的 altSecurityIdentities 中筛选值。 确保 CBA 配置已更新，以支持同步到 certificateUserId 的用户名绑定，并使用这些值启用身份验证。

后续步骤

• Microsoft Entra CBA 概述
• Microsoft Entra CBA 的技术深入探讨
• 如何配置 Microsoft Entra CBA
• iOS 设备上的 Microsoft Entra CBA
• Android 设备上的 Microsoft Entra CBA
• 使用 Microsoft Entra CBA 进行 Windows 智能卡登录
• 如何迁移联合用户
• 常见问题