API di amministrazione delle credenziali verificabili
L'API ID verificato di Microsoft Entra Amministrazione consente di gestire tutti gli aspetti del servizio credenziali verificabili. Offre un modo per configurare un nuovo servizio, gestire e creare contratti di credenziali verificabili, revocare credenziali verificabili e rifiutare completamente il servizio.
L'API è destinata agli sviluppatori che hanno familiarità con le API RESTful e autorizzazioni sufficienti per il tenant di Microsoft Entra per abilitare il servizio
URL di base
L'API Amministrazione è server su HTTPS. Tutti gli URL a cui si fa riferimento nella documentazione hanno la base seguente: https://verifiedid.did.msidentity.com.
Autenticazione
L'API è protetta tramite Microsoft Entra ID e usa token di connessione OAuth2. Il token di accesso può essere per un utente o per un'applicazione.
Token di connessione utente
La registrazione dell'app deve avere l'autorizzazione API per Verifiable Credentials Service Admin e quindi quando si acquisisce il token di accesso l'app deve usare l'ambito 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access. Il token di accesso deve essere per un utente con l'amministratore globale o il ruolo di amministratore dei criteri di autenticazione. Un utente con ruolo lettore globale può eseguire chiamate API di sola lettura.
Token di connessione dell'applicazione
Il Verifiable Credentials Service Admin servizio supporta le autorizzazioni dell'applicazione seguenti.
| Autorizzazione | Descrizione |
|---|---|
| VerifiableCredential.Authority.ReadWrite | Autorizzazione per oggetti autorità di lettura/scrittura |
| VerifiableCredential.Contract.ReadWrite | Autorizzazione per oggetti contratto di lettura/scrittura |
| VerificabileCredential.Credential.Search | Autorizzazione per la ricerca di credenziali da revocare |
| VerificabileCredential.Credential.Revoke | Autorizzazione per revocare una credenziale rilasciata in precedenza |
| VerifiableCredential.Network.Read | Autorizzazione per leggere le voci dalla rete ID verificato |
La registrazione dell'app deve avere l'autorizzazione API per Verifiable Credentials Service Admin e le autorizzazioni necessarie dalla tabella precedente. Quando si acquisisce il token di accesso, tramite il flusso delle credenziali client, l'app deve usare l'ambito 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default.
Se l'app intende creare una nuova autorità, è necessario due elementi. Prima di tutto, la registrazione dell'app richiede l'autorizzazione VerifiableCredential.Authority.ReadWrite . In secondo luogo, l'app deve disporre Create Key dell'autorizzazione nei criteri di accesso di Key Vault. Se l'app legge/scrive solo le autorità esistenti, non è necessaria l'autorizzazione Key Vault.
Onboarding
Questa API consente di creare un nuovo ambiente in modo che sia possibile configurare nuove autorità. Questo può essere attivato manualmente passando alla pagina Credenziali verificabili anche nel portale di Azure. È necessario chiamare questa API una sola volta e solo se si vuole configurare un nuovo ambiente solo con l'API.
Richiesta HTTP
POST /v1.0/verifiableCredentials/onboard
Usare questo endpoint per completare il provisioning del servizio Credenziali verificabili nel tenant. Il sistema crea il resto delle entità servizio se non ne viene ancora eseguito il provisioning.
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo.
Messaggio restituito
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "f5bf2fc6-7135-4d94-a6fe-c26e4543bc5a",
"verifiableCredentialServicePrincipalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
"verifiableCredentialRequestServicePrincipalId": "bbbbbbbb-cccc-dddd-2222-333333333333",
"verifiableCredentialAdminServicePrincipalId": "cccccccc-dddd-eeee-3333-444444444444",
"status": "Enabled"
}
Chiamando ripetutamente questa API, viene restituito esattamente lo stesso messaggio restituito.
Autorità
Questo endpoint può essere usato per creare o aggiornare un'istanza del servizio credenziali verificabile.
Metodi
| Metodi | Tipo restituito | Descrizione |
|---|---|---|
| Ottenere l'autorità | Autorità | Leggere le proprietà di un'autorità |
| Autorità elenco | Matrice di autorità | Ottenere un elenco di tutti i servizi di credenziali verificabili/autorità configurate |
| Crea autorità | Autorità | Creare una nuova autorità |
| Autorità di aggiornamento | Autorità | Autorità di aggiornamento |
| Eliminare l'autorità | Autorità | Eliminare l'autorità |
| Generare una configurazione DID nota | ||
| Generare un documento DID | ||
| Convalidare la configurazione DID nota | ||
| Ruota chiave di firma | Autorità | Ruotare la chiave di firma |
| Eseguire la sincronizzazione con il documento DID | Autorità | Sincronizzare il documento DID con la nuova chiave di firma |
Ottenere l'autorità
Recuperare le proprietà di un'autorità configurata o di un'istanza del servizio credenziali verificabile.
Richiesta HTTP
GET /v1.0/verifiableCredentials/authorities/:authorityId
Sostituire con :authorityId il valore di una delle autorità configurate.
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo
Messaggio di risposta
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "ffea7eb3-0000-1111-2222-000000000000",
"name": "ExampleAuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
La risposta contiene le proprietà seguenti.
Tipo di autorità
| Proprietà | Type | Descrzione |
|---|---|---|
Id |
stringa | ID univoco generato automaticamente, che può essere usato per recuperare o aggiornare l'istanza specifica del servizio credenziali verificabile |
name |
string | Nome descrittivo di questa istanza del servizio credenziali verificabile |
status |
string | stato del servizio, questo valore sarà sempre enabled |
| didModel | didModel | Informazioni su DID e chiavi |
| keyVaultMetadata | keyVaultMeta data | Informazioni sull'insieme di credenziali delle chiavi usato |
tipo didModel
Web
| Proprietà | Type | Descrzione |
|---|---|---|
did |
stringa | Did per questa istanza del servizio credenziali verificabile |
signingKeys |
Matrice di stringhe | URL della chiave di firma |
linkedDomainUrls |
Matrice di stringhe | Domini collegati a questo DID, in attesa di una singola voce |
| didModel | didModel | Informazioni su DID e chiavi |
didDocumentStatus |
string | stato dell'operazione DID, il valore è sempre published per questo metodo |
tipo keyVaultMetadata
| Proprietà | Type | Descrzione |
|---|---|---|
subscriptionId |
stringa | La sottoscrizione di Azure in cui si trova l'insieme di credenziali delle chiavi |
resourceGroup |
string | nome del gruppo di risorse da questo insieme di credenziali delle chiavi |
resourceName |
string | Nome dell'insieme di credenziali delle chiavi |
resourceUrl |
string | URL dell'insieme di credenziali delle chiavi |
Autorità di elenco
Ottenere tutte le autorità configurate o i servizi di credenziali verificabili per questo tenant
Richiesta HTTP
GET /v1.0/verifiableCredentials/authorities
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo.
Messaggio di risposta
Il messaggio di risposta è una matrice di fonti Di esempio:
HTTP/1.1 200 OK
Content-type: application/json
{
value:
[
{
"id": "ffea7eb3-0000-1111-2222-000000000000",
"name": "AuthorityName",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
},
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "AuthorityName2",
"keyVaultUrl": "https://vccontosokv.vault.azure.net/",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid2.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid2.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
]
}
Creare l'autorità
Questa chiamata crea una nuova chiave privata, una chiave di ripristino e una chiave di aggiornamento, archivia queste chiavi nell'insieme di credenziali delle chiavi di Azure specificato e imposta le autorizzazioni per questo insieme di credenziali per il servizio credenziali verificabile e una nuova operazione DID con il documento DID corrispondente.
Richiesta HTTP
POST /v1.0/verifiableCredentials/authorities
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Nel corpo della richiesta specificare una rappresentazione JSON del codice seguente
| Proprietà | Type | Descrzione |
|---|---|---|
name |
stringa | Nome visualizzato di questa istanza del servizio |
linkedDomainUrl |
string | Dominio collegato all'operazione DID |
didMethod |
string | Deve essere web |
keyVaultMetadata |
keyVaultMetadata | metadati per un insieme di credenziali delle chiavi specifico |
Messaggio di esempio:
{
"name":"ExampleName",
"linkedDomainUrl":"https://verifiedid.contoso.com/",
"didMethod": "web",
"keyVaultMetadata":
{
"subscriptionId":"aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup":"verifiablecredentials",
"resourceName":"vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
Messaggio di risposta
In caso di esito positivo, il messaggio di risposta contiene il nome dell'autorità
Messaggio di esempio per did:web:
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
Messaggio di esempio per did:ion:
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItest6",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "submitted"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
Osservazioni:
È possibile creare più autorità con le proprie chiavi DID e private, che non saranno visibili nell'interfaccia utente del portale di Azure. Attualmente supportiamo solo la presenza di 1 autorità. Non sono stati testati completamente tutti gli scenari con più autorità create. Se stai provando questo ti preghiamo di comunicarci la tua esperienza.
Autorità di aggiornamento
Questo metodo può essere usato per aggiornare il nome visualizzato di questa specifica istanza del servizio credenziali verificabile.
Richiesta HTTP
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
Sostituire il valore di :authorityId con il valore dell'ID autorità da aggiornare.
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Nel corpo della richiesta specificare una rappresentazione JSON del codice seguente.
| Proprietà | Type | Descrzione |
|---|---|---|
name |
stringa | Nome visualizzato di questa istanza del servizio |
Messaggio di esempio
{
"name":"ExampleIssuerName"
}
Eliminare l'autorità
Questo metodo può essere usato per eliminare un'autorità. Attualmente è possibile eliminare solo did:ion le autorità. Quando si elimina un'autorità, tutte le credenziali ID verificate rilasciate diventano non valide e non possono più essere verificate perché l'autorità emittente non è più disponibile.
Richiesta HTTP
DELETE /beta/verifiableCredentials/authorities/:authorityId
Sostituire il valore di :authorityId con il valore dell'ID autorità da eliminare.
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Nessun corpo della richiesta
Messaggio di risposta
Messaggio di risposta di esempio:
Risposta dell'autorità di eliminazione riuscita.
HTTP/1.1 200 OK
Se l'eliminazione dell'autorità ha avuto esito positivo ma la pulizia delle chiavi di Azure Key Vault non è riuscita, si ottiene la risposta seguente.
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"error": {
"code": "deleteIssuerSuccessfulButKeyDeletionFailed",
"message": "The organization has been opted out of the Verifiable Credentials, but the following keys could not be deleted. To keep your organization secure, delete keys that are not in use. https://kxxxxxx.vault.azure.net/keys/vcSigningKey-9daeexxxxx-0575-23dc-81be-5f6axxxxx/0dcc532adb9a4fcf9902f90xxxxx"
}
}
Configurazione DID nota
Il generateWellknownDidConfiguration metodo genera il file di did-configuration.json firmato. Il file deve essere caricato nella .well-known cartella nella radice del sito Web ospitato per il dominio nel dominio collegato di questa istanza di credenziali verificabile. Le istruzioni sono consultabili qui.
Richiesta HTTP
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
È necessario specificare uno dei domini nei domini collegati dell'autorità specificata.
{
"domainUrl":"https://atest/"
}
Messaggio di risposta
Messaggio di risposta di esempio:
HTTP/1.1 200 OK
Content-type: application/json
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbGciOiJFUzI1NksiL...<SNIP>..."
]
}
Salvare questo risultato con il nome del file did-configuration.json e caricare il file nella cartella e nel sito Web corretti. Se si specifica un dominio non collegato a questo documento DID/DID, viene visualizzato un errore:
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"requestId":"079192a95fbf56a661c1b2dd0e012af5",
"date":"Mon, 07 Feb 2022 18:55:53 GMT",
"mscv":"AVQh55YiU3FxMipB.0",
"error":
{
"code":"wellKnownConfigDomainDoesNotExistInIssuer",
"message":"The domain used as an input to generate the well-known document is not registered with your organization. Domain: https://wrongdomain/"
}
}
Osservazioni:
È possibile puntare più DID allo stesso dominio. Se si sceglie questa configurazione, è necessario combinare i token generati e inserirli nello stesso file di did-configuration.json. Il file contiene una matrice di questi token.
Ad esempio:
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbG..token1...<SNIP>...",
"eyJhbG..token2...<SNIP>..."
]
}
Generare un documento DID
Questa chiamata genera il documento DID utilizzato per gli identificatori DID:WEB. Dopo aver generato il documento DID, l'amministratore deve posizionare il file nel https://domain/.well-known/did.json percorso.
Richiesta HTTP
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo.
Messaggio di risposta
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "did:web:verifiedid.contoso.com",
"@context": [
"https://www.w3.org/ns/did/v1",
{
"@base": "did:web:verifiedid.contoso.com"
}
],
"service": [
{
"id": "#linkeddomains",
"type": "LinkedDomains",
"serviceEndpoint": {
"origins": [
"https://verifiedid.contoso.com/"
]
}
},
{
"id": "#hub",
"type": "IdentityHub",
"serviceEndpoint": {
"instances": [
"https://verifiedid.hub.msidentity.com/v1.0/f640a374-b380-42c9-8e14-d174506838e9"
]
}
}
],
"verificationMethod": [
{
"id": "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b",
"controller": "did:web:verifiedid.contoso.com",
"type": "EcdsaSecp256k1VerificationKey2019",
"publicKeyJwk": {
"crv": "secp256k1",
"kty": "EC",
"x": "bFkOsjDB_K-hfz-c-ggspVHETMeZm31CtuzOt0PrmZc",
"y": "sewHrUNpXvJ7k-_4K8Yq78KgKzT1Vb7kmhK8x7_6h0g"
}
}
],
"authentication": [
"#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
],
"assertionMethod": [
"#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b"
]
}
Commento
Richiede al chiamante di disporre delle autorizzazioni key list per l'insieme di credenziali delle chiavi di destinazione.
Convalidare la configurazione DID nota
Questa chiamata controlla la configurazione did. Scarica la configurazione DID nota e convalida se viene usato il did corretto e la firma è corretta.
Richiesta HTTP
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo.
Messaggio di risposta
HTTP/1.1 204 No Content
Content-type: application/json
Ruotare la chiave di firma
La chiave di firma di rotazione crea una nuova chiave privata per l'autorità did:web. Il documento DID deve essere registrato nuovamente per riflettere l'aggiornamento. Al termine, synchronizeWithDidDocument indica al sistema di iniziare a usare la nuova chiave per la firma.
Richiesta HTTP
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo.
Messaggio di risposta
l'oggetto didDocumentStatus cambierà in outOfSync.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "outOfSync"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
Eseguire la sincronizzazione con il documento DID
Dopo aver ruotato la chiave di firma, il documento DID deve essere registrato nuovamente per riflettere l'aggiornamento. Al termine, synchronizeWithDidDocument indica al sistema di iniziare a usare la nuova chiave per la firma.
Richiesta HTTP
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo.
Messaggio di risposta
L'oggetto didDocumentStatus cambierà da outOfSync a published in una chiamata riuscita.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItesta",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "published"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vcwingtipskv",
"resourceUrl": "https://vcwingtipskv.vault.azure.net/"
},
"linkedDomainsVerified": false
}
Contratti
Questo endpoint consente di creare nuovi contratti e aggiornare i contratti esistenti. I contratti sono costituiti da due parti rappresentate da due definizioni JSON. Informazioni su come progettare e creare manualmente un contratto sono disponibili qui.
- La definizione di visualizzazione viene usata dagli amministratori per controllare l'aspetto di credenziali verificabili, ad esempio colore di sfondo, logo e titolo delle credenziali verificabili. Questo file contiene anche le attestazioni che devono essere archiviate all'interno delle credenziali verificabili.
- La definizione delle regole contiene le informazioni su come raccogliere e raccogliere attestazioni come attestazioni autocertificate, un'altra credenziale verificabile come input o forse un token ID ricevuto dopo che un utente ha eseguito l'accesso a un provider di identità compatibile con OIDC.
Metodi
| Metodi | Tipo restituito | Descrizione |
|---|---|---|
| Ottenere il contratto | Contract | Leggere le proprietà di un contratto |
| Elencare i contratti | Raccolta di contratti | Ottenere un elenco di tutti i contratti configurati |
| Creare un contratto | Contract | Creare un nuovo contratto |
| Aggiornare il contratto | Contract | Aggiorna contratto |
Ottenere il contratto
Richiesta HTTP
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
:authorityId Sostituire e :contractId con il valore corretto dell'autorità e del contratto.
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo.
Messaggio di risposta
messaggio di esempio:
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": false,
"manifestUrl": "...",
"issueNotificationAllowedToGroupOids" : null,
"rules": <rulesModel>,
"displays": <displayModel[]>,
"allowOverrideValidityIntervalOnIssuance": false
}
La risposta contiene le proprietà seguenti
Tipo di contratto
| Proprietà | Type | Descrzione |
|---|---|---|
Id |
stringa | ID contratto |
name |
string | Nome descrittivo del contratto |
status |
string | Sempre Enabled |
manifestUrl |
string | URL del contratto usato nella richiesta di rilascio |
issueNotificationEnabled |
boolean | impostare su true se gli utenti riceveranno una notifica che il vco è pronto per l'emissione |
issueNotificationAllowedToGroupOids |
matrice di stringhe groupId | matrice di ID gruppo a cui verranno offerte queste credenziali |
availableInVcDirectory |
boolean | Contratto pubblicato nella rete di credenziali verificabili |
| Regole | rulesModel | definizione delle regole |
| Visualizza | matrice displayModel | definizioni di visualizzazione |
allowOverrideValidityIntervalOnIssuance |
boolean | Se la chiamata API createIssuanceRequest è autorizzata a eseguire l'override della scadenza delle credenziali. Questa opzione è valida solo per i flussi idTokenHint . |
tipo rulesModel
| Proprietà | Type | Descrizione |
|---|---|---|
attestations |
Attestati | descrizione degli input supportati per le regole |
validityInterval |
number | questo valore mostra la durata della credenziale |
vc |
Matrice vcType | tipi per questo contratto |
customStatusEndpoint |
[customStatusEndpoint] (tipo di #customstatusendpoint) (facoltativo) | endpoint di stato da includere nella credenziale verificabile per questo contratto |
Se la proprietà della proprietà customStatusEndpoint non è specificata, viene usato l'endpoint anonymous di stato.
Tipo di attestazioni
| Proprietà | Type | Descrizione |
|---|---|---|
idTokens |
idTokenAttestation (array) (facoltativo) | descrive gli input dei token ID |
idTokenHints |
idTokenHintAttestation (array) (facoltativo) | descrive gli input dell'hint per il token ID |
presentations |
verificabilePresentationAttestation (matrice) (facoltativo) | descrive gli input di presentazioni verificabili |
selfIssued |
selfIssuedAttestation (matrice) (facoltativo) | descrive gli input autocertificati |
accessTokens |
accessTokenAttestation (array) (facoltativo) | descrive gli input dei token di accesso |
tipo idTokenAttestation
| Proprietà | Type | Descrizione |
|---|---|---|
mapping |
claimMapping (facoltativo) | regole per eseguire il mapping delle attestazioni di input in attestazioni di output nelle credenziali verificabili |
configuration |
string (url) | percorso del documento di configurazione del provider di identità |
clientId |
string | ID client da usare per ottenere il token ID |
redirectUri |
string | URI di reindirizzamento da usare per ottenere il token ID DEVE ESSERE vcclient://openid/ |
scope |
string | elenco delimitato da spazi di ambiti da usare per ottenere il token ID |
required |
booleano (valore predefinito false) | che indica se questa attestazione è obbligatoria o meno |
tipo idTokenHintAttestation
| Proprietà | Type | Descrizione |
|---|---|---|
mapping |
claimMapping (facoltativo) | regole per eseguire il mapping delle attestazioni di input in attestazioni di output nelle credenziali verificabili |
required |
booleano (valore predefinito false) | che indica se questa attestazione è obbligatoria o meno |
trustedIssuers |
string (matrice) | elenco di ID autorizzati a rilasciare le credenziali verificabili per questo contratto |
tipo verificabilePresentationAttestation
| Proprietà | Type | Descrizione |
|---|---|---|
mapping |
claimMapping (facoltativo) | regole per eseguire il mapping delle attestazioni di input in attestazioni di output nelle credenziali verificabili |
credentialType |
string (facoltativo) | tipo di credenziale richiesto dell'input |
required |
booleano (valore predefinito false) | che indica se questa attestazione è obbligatoria o meno |
trustedIssuers |
string (matrice) | elenco di ID autorizzati a rilasciare le credenziali verificabili per questo contratto |
tipo selfIssuedAttestation
| Proprietà | Type | Descrizione |
|---|---|---|
mapping |
claimMapping (facoltativo) | regole per eseguire il mapping delle attestazioni di input in attestazioni di output nelle credenziali verificabili |
required |
booleano (valore predefinito false) | che indica se questa attestazione è obbligatoria o meno |
tipo accessTokenAttestation
| Proprietà | Type | Descrizione |
|---|---|---|
mapping |
claimMapping (facoltativo) | regole per eseguire il mapping delle attestazioni di input in attestazioni di output nelle credenziali verificabili |
required |
booleano (valore predefinito false) | che indica se questa attestazione è obbligatoria o meno |
I valori supportati per la
mappingsproprietà sono:givenName,displayName,preferredLanguage,surnameuserPrincipalName,jobTitle.photoinputClaim
tipo claimMapping
| Proprietà | Type | Descrzione |
|---|---|---|
inputClaim |
stringa | nome dell'attestazione da usare dall'input |
outputClaim |
string | nome dell'attestazione nella credenziale verificabile |
indexed |
booleano (valore predefinito false) | che indica se il valore di questa attestazione viene utilizzato per la ricerca; è consentito indicizzare un solo oggetto clientMapping per un determinato contratto |
required |
booleano (valore predefinito false) | che indica se questo mapping è obbligatorio o meno |
type |
string (facoltativo) | tipo di attestazione |
tipo customStatusEndpoint
| Proprietà | Type | Descrizione |
|---|---|---|
url |
string (url) | URL dell'endpoint di stato personalizzato |
type |
string | tipo dell'endpoint |
esempio:
"rules": {
"attestations": {
"idTokens": [
{
"clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"configuration": "https://bankofwoodgrove.b2clogin.com/bankofwoodgrove.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_1_si",
"redirectUri": "vcclient://openid/",
"scope": "openid",
"mapping": [
{
"outputClaim": "givenName",
"required": false,
"inputClaim": "given_name",
"indexed": false
},
{
"outputClaim": "familyName",
"required": false,
"inputClaim": "family_name",
"indexed": true
}
],
"required": false
}
]
},
"validityInterval": 2592000,
"vc": {
"type": [
"BankofWoodgroveIdentity"
]
}
}
tipo displayModel
| Proprietà | Type | Descrzione |
|---|---|---|
locale |
stringa | impostazioni locali di questa visualizzazione |
credential |
displayCredential | proprietà di visualizzazione delle credenziali verificabili |
consent |
displayConsent | dati supplementari quando vengono rilasciate le credenziali verificabili |
claims |
matrice displayClaims | etichette per le attestazioni incluse nella credenziale verificabile |
displayCredential type
| Proprietà | Type | Descrzione |
|---|---|---|
title |
stringa | titolo delle credenziali |
issuedBy |
string | nome dell'emittente della credenziale |
backgroundColor |
numero (esadecimale) | colore di sfondo delle credenziali in esadecimale, ad esempio #FFAABB |
textColor |
numero (esadecimale) | colore del testo delle credenziali in esadecimale, ad esempio #FFAABB |
description |
string | testo supplementare visualizzato insieme a ogni credenziale |
logo |
displayCredentialLogo | logo da usare per le credenziali |
tipo displayCredentialLogo
| Proprietà | Type | Descrizione |
|---|---|---|
uri |
string (uri) | URI del logo. Se si tratta di un URL, deve essere raggiungibile tramite internet pubblico in modo anonimo. |
description |
string | la descrizione del logo |
tipo displayConsent
| Proprietà | Type | Descrzione |
|---|---|---|
title |
stringa | titolo del consenso |
instructions |
string | testo supplementare da usare quando viene visualizzato il consenso |
tipo displayClaims
| Proprietà | Type | Descrzione |
|---|---|---|
label |
stringa | etichetta dell'attestazione in visualizzazione |
claim |
string | nome dell'attestazione a cui si applica l'etichetta |
type |
string | tipo dell'attestazione |
description |
string (facoltativo) | descrizione dell'attestazione |
esempio:
{
"displays": [
{
"locale": "en-US",
"card": {
"backgroundColor": "#FFA500",
"description": "ThisisyourBankofWoodgroveIdentity",
"issuedBy": "BankofWoodgrove",
"textColor": "#FFFF00",
"title": "BankofWoodgroveIdentity",
"logo": {
"description": "Defaultbankofwoodgrovelogo",
"uri": "https://didcustomerplayground.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png"
}
},
"consent": {
"instructions": "Please login with your bankofWoodgrove account to receive this credential.",
"title": "Do you want to accept the verifiedbankofWoodgrove Identity?"
},
"claims": [
{
"claim": "vc.credentialSubject.givenName",
"label": "Name",
"type": "String"
},
{
"claim": "vc.credentialSubject.familyName",
"label": "Surname",
"type": "String"
}
]
}
]
}
Elencare i contratti
Questa API elenca tutti i contratti configurati nel tenant corrente per l'autorità specificata.
Richiesta HTTP
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo.
Messaggio di risposta
messaggio di esempio:
{
"value":
[
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "test1",
"authorityId": "ffea7eb3-0000-1111-2222-000000000000",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
},
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDI",
"name": "test2",
"authorityId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"status": "Enabled",
"issueNotificationEnabled": false,
"manifestUrl" : "https://...",
"rules": "<rules JSON>",
"displays": [{<display JSON}]
}
]
}
Create contract
Quando si crea un contratto, il nome deve essere univoco nel tenant. Nel caso in cui siano state create più autorità, il nome del contratto deve essere univoco in tutte le autorità. Il nome del contratto farà parte dell'URL del contratto, che viene usato nelle richieste di rilascio.
Richiesta HTTP
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Richiesta di esempi
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
Messaggio di risposta
Messaggio di esempio:
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "GUID",
"name": "ExampleContractName1",
"issuerId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"status": "Enabled",
"issueNotificationEnabled": false,
"rules": "<rules JSON>",
"displays": [{<display JSON}],
"manifestUrl": "https://..."
}
Aggiorna contratto
Questa API consente di aggiornare il contratto.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid
Richiesta di esempio:
{
"rules": "<rules JSON>",
"displays": [{<display JSON}],}
"availableInVcDirectory": true
"allowOverrideValidityIntervalOnIssuance": true
}
Messaggio di risposta
Messaggio di esempio:
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
"name": "contractname",
"status": "Enabled",
"issueNotificationEnabled": false,
"availableInVcDirectory": true,
"manifestUrl": "https://...",
"issueNotificationAllowedToGroupOids" : null,
"rules": rulesModel,
"displays": displayModel[],
"allowOverrideValidityIntervalOnIssuance": true
}
Titolo
Questo endpoint consente di cercare le credenziali verificabili rilasciate, controllare lo stato di revoca e revocare le credenziali.
Metodi
| Metodi | Tipo restituito | Descrizione |
|---|---|---|
| Ottenere le credenziali | Credenziali | Leggere le proprietà di una credenziale |
| Credenziali di ricerca | Raccolta di credenziali | Cercare un elenco di credenziali con un valore di attestazione specifico |
| Revocare le credenziali | Revocare credenziali specifiche |
Ottenere le credenziali
Questa API consente di recuperare una credenziale specifica e controllare lo stato per verificare se viene revocato o meno.
Richiesta HTTP
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Messaggio di risposta
Messaggio di esempio
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "valid",
"issuedAt": "2017-09-13T21:59:23.9868631Z"
}
Credenziali di ricerca
È possibile cercare credenziali verificabili con attestazioni di indice specifiche. Poiché viene archiviato solo un hash, è necessario cercare il valore calcolato specifico. L'algoritmo da usare è: Base64Encode(SHA256(contractid + valore attestazione)) Un esempio in C# è simile al seguente:
string claimvalue = "Bowen";
string contractid = "<...your-contract-id-value...>";
string output;
using (var sha256 = SHA256.Create())
{
var input = contractid + claimvalue;
byte[] inputasbytes = Encoding.UTF8.GetBytes(input);
hashedsearchclaimvalue = Convert.ToBase64String(sha256.ComputeHash(inputasbytes));
output = System.Net.WebUtility.UrlEncode( hashedsearchclaimvalue );
}
Nella richiesta seguente viene illustrato come aggiungere il valore calcolato al parametro di filtro della richiesta. Attualmente è supportato solo il formato filter=indexclaimhash eq.
Richiesta HTTP
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo.
Messaggio di risposta
Messaggio di esempio
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"status": "valid",
"issuedAtTimestamp": "Sat, 5 Feb 2022 03:51:29 GMT"
}
]
}
Revocare le credenziali
Questa API consente di revocare una credenziale specifica, dopo aver cercato le credenziali usando l'API di ricerca che le credenziali possono essere revocate specificando l'ID credenziale specifico.
Richiesta HTTP
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo.
Messaggio di risposta
HTTP/1.1 204 No Content
Content-type: application/json
Rifiutare esplicitamente
Questo metodo rimuoverà completamente tutte le istanze del servizio credenziali verificabile in questo tenant. Rimuove tutti i contratti configurati. Ogni credenziale verificabile rilasciata non può essere verificata per la revoca. Non è possibile annullare questa azione.
Avviso
Questa azione non può essere annullata e invaliderà tutte le credenziali verificabili rilasciate e i contratti creati.
Richiesta HTTP
POST /v1.0/verifiableCredentials/optout
Intestazioni della richiesta
| Intestazione | Valore |
|---|---|
| Autorizzazione | Connessione (token). Richiesto |
| Content-Type | application/json |
Corpo della richiesta
Non fornire un corpo della richiesta per questo metodo
Messaggio di risposta
Messaggio di risposta di esempio
HTTP/1.1 200 OK
Content-type: application/json
OK
Commento
Nota
Se non si dispone delle autorizzazioni di eliminazione per Key Vault, verrà restituito un messaggio di errore e si continuerà a rifiutare esplicitamente