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.
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 |
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.
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.
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 |
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 . |
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.
Se si verifica un errore con la richiesta, verrà restituita una risposta di errore e deve essere gestita in modo appropriato dall'app.
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:
|
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"
}
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”,
}
}
Informazioni su come chiamare l'API REST del servizio di richiesta.