Specifica della presentazione dell'API REST del servizio di richiesta

Articolo
02/06/2024

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:

metodo	Note
POST	Con il payload JSON come specificato in questo articolo.

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

metodo	Valore
`Authorization`	Collegare il token di accesso come token di connessione all'intestazione di autorizzazione in una richiesta HTTP. Ad esempio: `Authorization: Bearer <token>`.
`Content-Type`	`Application/json`

Creare una richiesta HTTP POST all'API REST del servizio di richiesta. Non tenantId è 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>

{
    "includeQRCode": true,
    "callback": {
      "url": "https://contoso.com/api/verifier/presentationCallback",
      "state": "11111111-2222-2222-2222-333333333333",
      "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.

Tipo di autorizzazione	Autorizzazione
Applicazione	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

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.

{
  "includeQRCode": true,
  "includeReceipt": true,
  "authority": "did:web:verifiedid.contoso.com",
  "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 proprietà seguenti.

Parametro	Tipo	Descrizione
`includeQRCode`	Boolean	Facoltativo. Determina se un codice a matrice è incluso nella risposta di questa richiesta. Presentare il codice a matrice e chiedere all'utente di analizzarlo. La scansione del codice a matrice avvia l'app di autenticazione con questa richiesta di presentazione. I valori possibili sono `true` (impostazione predefinita) o `false`. Quando si imposta il valore su `false`, utilizzare la proprietà return `url` per eseguire il rendering di un collegamento diretto.
`includeReceipt`	Booleano	Facoltativo. Determina se una ricevuta deve essere inclusa nella risposta di questa richiesta. I valori possibili sono `true` o `false` (impostazione predefinita). La ricevuta contiene il payload originale inviato dall'autenticatore al servizio Credenziali verificabili. La ricevuta è utile per la risoluzione dei problemi o se si ha la necessità di ge i dettagli completi del payload. In caso contrario, non è necessario impostare questo valore su `true` per impostazione predefinita. `OpenId Connect SIOP` Nella richiesta la ricevuta contiene il token ID della richiesta originale.
`authority`	string	Identificatore decentralizzato (DID) del tenant microsoft Entra del verificatore. Per altre informazioni, vedere Raccogliere i dettagli del tenant per configurare l'applicazione di esempio.
`registration`	RequestRegistration	Fornisce informazioni sul verificatore.
`callback`	Callback	Obbligatorio. Consente allo sviluppatore di aggiornare l'interfaccia utente durante il processo di presentazione delle credenziali verificabili. Quando l'utente completa il processo, continuare il processo dopo che i risultati vengono restituiti all'applicazione.
`requestedCredentials`	collection	Insieme di oggetti RequestCredential .

Tipo RequestRegistration

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

Proprietà	Type	Descrzione
`clientName`	stringa	Nome visualizzato del verificatore delle credenziali verificabili. Questo nome verrà presentato all'utente nell'app di autenticazione.
`purpose`	string	Facoltativo. Stringa visualizzata per informare l'utente del motivo per cui vengono richieste le credenziali verificabili.
`logoUrl`	URL	Facoltativo. URL per un tipo di logo del verificatore. Non viene usato dall'app Authenticator.
`termsOfServiceUrl`	URL	Facoltativo. URL delle condizioni per il servizio per il verificatore. Non viene usato dall'app Authenticator.

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

Screenshot che mostra come approvare la 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 Callback tipo contiene le proprietà seguenti:

Proprietà	Type	Descrzione
`url`	stringa	URI all'endpoint di callback dell'applicazione. L'URI deve puntare a un endpoint raggiungibile su Internet; in caso contrario, il servizio genererà un errore illeggibile dell'URL di callback. Input accettati IPv4, IPv6 o NOME host risolvibile DNS.
`state`	string	Correla l'evento di callback con lo stato passato nel payload originale.
`headers`	string	Facoltativo. È possibile includere una raccolta di intestazioni HTTP richieste dalla fine ricevente del messaggio POST. I valori di intestazione supportati correnti sono o `api-key` le `Authorization` intestazioni. Qualsiasi altra intestazione genererà un errore di intestazione callback non valido.

Tipo RequestCredential

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

Proprietà	Type	Descrzione
`type`	stringa	Tipo di credenziale verificabile. Deve `type` corrispondere al tipo definito nel `issuer` manifesto delle credenziali verificabili, ad esempio `VerifiedCredentialExpert`. Per ottenere il manifesto dell'autorità emittente, vedere Raccogliere le credenziali e i dettagli dell'ambiente per configurare l'applicazione di esempio. Copiare l'URL delle credenziali del problema, aprirlo in un Web browser e controllare la proprietà ID.
`purpose`	string	Facoltativo. Fornire informazioni sullo scopo della richiesta di questa credenziale verificabile. Non viene usato dall'app Authenticator.
`acceptedIssuers`	raccolta di stringhe	Facoltativo. Raccolta di ID di autorità emittenti che potrebbero emettere il tipo di credenziale verificabile che gli interessati possono presentare. Per ottenere l'autorità emittente DID, vedere Raccogliere le credenziali e i dettagli dell'ambiente per configurare l'applicazione di esempio e copiare il valore dell'identificatore decentralizzato (DID). Se la `acceptedIssuers` raccolta è vuota o non presente, la richiesta di presentazione accetterà un tipo di credenziale emesso da qualsiasi autorità emittente.
`configuration.validation`	Configuration.Validation	Impostazioni facoltative per la convalida della presentazione.
`constraints`	Vincoli	Facoltativo. Raccolta di vincoli di attestazioni.

Tipo configuration.validation

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

Proprietà	Type	Descrizione
`allowRevoked`	Boolean	Facoltativo. Determina se devono essere accettate credenziali revocate. Il valore predefinito è `false` (non deve essere accettato).
`validateLinkedDomain`	Booleano	Facoltativo. Determina se il dominio collegato deve essere convalidato. Il valore predefinito è `false`. L'impostazione di questo flag `false` significa che l'applicazione relying party accetta le credenziali da un dominio collegato non verificato. L'impostazione di questo flag su `true` indica che il dominio collegato verrà convalidato e verranno accettati solo i domini verificati.
`faceCheck`	faceCheck	Facoltativo. Consente di richiedere un controllo di attività durante la presentazione.

Tipo di vincoli

Il constraints tipo 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 AND, 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. Tutti i confronti non fanno distinzione tra maiuscole e minuscole.

Proprietà	Type	Descrzione
`claimName`	stringa	Obbligatorio. Nome dell'attestazione per il vincolo. Si tratta del nome dell'attestazione nella credenziale verificabile. Vedere outputClaim nel tipo claimMapping.
`values`	raccolta di stringhe	Set di valori che devono corrispondere al valore dell'attestazione. Se si specificano più valori, ad esempio ["red", "green", "blue"] è una corrispondenza se il valore dell'attestazione nella credenziale contiene uno dei valori nella raccolta.
`contains`	string	Il vincolo restituisce true se il valore dell'attestazione contiene il valore specificato.
`startsWith`	string	Il vincolo restituisce true se il valore dell'attestazione inizia con il valore specificato.

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.

Proprietà	Type	Descrzione
`sourcePhotoClaimName`	stringa	Obbligatorio. Nome dell'attestazione nella credenziale che contiene la foto. Vedere outputClaim nel tipo claimMapping.
`matchConfidenceThreshold`	integer	Facoltativo. Soglia riservata per un controllo riuscito tra la foto e i dati di liveness. Deve essere un numero intero compreso tra 50 e 100. Il valore predefinito è 70.

Risposta riuscita

In caso di esito positivo, questo metodo restituisce un codice di risposta (HTTP 201 Created) 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/12345678-0000-0000-0000-000000000000/verifiableCredentials/presentationRequests/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

La risposta contiene le proprietà seguenti:

Proprietà	Type	Descrzione
`requestId`	stringa	ID richiesta generato automaticamente. Il callback usa la stessa richiesta, consentendo di tenere traccia della richiesta di presentazione e dei relativi callback.
`url`	string	URL che avvia l'app di autenticazione e avvia il processo di presentazione. È possibile presentare questo URL all'utente se non riesce a eseguire la scansione del codice a matrice.
`expiry`	integer	Indica quando la risposta scadrà.
`qrCode`	string	Codice a matrice che l'utente può analizzare per avviare il flusso di presentazione.

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.

Proprietà	Type	Descrzione
`requestId`	stringa	Mappato alla richiesta originale quando il payload è stato pubblicato nel servizio Credenziali verificabili.
`requestStatus`	string	Stato restituito quando la richiesta è stata recuperata dall'app di autenticazione. Valori possibili: `request_retrieved`: l'utente ha analizzato il codice a matrice o ha selezionato il collegamento che avvia il flusso di presentazione. `presentation_verified`: la convalida delle credenziali verificabile è stata completata correttamente. li>`presentation_error`: Si è verificato un errore nella presentazione.
`state`	string	Restituisce il valore di stato passato nel payload originale.
`subject`	string	Utente di credenziali verificabile DID.
`verifiedCredentialsData`	array	Restituisce una matrice di credenziali verificabili richieste. Per ogni credenziale verificabile, fornisce: Tipi di credenziali verificabili. DID dell'autorità emittente Attestazioni recuperate. Dominio dell'autorità emittente di credenziali verificabile. Stato di convalida del dominio dell'autorità di certificazione delle credenziali verificabile.
`receipt`	string	Facoltativo. La ricevuta contiene il payload originale inviato dal portafoglio al servizio Credenziali verificabili. La ricevuta deve essere usata solo per la risoluzione dei problemi o il debug. Il formato nella ricevuta non è corretto e può cambiare in base al portafoglio e alla versione usata.

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.