Individuazione della configurazione dichiarata

• Si applica a:

  ✅ Windows 11, ✅ Windows 10

L'individuazione della configurazione dichiarata da Windows (WinDC) usa uno schema JSON dedicato per eseguire query sui dettagli della registrazione dall'endpoint del servizio di individuazione (DS). Questo processo prevede l'invio di richieste HTTP con intestazioni specifiche e un corpo JSON contenente dettagli quali dominio utente, ID tenant e versione del sistema operativo. Il servizio DS risponde con gli URL del servizio di registrazione e i criteri di autenticazione necessari in base al tipo di registrazione (Microsoft Entra dispositivi aggiunti o registrati).

Questo articolo descrive la struttura dello schema per i corpi di richiesta e risposta HTTP e fornisce esempi per guidare l'implementazione.

Struttura dello schema

Intestazioni della richiesta HTTP

Intestazione	Obbligatorio	Descrizione
MS-CV: %s	No	Vettore di correlazione per la registrazione
client-request-id: %s	No	ID richiesta
Content-Type: application/json	Sì	Tipo di contenuto HTTP

Corpo della richiesta HTTP (JSON)

Campo	Obbligatorio	Descrizione
userDomain	No	Nome di dominio dell'account registrato
upn	No	Nome entità utente (UPN) dell'account registrato
tenantId	No	ID tenant dell'account registrato
emmDeviceId	No	ID dispositivo EMM (Enterprise Mobility Management) dell'account registrato
enrollmentType	Entra aggiunto: No Entra registrato: Sì	Tipo di registrazione dell'account registrato. Valori supportati: - Device: indica che il tipo di registrazione padre è entrante (la risposta DS deve specificare "AuthPolicy": "Federated"). - User: indica che il tipo di registrazione padre è Entra registered (la risposta DS deve specificare "AuthPolicy": "Certificate"). - Caso legacy (solo entra aggiunto): se il enrollmentType parametro non è incluso nel corpo della richiesta, il dispositivo deve essere considerato come aggiunto a Entra.
osVersion	Sì	Versione del sistema operativo nel dispositivo. Il DS può usare osVersion per determinare se la piattaforma client supporta la registrazione WinDC. Per informazioni dettagliate, vedere le piattaforme supportate .

Corpo della risposta HTTP DS (JSON)

Campo	Obbligatorio	Descrizione
EnrollmentServiceUrl	Sì	URL del servizio di registrazione WinDC
EnrollmentVersion	No	Versione di registrazione
EnrollmentPolicyServiceUrl	Sì	URL del servizio criteri di registrazione
AuthenticationServiceUrl	Sì	URL del servizio di autenticazione
ManagementResource	No	Risorsa di gestione
TouUrl	No	URL delle condizioni per l'utilizzo
AuthPolicy	Sì	Criteri di autenticazione. Valori supportati: - Federated (obbligatorio per entra a far parte) - Certificate (obbligatorio per Entra registrato)
errorCode	No	Codice di errore
message	No	Messaggio di stato

Esempi

Richiesta di individuazione

Intestazioni

Content-Type: application/json

Corpo

1. Approccio basato su modello singolo: il client invia il valore UPN nella richiesta iniziale, insieme al parametro tenantId .

   1. Microsoft Entra aggiunto:

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

      {
      
          "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. Nessun UPN (legacy)

   1. Microsoft Entra aggiunto:

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

   2. Microsoft Entra registrati:

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

3. UPN richiesto dal server (formato legacy). Esaminare la gestione degli errori per informazioni dettagliate su come il server può richiedere i dati UPN se non vengono forniti nella richiesta iniziale.

   1. Microsoft Entra aggiunto:

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

   2. Microsoft Entra registrati:

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

Risposta di individuazione

Intestazioni

Content-Type: application/json

Corpo

1. Microsoft Entra aggiunto (richiede "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 registrato (richiede "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 registrazione WinDC richiede meccanismi di autenticazione diversi per Microsoft Entra dispositivi aggiunti e registrati. Il servizio DS WinDC deve integrarsi con il modello di autenticazione specificando il valore appropriato AuthPolicy nella risposta di individuazione, in base alla enrollmentType proprietà della richiesta.

• Microsoft Entra dispositivi aggiunti usano l'autenticazione federata (token del dispositivo Entra).
• Microsoft Entra dispositivi registrati usano l'autenticazione del certificato (certificato MDM di cui è stato effettuato il provisioning per la registrazione padre).

Regole

• Per Microsoft Entra dispositivi aggiunti:

  • Richiesta di individuazione: "enrollmentType": "Device"
  • Risposta di individuazione: "AuthPolicy": "Federated"
  • Autenticazione: il client usa il token del dispositivo Entra per eseguire l'autenticazione con il server di registrazione WinDC.

• Per i casi legacy (dove il valore è vuoto):For legacy cases (where enrollmentType value is empty):

  • Richiesta di individuazione: "enrollmentType": ""
  • Risposta di individuazione: "AuthPolicy": "Federated"
  • Autenticazione: il client usa il token del dispositivo Entra per eseguire l'autenticazione con il server di registrazione WinDC.

• Per Microsoft Entra dispositivi registrati:

  • Richiesta di individuazione: "enrollmentType": "User"
  • Risposta di individuazione: "AuthPolicy": "Certificate"
  • Autenticazione: il client usa il certificato MDM della registrazione padre per eseguire l'autenticazione con il server di registrazione WinDC.

Gestione degli errori

• UPNRequired: se nella richiesta di individuazione non viene specificato alcun valore UPN, il servizio di configurazione può impostare su errorCodeUPNRequired nella risposta per attivare il client per ritentare la richiesta con un valore UPN, se disponibile.
• WINHTTP_QUERY_RETRY_AFTER: il server può impostare questo flag per configurare la richiesta client per riprovare dopo un ritardo specificato. Questo flag è utile per gestire scenari di timeout o limitazione delle richieste.