映射到 Microsoft Entra ID 中的 CertificateUserIds 属性

项目
06/14/2024

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

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

注意

尽管每个值在 Microsoft Entra ID 中必须唯一，但可以通过实现多个用户名绑定将单个证书映射到多个帐户。有关详细信息，请参阅多个用户名绑定。

证书用户 ID 的支持模式

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

证书映射字段	certificateUserIds 中的值示例
PrincipalName	`X509:<PN>bob@woodgrove.com`
PrincipalName	`X509:<PN>bob@woodgrove`
RFC822Name	`X509:<RFC822>user@woodgrove.com`
IssuerAndSubject	`X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<S>DC=com,DC=contoso,OU=UserAccounts,CN=mfatest`
Subject	`X509:<S>DC=com,DC=contoso,OU=UserAccounts,CN=mfatest`
SKI	`X509:<SKI>aB1cD2eF3gH4iJ5kL6mN7oP8qR`
SHA1PublicKey	`X509:<SHA1-PUKEY>cD2eF3gH4iJ5kL6mN7oP8qR9sT`
IssuerAndSerialNumber	`X509:<I>DC=com,DC=contoso,CN=CONTOSO-DC-CA<SR>eF3gH4iJ5kL6mN7oP8qR9sT0uV` 若要获取序列号的正确值，请运行以下命令并存储 CertificateUserIds 中显示的值：语法： `Certutil –dump –v [~certificate path~] >> [~dumpFile path~]` 示例： `certutil -dump -v firstusercert.cer >> firstCertDump.txt`

更新 certificateUserIds 的角色

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

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

注意

Active Directory 管理员可以进行更改，这些更改会影响任何已同步帐户 Microsoft Entra ID 中的 CertificateUserIds 值。管理员可以纳入具有已同步用户帐户的委派管理权限或 Microsoft Entra Connect 服务器管理权限的帐户。

更新 certificateUserIds

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

至少以仅限云用户的特权身份验证管理员或已同步用户的混合标识管理员身份登录到 Microsoft Entra 管理中心。
搜索并选择“所有用户”。
单击一个用户，然后单击“编辑属性”。
在“授权信息”旁边，单击“查看”。
单击“编辑证书用户 ID”。
单击“添加” 。
输入值，然后单击“保存”。最多可以添加四个值，每个值 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"
        ]
    }
}

使用 PowerShell 命令更新 certificateUserIds

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

使用管理员特权启动 PowerShell。

安装和导入 Microsoft Graph PowerShell SDK。

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

连接到租户并全部接受。

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

列出给定用户的 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

使用 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"
              )
        }
  }

更新 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

获取用户对象。

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

更新用户对象的 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 属性。此外，按 KB5014754 所述在 Windows 域控制器上应用基于证书的身份验证更改后，你可能已经实现了一些不可重用的映射方法（类型 = 强），以满足本地 Active Directory 强证书绑定强制执行要求。

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

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

其 altSecurityIdentities 属性中的值不超过 5 个
没有超过 1024 个字符的值
无重复值

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

注意

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

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

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

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

在 Microsoft Entra Connect 服务器上，查找并启动“同步规则编辑器”。
单击“方向”，然后单击“出站”。
查找规则“输出到 Microsoft Entra ID - 用户标识”，单击“编辑”，然后单击“是”以确认。
在“优先级”字段中输入一个高的数字，然后单击“下一步”。
单击“转换”>“添加转换”。可能需要先向下滚动转换列表，再创建新的转换。

同步 X509:<PN>PrincipalNameValue

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

"X509:<PN>"&[userPrincipalName]

如何同步 x509 的屏幕截图。

同步 X509:<RFC822>RFC822Name

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

"X509:<RFC822>"&[userPrincipalName]

如何同步 RFC822Name 的屏幕截图。

单击“目标属性”，选择“CertificateUserIds”，单击“源”，选择“userPrincipalName”，然后单击“保存”。
单击“确定”以确认。

重要

上述示例使用 userPrincipalName 属性作为转换规则中的源属性。可以使用包含相应值的任何可用属性。例如，某些组织使用邮件属性。有关更多复杂的转换规则，请参阅 Microsoft Entra Connect 同步：了解声明性预配表达式

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

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

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

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

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

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

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

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

如何从 altSecurityIdentities 转换为 alternateSecurityId 属性的屏幕截图。

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

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

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

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

运行同步将数据填充到 certificateUserIds 属性。
若要验证成功，请查看 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 配置已更新，以支持正在同步到 certificateUserIds 的用户名绑定，以使用这些值启用身份验证。

通过

映射到 Microsoft Entra ID 中的 CertificateUserIds 属性

证书用户 ID 的支持模式

更新 certificateUserIds 的角色

更新 certificateUserIds

使用 Microsoft Graph 查询更新 certificateUserIds

查找 certificateUserIds

更新 certificateUserIds

请求正文

使用 PowerShell 命令更新 certificateUserIds

使用 Microsoft Entra Connect 更新 CertificateUserIds

同步 X509:<PN>PrincipalNameValue

同步 X509:<RFC822>RFC822Name

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

后续步骤

反馈

其他资源