Specifica di rilascio dell'API REST del servizio di richiesta

Articolo
02/26/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 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 saltproprietà , alge 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: `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 `error` proprietà .
`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.

Share via