Specifica della presentazione dell'API REST del servizio di richiesta

ID verificato di Microsoft Entra include l'API REST del servizio di richiesta. Questa API consente di rilasciare e verificare le credenziali. Questo articolo specifica l'API REST del servizio di richiesta per una richiesta di presentazione. La richiesta di presentazione chiede all'utente di presentare una credenziale verificabile e quindi di verificare le credenziali. Un altro articolo descrive come chiamare l'API REST del servizio di richiesta.

Richiesta HTTP

La richiesta di presentazione dell'API REST del servizio di richiesta supporta il metodo HTTP seguente:

La richiesta di presentazione dell'API REST del servizio di richiesta richiede le intestazioni HTTP seguenti:

Creare una richiesta HTTP POST all'API REST del servizio di richiesta. tenantId non è più necessario nell'URL perché è presente come attestazione in access_token.

https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest

La richiesta HTTP seguente illustra una richiesta di presentazione all'API REST del servizio di richiesta:

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Content-Type: application/json
Authorization: Bearer  <token>

{
    "callback": {
      "url": "https://contoso.com/api/verifier/presentationCallback",
      "state": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

Per chiamare l'API REST del servizio di richiesta, è necessaria l'autorizzazione seguente. Per altre informazioni, vedere Concedere le autorizzazioni per ottenere i token di accesso.

Payload della richiesta di presentazione

Il payload della richiesta di presentazione contiene informazioni sulla richiesta di presentazione delle credenziali verificabili. Nell'esempio seguente viene illustrata una richiesta di presentazione da un'autorità emittente specifica. Il risultato di questa richiesta restituisce un codice a matrice con un collegamento per avviare il processo di presentazione.

{
  "authority": "did:web:verifiedid.contoso.com",
  "includeReceipt": true,
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:web:verifiedid.contoso.com"
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

Il payload contiene le seguenti proprietà.

Tipo RequestRegistration

Il tipo RequestRegistration fornisce la registrazione delle informazioni per l'emittente. Il tipo RequestRegistration contiene le seguenti proprietà:

Lo screenshot seguente mostra la proprietà clientName e il nome visualizzato dell'oggetto authority (il verificatore) nella richiesta di presentazione.

Tipo di callback

L'API REST del servizio di richiesta genera diversi eventi all'endpoint di callback. Questi eventi consentono di aggiornare l'interfaccia utente e continuare il processo dopo che i risultati vengono restituiti all'applicazione. Il tipo Callback contiene le seguenti proprietà:

Tipo RequestCredential

RequestCredential fornisce informazioni sulle credenziali richieste che l'utente deve fornire. RequestCredential contiene le proprietà seguenti:

Tipo configuration.validation

Configuration.Validation fornisce informazioni sulla modalità di convalida delle credenziali presentate. Contiene le seguenti proprietà:

Tipi di vincolo

Il tipo constraints contiene una raccolta di vincoli di attestazione che devono essere soddisfatti quando un portafoglio seleziona le credenziali candidate. Ciò consente di richiedere credenziali con un valore di attestazione specifico. I vincoli specificati useranno la logica E, ad esempio se si specificano tre vincoli, tutti devono essere soddisfatti. Per ogni vincolo nella raccolta, è necessario selezionare un operando di valori, contiene o startsWith. I valori non possono essere espressioni regolari. Tutte le operazioni di confronto non fanno distinzione tra maiuscole e minuscole.

tipo faceCheck

Il tipo faceCheck contiene informazioni per l'esecuzione del controllo dell'attività durante la presentazione di una credenziale. Le credenziali richieste devono contenere una foto del titolare nell'attestazione denominata da sourcePhotoClaimName. La presentazione avrà esito positivo se il controllo di attività raggiunge un livello di confidenza uguale o maggiore a quello specificato nella proprietà matchConfidenceThreshold. Se la soglia non viene raggiunta, l'intera presentazione avrà esito negativo.

Risposta con esito positivo

In caso di esito positivo, questo metodo restituisce un codice di risposta (HTTP 201 Creato) e una raccolta di oggetti evento nel corpo della risposta. Il codice JSON seguente illustra una risposta riuscita:

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid-vc://?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/presentationRequests/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

La risposta contiene le proprietà seguenti:

Quando l'app riceve la risposta, l'app deve presentare il codice a matrice all'utente. L'utente analizza il codice a matrice, che apre l'app di autenticazione e avvia il processo di presentazione.

Risposta con errore

Se si verifica un errore con la richiesta, viene restituita una risposta di errore e deve essere gestita in modo appropriato dall'app.

Eventi di callback

L'endpoint di callback viene chiamato quando un utente analizza il codice a matrice, usa il collegamento diretto all'app di autenticazione o termina il processo di presentazione.

L'esempio seguente illustra un payload di callback quando l'app di autenticazione avvia la richiesta di presentazione:

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "requestStatus":"request_retrieved",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58"
}

L'esempio seguente illustra un payload di callback dopo il completamento della presentazione delle credenziali verificabili:

{
  "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
  "requestStatus": "presentation_verified",
  "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
  "subject": "did:web:verifiedid.contoso.com",
  "verifiedCredentialsData": [
    {
      "issuer": "did:web:issuer...",
      "type": [
        "VerifiableCredential",
        "VerifiedCredentialExpert"
      ],
      "claims": {
        "firstName": "Megan",
        "lastName": "Bowen"
      },
      "credentialState": {
        "revocationStatus": "VALID"
      },
      "domainValidation": {
        "url": "https://contoso.com/"
      },
      "issuanceDate": "yyyy-MM-ddTHH:mm:ssZ",
      "expirationDate": "yyyy-MM-ddTHH:mm:ssZ"
    }
  ],
  "receipt": {
    "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
    "vp_token": "...",
    "state": "..."
  }
}

Passaggi successivi

Informazioni su come chiamare l'API REST del servizio di richiesta.