Richiedere API REST del servizio di presentazione (anteprima)

Azure Active Directory credenziali verificabili Azure AD (API REST del servizio richiesta). Questa API consente di emettere e verificare le credenziali. Questo articolo specifica l'API REST del servizio richiesta per una richiesta di presentazione. La richiesta di presentazione chiede all'utente di presentare una credenziale verificabile e quindi di verificare le credenziali.

Richiesta HTTP

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

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

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

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

Creare una richiesta HTTP POST al API REST del servizio. Sostituire con {tenantID} l'ID tenant o il nome del tenant.

https://beta.did.msidentity.com/v1.0/{tenantID}/verifiablecredentials/request

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

POST https://beta.did.msidentity.com/v1.0/contoso.onmicrosoft.com/verifiablecredentials/request
Content-Type: application/json
Authorization: Bearer  <token>

{  
    "includeQRCode": true,  
    "callback": {  
    "url": "https://www.contoso.com/api/verifier/presentationCallbac",  
    "state": "11111111-2222-2222-2222-333333333333",  
      "headers": {  
        "api-key": "an-api-key-can-go-here"  
      }  
    },  
    ...
} 

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

Tipo di autorizzazione Autorizzazione
Applicazione bbb94529-53a3-4be5-a069-7eaf2712b826/.default

Payload della richiesta di presentazione

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

{
  "includeQRCode": true,
  "callback": {
    "url": "https://www.contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for VERIFIER CALLBACK API"
    }
  },
  "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiOiJiRWo5MDY...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "presentation": {
    "includeReceipt": true,
    "requestedCredentials": [
      {
        "type": "VerifiedCredentialExpert",
        "purpose": "So we can see that you a veritable credentials expert",
        "acceptedIssuers": [
          "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiO..."
        ]
      }
    ]
  }
}

Il payload contiene le proprietà seguenti.

Parametro Tipo Descrizione
includeQRCode Boolean Determina se un codice a qr è incluso nella risposta di questa richiesta. Presentare il codice a codici a codici e chiedere all'utente di analizzarlo. L'analisi del codice a barre 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 , usare la proprietà return per eseguire il rendering di un collegamento url diretto.
authority string Identificatore decentralizzato (DID) del tenant Azure AD verificatore. Per altre informazioni, vedere Raccogliere i dettagli del tenant per configurare l'applicazione di esempio.
registration RequestRegistration Fornisce informazioni sul verificatore.
presentation RequestPresentation Fornisce informazioni sulla richiesta di presentazione delle credenziali verificabili.
callback Callback 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 sono stati restituiti all'applicazione.

Tipo RequestRegistration

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

Proprietà Type Descrizione
clientName string Nome visualizzato dell'autorità emittente della credenziale verificabile. Questo nome verrà presentato all'utente nell'app di autenticazione.

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

Screenshot che mostra come approvare la richiesta di presentazione.

Tipo RequestPresentation

Il RequestPresentation tipo fornisce le informazioni necessarie per la presentazione delle credenziali verificabili. RequestPresentation contiene le proprietà seguenti:

Proprietà Type Descrizione
includeReceipt Boolean Determina se una ricevuta deve essere inclusa nella risposta della richiesta. I valori possibili true sono 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 e non deve essere impostata per impostazione predefinita. Nella richiesta OpenId Connect SIOP la ricevuta contiene il token ID della richiesta originale.
requestedCredentials collection Raccolta di oggetti RequestCredential.

Tipo RequestCredential

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

Proprietà Type Descrizione
type string Tipo di credenziale verificabile. Deve type corrispondere al tipo definito nel manifesto delle credenziali issuer 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 Fornire informazioni sullo scopo della richiesta di questa credenziale verificabile.
acceptedIssuers raccolta di stringhe Raccolta di DID delle autorità emittente che potrebbero rilasciare il tipo di credenziale verificabile che i soggetti possono presentare. Per ottenere l'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).

Tipo di callback

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

Proprietà Type Descrizione
url string URI dell'endpoint di callback dell'applicazione.
state string Associa allo stato passato nel payload originale.
headers string Facoltativa. È possibile includere una raccolta di intestazioni HTTP richieste dall'estremità ricevente del messaggio POST. Le intestazioni devono includere solo o api-key qualsiasi intestazione necessaria per l'autorizzazione.

Risposta di esito positivo

Se ha 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 corretta:

{  
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid://vc/?request_uri=https://beta.did.msidentity.com/v1.0/87654321-0000-0000-0000-000000000000/verifiablecredentials/request/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
} 

La risposta contiene le proprietà seguenti:

Proprietà Type Descrizione
requestId string ID di correlazione rigenerato 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 è in grado di analizzare il codice a esecuzione automatica.
expiry numero intero Indica la scadenza della risposta.
qrCode string Codice a qr che l'utente può analizzare per avviare il flusso di presentazione.

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

Risposta di errore

È anche possibile restituire risposte di errore in modo che l'app possa gestirle in modo appropriato. Il codice JSON seguente mostra un messaggio di errore non autorizzato:

{
    "requestId": "fb888ac646c96083de83b099b2678de0",
    "date": "Wed, 29 Sep 2021 21:49:00 GMT",
    "error": {
        "code": "unauthorized",
        "message": "Failed to authenticate the request."
    }
}

La risposta contiene le proprietà seguenti:

Proprietà Type Descrizione
requestId string ID della richiesta rigenerata automaticamente.
date Data Ora dell'errore.
error.code string Codice di errore restituito.
error.message string Messaggio di errore.

Eventi di callback

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

Proprietà Type Descrizione
requestId string È stato eseguito il mapping alla richiesta originale quando il payload è stato pubblicato nel servizio Credenziali verificabili.
code string Codice restituito quando la richiesta è stata recuperata dall'app di autenticazione. Valori possibili:
  • request_retrieved: l'utente ha analizzato il codice a esecuzione automatica o ha selezionato il collegamento che avvia il flusso di presentazione.
  • presentation_verified: convalida delle credenziali verificabile completata.
state string Restituisce il valore dello stato passato nel payload originale.
subject string L'utente delle credenziali verificabile ha fatto.
issuers array Restituisce una matrice di credenziali verificabili richieste. Per ogni credenziale verificabile, fornisce:
  • Tipo di credenziale verificabile.
  • Attestazioni recuperate.
  • Dominio dell'autorità emittente delle credenziali verificabile.
  • Stato di convalida del dominio dell'autorità emittente delle credenziali verificabile.
  • receipt string Facoltativa. La ricevuta contiene il payload originale inviato dall'autenticatore a Credenziali verificabili.

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

    {  
        "requestId":"aef2133ba45886ce2c38974339ba1057",  
        "code":"request_retrieved",  
        "state":"Wy0ThUz1gSasAjS1"
    } 
    

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

    {
      "requestId": "87e1cb24-9096-409f-81cb-9e645f23a4ba",
      "code": "presentation_verified",
      "state": "f3d94e35-ca5f-4b1b-a7d7-a88caa05e322",
      "subject": "did:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>…",
      "issuers": [
        {
          "type": [
            "VerifiableCredential",
            "VerifiedCredentialExpert"
          ],
          "claims": {
            "firstName": "John",
            "lastName": "Doe"
          },
          "domain": "https://contoso.com/",
          "verified": "DNS",
          "issuer": "did:ion:….."
        }
      ],
      "receipt": {
        "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>"
      }
    } 
    

    Passaggi successivi

    Informazioni su come chiamare il metodo Request API REST del servizio.