Condividi tramite

Individuazione della configurazione dichiarata

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 Microsoft Entra aggiunto: No
Microsoft Entra registrato: Sì		 Tipo di registrazione dell'account registrato.

Valori supportati:
- Device: indica che il tipo di registrazione padre è Microsoft Entra aggiunto (la risposta DS deve specificare "AuthPolicy": "Federated").
- User: indica che il tipo di registrazione padre è Microsoft Entra registrato (la risposta DS deve specificare "AuthPolicy": "Certificate").
- Caso legacy (solo Microsoft Entra aggiunto): se il enrollmentType parametro non è incluso nel corpo della richiesta, il dispositivo deve essere considerato come Microsoft Entra aggiunto.
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 Microsoft Entra aggiunto)
- Certificate(obbligatorio per Microsoft 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 (Microsoft Entra token del dispositivo).
  • 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 Microsoft Entra per 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 Microsoft Entra per 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.
  • Last updated on