Compartir a través de

Detección de configuración declarada

La detección de la configuración declarada por Windows (WinDC) usa un esquema JSON dedicado para consultar los detalles de inscripción desde el punto de conexión del servicio de detección (DS). Este proceso implica el envío de solicitudes HTTP con encabezados específicos y un cuerpo JSON que contiene detalles como el dominio de usuario, el identificador de inquilino y la versión del sistema operativo. El DS responde con las direcciones URL del servicio de inscripción y las directivas de autenticación necesarias en función del tipo de inscripción (Microsoft Entra dispositivos unidos o registrados).

En este artículo se describe la estructura de esquema de los cuerpos de solicitud y respuesta HTTP y se proporcionan ejemplos para guiar la implementación.

Estructura de esquema

Encabezados de solicitud HTTP

Encabezado Obligatorio Descripción
MS-CV: %s No Vector de correlación para la inscripción
client-request-id: %s No Identificador de solicitud
Content-Type: application/json Sí Tipo de contenido HTTP

Cuerpo de la solicitud HTTP (JSON)

Campo Obligatorio Descripción
userDomain No Nombre de dominio de la cuenta inscrita
upn No Nombre principal de usuario (UPN) de la cuenta inscrita
tenantId No Identificador de inquilino de la cuenta inscrita
emmDeviceId No Identificador de dispositivo de Administración de movilidad empresarial (EMM) de la cuenta inscrita
enrollmentType Entrar unido: No
Entra registrado: Sí		 Tipo de inscripción de la cuenta inscrita.

Valores admitidos:
- Device: indica que el tipo de inscripción primaria está unido a Entra (la respuesta de DS debe especificar "AuthPolicy": "Federado").
- User: indica que el tipo de inscripción primaria es Entra registrado (la respuesta de DS debe especificar "AuthPolicy": "Certificate").
- Caso heredado (solo entra unido): si el enrollmentType parámetro no está incluido en el cuerpo de la solicitud, el dispositivo debe tratarse como Entra unido.
osVersion Sí Versión del sistema operativo en el dispositivo. El DS puede usar osVersion para determinar si la plataforma cliente admite la inscripción de WinDC. Revise las plataformas admitidas para obtener más información.

Cuerpo de la respuesta HTTP DS (JSON)

Campo Obligatorio Descripción
EnrollmentServiceUrl Sí Dirección URL del servicio de inscripción de WinDC
EnrollmentVersion No Versión de inscripción
EnrollmentPolicyServiceUrl Sí Dirección URL del servicio de directiva de inscripción
AuthenticationServiceUrl Sí Dirección URL del servicio de autenticación
ManagementResource No Recurso de administración
TouUrl No Dirección URL de los términos de uso
AuthPolicy Sí Directiva de autenticación. Valores admitidos:
- Federated (necesario para entrar unido)
- Certificate (obligatorio para Entra registrado)
errorCode No Código de error
message No Mensaje de estado

Ejemplos

Solicitud de detección

Encabezados

Content-Type: application/json

Body

  1. Enfoque de plantilla única: el cliente envía el valor de UPN en la solicitud inicial, junto con el parámetro tenantId .

    1. Microsoft Entra unidos:

      {
    "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 registrado:

      {

    "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. Sin UPN (heredado)

    1. Microsoft Entra unidos:

      {
    "userDomain" : "contoso.com",
    "emmDeviceId" : "00000000-0000-0000-0000-000000000000",
    "enrollmentType" : "Device",
    "osVersion" : "10.0.00000.0"
}

    2. Microsoft Entra registrado:

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

  3. UPN solicitado por el servidor (formato heredado). Revise el control de errores para obtener más información sobre cómo el servidor puede solicitar datos UPN si no se proporcionan en la solicitud inicial.

    1. Microsoft Entra unidos:

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

    2. Microsoft Entra registrado:

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

Respuesta de detección

Encabezados

Content-Type: application/json

Body

  1. Microsoft Entra unido (requiere "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 registrado (requiere "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

La inscripción de WinDC requiere distintos mecanismos de autenticación para Microsoft Entra dispositivos unidos y registrados. El DS de WinDC debe integrarse con el modelo de autenticación especificando el valor adecuado AuthPolicy en la respuesta de detección, en función de la enrollmentType propiedad de la solicitud.

  • Microsoft Entra dispositivos unidos usan la autenticación federada (token de dispositivo Entra).
  • Microsoft Entra dispositivos registrados usan la autenticación de certificado (certificado MDM aprovisionado para la inscripción primaria).

Reglas

  • Para Microsoft Entra dispositivos unidos:

    • Solicitud de detección: "enrollmentType": "Device"
    • Respuesta de detección: "AuthPolicy": "Federated"
    • Autenticación: el cliente usa el token de dispositivo Entra para autenticarse con el servidor de inscripción de WinDC.

  • Para los casos heredados (donde enrollmentType el valor está vacío):

    • Solicitud de detección: "enrollmentType": ""
    • Respuesta de detección: "AuthPolicy": "Federated"
    • Autenticación: el cliente usa el token de dispositivo Entra para autenticarse con el servidor de inscripción de WinDC.

  • Para Microsoft Entra dispositivos registrados:

    • Solicitud de detección: "enrollmentType": "User"
    • Respuesta de detección: "AuthPolicy": "Certificate"
    • Autenticación: el cliente usa el certificado MDM de la inscripción primaria para autenticarse con el servidor de inscripción de WinDC.

Tratamiento de errores

  • UPNRequired: si no se proporciona ningún valor UPN en la solicitud de detección, el DS puede establecer en errorCodeUPNRequired en la respuesta para desencadenar que el cliente vuelva a intentar la solicitud con un valor UPN, si está disponible.
  • WINHTTP_QUERY_RETRY_AFTER: el servidor puede establecer esta marca para configurar la solicitud de cliente para que vuelva a intentarlo después de un retraso especificado. Esta marca es útil para controlar escenarios de tiempo de espera o limitación.