Specifica della presentazione dell'API REST del servizio di richiesta

Articolo
10/07/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`	Rendere visibile il token di accesso come token di connessione nell'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. 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.

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.

{
  "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à.

Parametro	Tipo	Descrizione
`includeQRCode`	Booleano	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` o `false` (impostazione predefinita). Quando si imposta il valore su `false`, utilizzare la proprietà `url` restituisci 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. Nella richiesta `OpenId Connect SIOP` la ricevuta contiene il token ID della richiesta originale.
`authority`	stringa	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`	Richiamata	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`	raccolta	Insieme di oggetti RequestCredential.

Tipo RequestRegistration

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

Proprietà	Type	Descrizione
`clientName`	stringa	Nome visualizzato del verificatore delle credenziali verificabili. Questo nome verrà presentato all'utente nell'app di autenticazione.
`purpose`	stringa	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 proprietà clientName e il nome visualizzato dell'oggetto authority (il verificatore) nella richiesta di presentazione.

Screenshot che mostra come approvare la richiesta di presentazion.

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à:

Proprietà	Type	Descrizione
`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`	stringa	Correla l'evento di callback con lo stato passato nel payload originale.
`headers`	stringa	Facoltativo. È possibile includere una raccolta di intestazioni HTTP richieste dalla fine ricevente del messaggio POST. I valori di intestazione supportati correnti sono `api-key` o le intestazioni `Authorization`. 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	Descrizione
`type`	stringa	Tipo di credenziale verificabile. `type` deve corrispondere al tipo definito nel manifesto `issuer` 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`	stringa	Facoltativo. Fornire informazioni sullo scopo della richiesta di questa credenziale verificabile. Non viene usato dall'app Authenticator.
`acceptedIssuers`	raccolta di tipi stringa	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 raccolta `acceptedIssuers` è 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`	Booleano	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 su `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.

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.

Proprietà	Type	Descrizione
`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 tipi stringa	Set di valori che devono corrispondere al valore dell'attestazione. Se si specificano più valori, ad esempio ["rosso", "verde", "blu"] è una corrispondenza se il valore dell'attestazione nella credenziale contiene uno dei valori nella raccolta.
`contains`	stringa	Il vincolo restituisce true se il valore dell'attestazione contiene il valore specificato.
`startsWith`	stringa	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	Descrizione
`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 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:

Proprietà	Type	Descrizione
`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`	stringa	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`	stringa	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	Descrizione
`requestId`	stringa	Mappato alla richiesta originale quando il payload è stato pubblicato nel servizio Credenziali verificabili.
`requestStatus`	stringa	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`	stringa	Restituisce il valore di stato passato nel payload originale.
`subject`	stringa	Utente di credenziali verificabile DID.
`verifiedCredentialsData`	matrice	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`	stringa	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.

Condividi tramite