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 |
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.
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>
{
"includeQRCode": true,
"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.
{
"includeQRCode": false,
"callback": {
"url": "https://contoso.com/api/issuer/issuanceCallback",
"state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
"headers": {
"api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
}
},
"authority": "did:web:verifiedid.contoso.com",
"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 |
Boolean | 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 (impostazione predefinita) o false . Quando si imposta il valore su false , utilizzare la proprietà return url per eseguire il rendering di un collegamento diretto. |
callback |
Callback | 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 |
string | 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 |
string | 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 |
string | 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 |
string | 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 |
SPILLA | 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 |
string | 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 RequestRegistration
tipo fornisce la registrazione delle informazioni per l'emittente. Il RequestRegistration
tipo contiene le proprietà seguenti:
Proprietà | Type | Descrzione |
---|---|---|
clientName |
stringa | Nome visualizzato dell'autorità emittente della credenziale verificabile. |
logoUrl |
string | Facoltativo. URL del logo dell'autorità di certificazione. |
termsOfServiceUrl |
string | Facoltativo. URL per le condizioni per l'utilizzo delle credenziali verificabili rilasciate. |
Nota
Al momento, le RequestRegistration
informazioni 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 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. Formati accettati IPv4, IPv6 o DNS resolveable hostname |
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 di pin
Il pin
tipo 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 salt
proprietà , alg
e iterations
. pin
contiene le proprietà seguenti:
Proprietà | Type | Descrzione |
---|---|---|
value |
stringa | Contiene il valore del PIN in testo normale. Quando si usa un PIN con hash, la proprietà value contiene l'hash salted, con codifica Base64. |
type |
string | Tipo di codice PIN. Valore possibile: numeric (impostazione predefinita). |
length |
integer | Lunghezza del codice PIN. La lunghezza predefinita è 6, il minimo è 4 e il massimo è 16. |
salt |
string | Salt del codice PIN con hash. Il salt viene anteporto durante il calcolo hash. Codifica: UTF-8. |
alg |
string | Algoritmo hash per il PIN con hash. Algoritmo supportato: sha256 . |
iterations |
integer | Numero di iterazioni hash. Valore possibile: 1 . |
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": "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 | Descrzione |
---|---|---|
requestId |
stringa | ID richiesta generato automaticamente. Il callback usa la stessa richiesta, consentendo di tenere traccia della richiesta di rilascio e dei relativi callback. |
url |
string | 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 |
string | 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 callback 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 | Descrzione |
---|---|---|
requestId |
stringa | Mappato alla richiesta originale quando il payload è stato pubblicato nel servizio Credenziali verificabili. |
requestStatus |
string | Stato restituito per la richiesta. Valori possibili:
|
state |
string | Restituisce il valore di stato passato nel payload originale. |
error |
Errore | Quando il valore della code proprietà è issuance_error , questa proprietà contiene informazioni sull'errore. |
error.code |
string | Codice di errore restituito. |
error.message |
string | Messaggio di errore. |
L'esempio seguente illustra un payload di callback 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 callback 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 callback
L'endpoint di callback potrebbe essere chiamato con un messaggio di errore. Nella tabella seguente sono elencati i codici di errore:
Message | 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 callback 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.
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per