声明的配置发现

Windows 声明的配置 (WinDC) 发现使用专用 JSON 架构从 发现服务终结点 (DS) 查询注册详细信息。 此过程涉及发送具有特定标头和 JSON 正文的 HTTP 请求,其中包含用户域、租户 ID 和 OS 版本等详细信息。 DS 根据注册类型 (Microsoft Entra 加入或注册的设备) ,使用必要的注册服务 URL 和身份验证策略进行响应。

本文概述了 HTTP 请求和响应正文的架构结构,并提供指导实现的示例。

架构结构

HTTP 请求标头

标题 必需 描述
MS-CV: %s 否 注册的相关向量
client-request-id: %s 否 请求 ID
Content-Type: application/json 是 HTTP Content-Type

HTTP 请求正文 (JSON)

字段 必需 描述
userDomain 否 已注册帐户的域名
upn 否 已注册帐户的用户主体名称 (UPN)
tenantId 否 已注册帐户的租户 ID
emmDeviceId 否 企业移动性管理 (EMM) 已注册帐户的设备 ID
enrollmentType 已加入Microsoft Entra:否
已注册Microsoft Entra:是
已注册帐户的注册类型。

支持的值:
- Device:指示父注册类型Microsoft Entra联接 (DS 响应应指定“AuthPolicy”:“Federated”) 。
- User:指示父注册类型Microsoft Entra已注册 (DS 响应应指定“AuthPolicy”:“Certificate”) 。
- 旧案例 (Microsoft Entra 仅) 联接:如果enrollmentType参数未包含在请求正文中,则设备应被视为已加入Microsoft Entra。
osVersion 是 设备上的 OS 版本。 DS 可以使用 osVersion 来确定客户端平台是否支持 WinDC 注册。 有关详细信息 ,请查看支持的平台 。

HTTP DS 响应正文 (JSON)

字段 必需 描述
EnrollmentServiceUrl 是 WinDC 注册服务的 URL
EnrollmentVersion 否 注册版本
EnrollmentPolicyServiceUrl 是 注册策略服务 URL
AuthenticationServiceUrl 是 身份验证服务 URL
ManagementResource 否 管理资源
TouUrl 否 使用条款 URL
AuthPolicy 是 身份验证策略。 支持的值:
- Federated加入Microsoft Entra) 所需的 (
- CertificateMicrosoft Entra已注册) 需要 (
errorCode 否 错误代码
message 否 状态消息

示例

发现请求

标题

Content-Type: application/json

正文

  1. 单一模板方法:客户端在初始请求中发送 UPN 值以及 tenantId 参数。

    1. 已加入Microsoft Entra:

      {
          "userDomain" : "contoso.com",
          "upn" : "johndoe@contoso.com",
          "tenantId" : "00000000-0000-0000-0000-000000000000",
          "emmDeviceId" : "00000000-0000-0000-0000-000000000000",
          "enrollmentType" : "Device",
          "osVersion" : "10.0.00000.0"
      }
      
    2. 已注册Microsoft Entra:

      {
      
          "userDomain" : "contoso.com",
          "upn" : "johndoe@contoso.com",
          "tenantId" : "00000000-0000-0000-0000-000000000000",
          "emmDeviceId" : "00000000-0000-0000-0000-000000000000",
          "enrollmentType" : "Device",
          "osVersion" : "10.0.00000.0"
      }
      
  2. 没有 UPN (旧版)

    1. 已加入Microsoft Entra:

      {
          "userDomain" : "contoso.com",
          "emmDeviceId" : "00000000-0000-0000-0000-000000000000",
          "enrollmentType" : "Device",
          "osVersion" : "10.0.00000.0"
      }
      
    2. 已注册Microsoft Entra:

      {
          "userDomain" : "contoso.com",
          "emmDeviceId" : "00000000-0000-0000-0000-000000000000",
          "enrollmentType" : "User",
          "osVersion" : "10.0.00000.0"
      }
      
  3. 服务器请求的 UPN (旧格式) 。 查看 错误处理 ,详细了解服务器在初始请求中未提供 UPN 数据时如何请求 UPN 数据。

    1. 已加入Microsoft Entra:

      {
          "upn" : "johndoe@contoso.com",
          "emmDeviceId" : "00000000-0000-0000-0000-000000000000",
          "enrollmentType" : "Device",
          "osVersion" : "10.0.00000.0"
      }
      
    2. 已注册Microsoft Entra:

      {
          "upn" : "johndoe@contoso.com",
          "emmDeviceId" : "00000000-0000-0000-0000-000000000000",
          "enrollmentType" : "User",
          "osVersion" : "10.0.00000.0"
      }
      

发现响应

标题

Content-Type: application/json

正文

  1. Microsoft Entra联接 (需要 "AuthPolicy": "Federated") :

    {
        "EnrollmentServiceUrl" : "https://manage.contoso.com/Enrollment/Discovery",
        "EnrollmentPolicyServiceUrl" : "https://manage.contoso.com/Enrollment/GetPolicies",
        "AuthenticationServiceUrl" : "https://manage.contoso.com/Enrollment/AuthService",
        "AuthPolicy" : "Federated",
        "ManagementResource":"https://manage.contoso.com",
        "TouUrl" : "https://manage.contoso.com/Enrollment/tou.aspx"
    }
    
  2. Microsoft Entra已注册 (需要 "AuthPolicy": "Certificate") :

    {
        "EnrollmentServiceUrl" : "https://manage.contoso.com/Enrollment/Discovery",
        "EnrollmentPolicyServiceUrl" : "https://manage.contoso.com/Enrollment/GetPolicies",
        "AuthenticationServiceUrl" : "https://manage.contoso.com/Enrollment/AuthService",
        "AuthPolicy" : "Certificate",
        "ManagementResource":"https://manage.contoso.com",
        "TouUrl" : "https://manage.contoso.com/Enrollment/tou.aspx"
    }
    

Authentication

WinDC 注册需要对已加入和已注册Microsoft Entra设备使用不同的身份验证机制。 WinDC DS 必须基于enrollmentType请求的 属性,通过在发现响应中指定适当的AuthPolicy值来与身份验证模型集成。

  • Microsoft Entra加入的设备使用联合身份验证 (Microsoft Entra 设备令牌) 。
  • Microsoft Entra已注册的设备使用证书身份验证 (为父注册) 预配的 MDM 证书。

规则

  • 对于已加入Microsoft Entra的设备:

    • 发现请求: "enrollmentType": "Device"
    • 发现响应: "AuthPolicy": "Federated"
    • 身份验证:客户端使用 Microsoft Entra 设备令牌向 WinDC 注册服务器进行身份验证。
  • 对于值为空的 enrollmentType 旧 () :

    • 发现请求: "enrollmentType": ""
    • 发现响应: "AuthPolicy": "Federated"
    • 身份验证:客户端使用 Microsoft Entra 设备令牌向 WinDC 注册服务器进行身份验证。
  • 对于已注册Microsoft Entra设备:

    • 发现请求: "enrollmentType": "User"
    • 发现响应: "AuthPolicy": "Certificate"
    • 身份验证:客户端使用父注册中的 MDM 证书向 WinDC 注册服务器进行身份验证。

错误处理

  • UPNRequired:如果发现请求中未提供 UPN 值,DS 可以在响应中将 设置为 errorCodeUPNRequired ,以触发客户端使用 UPN 值重试请求(如果可用)。
  • WINHTTP_QUERY_RETRY_AFTER:服务器可以设置此标志,将客户端请求配置为在指定的延迟后重试。 此标志可用于处理超时或限制方案。