Leggere in inglese

Condividi tramite


Specifica di rilascio 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 rilascio. Un altro articolo descrive come chiamare l'API REST del servizio di richiesta.

Richiesta HTTP

La richiesta di rilascio 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 rilascio dell'API REST del servizio di richiesta richiede le intestazioni HTTP seguenti:

Nome 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.

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

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

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

{
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "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 rilascio

Il payload della richiesta di rilascio contiene informazioni sulla richiesta di rilascio delle credenziali verificabili. L'esempio seguente illustra una richiesta di rilascio usando un flusso di codice PIN con attestazioni utente, ad esempio nome e cognome. Il risultato di questa richiesta restituisce un codice a matrice con un collegamento per avviare il processo di rilascio.

{
  "authority": "did:web:verifiedid.contoso.com",
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

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 rilascio. 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.
callback Richiamata Obbligatorio. Consente allo sviluppatore di ottenere informazioni in modo asincrono sul flusso durante il processo di rilascio delle credenziali verificabile. Ad esempio, lo sviluppatore potrebbe volere una chiamata quando l'utente ha analizzato il codice a matrice o se la richiesta di rilascio ha esito positivo o negativo.
authority stringa Identificatore decentralizzato (DID) dell'autorità emittente. Per altre informazioni, vedere Raccogliere le credenziali e i dettagli dell'ambiente per configurare l'applicazione di esempio.
registration RequestRegistration Fornisce informazioni sull'autorità emittente che può essere visualizzata nell'app di autenticazione.
type stringa Tipo di credenziale verificabile. Deve corrispondere al tipo definito nel manifesto delle credenziali verificabile. Ad esempio: VerifiedCredentialExpert. Per altre informazioni, vedere Creare la scheda di esperti di credenziali verificata in Azure.
manifest stringa URL del documento manifesto delle credenziali verificabile. Per altre informazioni, vedere Raccogliere le credenziali e i dettagli dell'ambiente per configurare l'applicazione di esempio.
claims stringa Facoltativo. Può essere usato solo per il flusso di attestazione dell'hint del token ID per includere una raccolta di asserzioni eseguite sull'oggetto nella credenziale verificabile.
pin PIN Facoltativo. Il codice PIN può essere usato solo con il flusso di attestazione dell'hint del token ID. Un numero di PIN per fornire maggiore sicurezza durante il rilascio. Si genera un codice PIN e lo si presenta all'utente nell'app. L'utente deve fornire il codice PIN generato.
expirationDate stringa Facoltativo. ExpirationDate può essere usato solo con il flusso di attestazione dell'hint del token ID. Se specificato, il valore deve essere una data espressa nel formato ISO8601. La data sostituirà validityInterval nella definizione delle regole delle credenziali per questa richiesta di rilascio. Usare questa impostazione per controllare in modo esplicito quando una credenziale scade, ad esempio la fine del giorno, la fine del mese o la fine dell'anno, indipendentemente dal momento in cui viene rilasciata. Si noti che la data è espressa in formato UTC. Se si specifica la fine dell'anno, con l'ora impostata su 23:59:59, ovvero da 1 secondo a mezzanotte nell'ora UTC. Qualsiasi utente in un fuso orario diverso otterrà la data di scadenza presentata nel fuso orario locale in Microsoft Authenticator. Ciò significa che se ci si trova nel fuso orario CET, verrà presentato il 1° gennaio 1:00.

Il contratto credenziali deve avere il flag allowOverrideValidityOnIssuance impostato su true.

Attualmente sono disponibili quattro tipi di attestazione delle attestazioni che è possibile inviare nel payload. ID verificato di Microsoft Entra usa quattro modi per inserire attestazioni in una credenziale verificabile e attestare tali informazioni con il DID dell'autorità emittente. Di seguito sono riportati i quattro tipi:

  • Token ID
  • Suggerimento per il token ID
  • Credenziali verificabili tramite una presentazione verificabile
  • Attestazioni autocertificate

È possibile trovare informazioni dettagliate sui tipi di input in Personalizzazione delle credenziali verificabili.

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 dell'autorità emittente della credenziale verificabile.
logoUrl stringa Facoltativo. URL del logo dell'autorità di certificazione.
termsOfServiceUrl stringa Facoltativo. URL per le condizioni per l'utilizzo delle credenziali verificabili rilasciate.

Nota

Al momento, le informazioni RequestRegistration non vengono presentate durante il rilascio nell'app Microsoft Authenticator. Queste informazioni, tuttavia, possono essere usate nel payload.

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 richiamata. Formati accettati IPv4, IPv6 o DNS risolvibili con nome host. Per rafforzare la protezione avanzata della rete, vedere Domande frequenti.
state string 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 di richiamata non valido

Tipo di segnaposto

Il tipo pin definisce un codice PIN che può essere visualizzato come parte del rilascio. pin è facoltativo e, se usato, deve sempre essere inviato fuori banda. Quando si usa un codice PIN HASH, è necessario definire le proprietà salt, alg e iterations. pin contiene le proprietà seguenti:

Proprietà Type Descrizione
value stringa Contiene il valore del PIN in testo normale. Quando si usa un PIN con hash, la proprietà valore contiene l'hash salted, con codifica Base64.
type stringa Tipo di codice PIN. Valore possibile: numeric (impostazione predefinita).
length integer Lunghezza del codice PIN. La durata predefinita è 6, il valore minimo è 4 e il valore massimo è 16.
salt stringa Salt del codice PIN con hash. Il salt viene anteposto durante il calcolo hash. Codifica: UTF-8.
alg stringa Algoritmo hash per il PIN con hash. Algoritmi supportati: sha256.
iterations integer Numero di iterazioni hash. Valore possibile: 1.

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": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "qrCode": "data:image/png;base64,iVBORw0KggoA<SNIP>"  
} 

La risposta contiene le proprietà seguenti:

Proprietà Type Descrizione
requestId stringa ID richiesta generato automaticamente. La richiamata usa la stessa richiesta, consentendo di tenere traccia della richiesta di rilascio e delle relative richiamate.
url stringa URL che avvia l'app di autenticazione e avvia il processo di rilascio. È 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 rilascio.

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 rilascio.

Risposta con errore

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

Eventi di callback

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

Proprietà Type Descrizione
requestId stringa Mappato alla richiesta originale quando il payload è stato pubblicato nel servizio Credenziali verificabili.
requestStatus stringa Stato restituito per la richiesta. Valori possibili:
  • request_retrieved: l'utente ha analizzato il codice a matrice o ha selezionato il collegamento che avvia il flusso di rilascio.
  • issuance_successful: il rilascio delle credenziali verificabili è riuscito.
  • issuance_error: si è verificato un errore durante il rilascio. Per informazioni dettagliate, vedere la proprietà error.
state stringa Restituisce il valore di stato passato nel payload originale.
error errore Quando il valore della proprietà code è issuance_error, questa proprietà contiene informazioni sull'errore.
error.code stringa Codice di errore restituito.
error.message stringa Messaggio di errore.

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

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"request_retrieved",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
} 

L'esempio seguente illustra un payload di richiamata dopo che l'utente ha completato correttamente il processo di rilascio:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"issuance_successful",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
} 

Errori di richiamata

L'endpoint di richiamata potrebbe essere chiamato con un messaggio di errore. Nella seguente tabella vengono elencati i codici di errore:

Messaggio Definizione
fetch_contract_error Impossibile recuperare il contratto di credenziali verificabile. Questo errore si verifica in genere quando l'API non riesce a recuperare il manifesto specificato nell'oggetto RequestIssuance del payload della richiesta.
issuance_service_error Il servizio Credenziali verificabili non è in grado di convalidare i requisiti o si è verificato un problema in Credenziali verificabili.
unspecified_error Questo errore non è comune, ma vale la pena di indagare.

L'esempio seguente illustra un payload di richiamata quando si è verificato un errore:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus": "issuance_error",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",  
    "error": { 
      "code":"IssuanceFlowFailed", 
      "message":"issuance_service_error”, 
    } 
} 

Passaggi successivi

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