Condividi tramite

API di amministrazione delle credenziali verificabili

  • Articolo

L'API di amministrazione di ID verificato di Microsoft Entra 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 admin è 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 il ruolo di amministratore globale o 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à Authority 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à Authority Creare una nuova autorità
Autorità di aggiornamento Authority Autorità di aggiornamento
Eliminare l'autorità Authority Eliminare l'autorità
Generare una configurazione DID nota
Generare un documento DID
Convalidare la configurazione DID nota
Ruota chiave di firma Authority Ruotare la chiave di firma
Eseguire la sincronizzazione con il documento DID Authority 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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": "ExampleAuthorityName",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/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 Descrizione
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 Descrizione
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 Descrizione
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

Esempio:

HTTP/1.1 200 OK
Content-type: application/json
{
    value:

    [
        {
            "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
            "name": "AuthorityName",
            "status": "Enabled",
            "didModel": {
                "did": "did:web:verifiedid.contoso.com",
                "signingKeys": [
                    "https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/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 Descrizione
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

Esempio di messaggio :

{
  "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 Descrizione
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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
    "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 Descrizione
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
norme 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 mappings proprietà sono: givenName, displayName, preferredLanguage, surnameuserPrincipalName, mail, jobTitle. photoinputClaim

tipo claimMapping

Proprietà Type Descrizione
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 Descrizione
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 Descrizione
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 Descrizione
title stringa titolo del consenso
instructions string testo supplementare da usare quando viene visualizzato il consenso

tipo displayClaims

Proprietà Type Descrizione
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.z13.web.core.windows.net/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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
            "name": "test1",
            "authorityId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
            "status": "Enabled",
            "issueNotificationEnabled": false,
            "manifestUrl" : "https://...",
            "rules": "<rules JSON>",
            "displays": [{<display JSON}]
        },
        {
            "id": "C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w",
            "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

Esempio di messaggio :

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

Esempio di messaggio :

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
    "name": "contractname",
    "status": "Enabled",
    "issueNotificationEnabled": false,
    "availableInVcDirectory": true,
    "manifestUrl": "https://...",
    "issueNotificationAllowedToGroupOids" : null,
    "rules": rulesModel,
    "displays": displayModel[],
    "allowOverrideValidityIntervalOnIssuance": true
}

Credenziali

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 Credenziale 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

Passaggi successivi