Administrator-API für Nachweise
Mit der Microsoft Entra Verified ID-Admin-API können Sie alle Aspekte des Diensts für Nachweise verwalten. Die API bietet eine Möglichkeit, einen brandneuen Dienst einzurichten, Nachweisverträge zu verwalten und zu erstellen, Nachweise zu widerrufen und den Dienst auch vollständig zu deaktivieren.
Die API ist für Entwickler*innen gedacht, die mit RESTful-APIs vertraut sind und über ausreichende Berechtigungen im Microsoft Entra-Mandanten verfügen, um den Dienst zu aktivieren.
Basis-URL
Die Administrator-API kommuniziert mit dem Server über HTTPS. Alle in der Dokumentation referenzierten URLs verwenden die folgende Basis: https://verifiedid.did.msidentity.com.
Authentifizierung
Die API ist durch Microsoft Entra ID geschützt und verwendet OAuth2-Bearertoken. Das Zugriffstoken kann für einen Benutzer oder eine Anwendung sein.
Benutzer-Bearertoken
Die App-Registrierung muss über die API-Berechtigung für Verifiable Credentials Service Admin verfügen, und beim Abrufen des Zugriffstokens sollte die App dann den Bereich 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access verwenden. Das Zugriffstoken muss für einen Benutzer mit der Rolle Globaler Administrator oder Authentifizierungsrichtlinienadministrator gelten. Ein Benutzer mit der Rolle globaler Leser kann schreibgeschützte API-Aufrufe ausführen.
Anwendungs-Bearertoken
Der Dienst „Verifiable Credentials Service Admin“ unterstützt die folgenden Anwendungsberechtigungen.
| Berechtigung | Beschreibung |
|---|---|
| VerifiableCredential.Authority.ReadWrite | Berechtigung zum Lesen/Schreiben von Autoritätsobjekten |
| VerifiableCredential.Contract.ReadWrite | Berechtigung zum Lesen/Schreiben von Vertragsobjekten |
| VerifiableCredential.Credential.Search | Berechtigung zum Suchen nach zu widerrufenden Anmeldeinformationen |
| VerifiableCredential.Credential.Revoke | Berechtigung zum Widerrufen einer zuvor ausgestellten Anmeldeinformation |
| VerifiableCredential.Network.Read | Berechtigung zum Lesen von Einträgen aus dem Verified ID Network |
Die App-Registrierung benötigt die API-Berechtigung für Verifiable Credentials Service Admin und die erforderlichen Berechtigungen aus der obigen Tabelle. Beim Abrufen des Zugriffstokens über den Flow für Clientanmeldeinformationen sollte die App den Bereich „6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default“ verwenden.
Wenn die App beabsichtigt, eine neue Autorität zu erstellen, benötigt sie zwei Dinge. Erstens benötigt die App-Registrierung die VerifiableCredential.Authority.ReadWrite-Berechtigung. Zweitens muss die App über die Create Key-Berechtigung in den Zugriffsrichtlinien der Schlüsseltresore verfügen. Wenn die App nur vorhandene Autoritäten liest/schreibt, benötigt sie nicht die Key Vault-Berechtigung.
Onboarding
Über diese API wird eine neue Umgebung erstellt, sodass neue Autoritäten eingerichtet werden können. Sie können dies auch auf der Seite „Nachweise“ im Azure-Portal manuell auslösen. Sie müssen diese API nur einmal aufrufen und nur dann, wenn Sie eine völlig neue Umgebung nur mit der API einrichten möchten.
HTTP-Anforderung
POST /v1.0/verifiableCredentials/onboard
Verwenden Sie diesen Endpunkt, um die Bereitstellung des Nachweisdiensts in Ihrem Mandanten abzuschließen. Das System erstellt die restlichen Dienstprinzipale, wenn diese noch nicht bereitgestellt sind.
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
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"
}
Wenn Sie diese API wiederholt aufrufen, wird exakt dieselbe Antwortnachricht zurückgegeben.
Autoritative Stellen
Dieser Endpunkt kann verwendet werden, um eine Instanz des Nachweisdiensts zu erstellen oder zu aktualisieren.
Methoden
| Methoden | Rückgabetyp | BESCHREIBUNG |
|---|---|---|
| Autorität abrufen | Authority | Lesen der Eigenschaften einer Autorität |
| Autorität auflisten | Autoritätsarray | Abrufen einer Liste aller konfigurierten Autoritäten/Nachweisdienste |
| Autorität erstellen | Authority | Erstellen einer neuen Autorität |
| Autorität aktualisieren | Authority | Autorität aktualisieren |
| Autorität löschen | Behörde | Autorität löschen |
| Bekannte DID-Konfiguration generieren | ||
| DID-Dokument generieren | ||
| Bekannte DID-Konfiguration überprüfen | ||
| Signaturschlüssel rotieren | Behörde | Rotieren eines Signaturschlüssels |
| Mit DID-Dokument synchronisieren | Behörde | Synchronisieren des DID-Dokuments mit neuem Signaturschlüssel |
Autorität abrufen
Dient zum Abrufen der Eigenschaften einer konfigurierten Autorität oder einer Nachweisdienstinstanz.
HTTP-Anforderung
GET /v1.0/verifiableCredentials/authorities/:authorityId
Ersetzen Sie die :authorityId durch den Wert einer der konfigurierten Autoritäten.
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
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/"
}
}
Die Antwort enthält die folgenden Eigenschaften.
Autoritätstyp
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
Id |
Zeichenfolge | Eine automatisch generierte eindeutige ID, die zum Abrufen oder Aktualisieren der spezifischen Instanz des Nachweisdiensts verwendet werden kann |
name |
Zeichenfolge | Der Anzeigename dieser Instanz des Nachweisdiensts |
status |
Zeichenfolge | Der Status des Diensts, dieser ist immer enabled |
| didModel | didModel | Informationen zu DID und Schlüsseln |
| keyVaultMetadata | keyVaultMeta-Daten | Informationen zur verwendeten Key Vault-Instanz |
didModel-Typ
Web
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
did |
Zeichenfolge | Die DID für diese Instanz des Nachweisdiensts |
signingKeys |
Zeichenfolgenarray | URL zum Signaturschlüssel |
linkedDomainUrls |
Zeichenfolgenarray | Domänen, die mit dieser DID verknüpft sind; erwartet wird ein einzelner Eintrag |
| didModel | didModel | Informationen zu DID und Schlüsseln |
didDocumentStatus |
Zeichenfolge | Status der DID, der Wert für diese Methode ist immer published |
keyVaultMetadata-Typ
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
subscriptionId |
Zeichenfolge | Das Azure-Abonnement, in dem sich diese Key Vault-Instanz befindet |
resourceGroup |
Zeichenfolge | Name der Ressourcengruppe in dieser Key Vault-Instanz |
resourceName |
Zeichenfolge | Name der Key Vault-Instanz |
resourceUrl |
Zeichenfolge | URL zu dieser Key Vault-Instanz |
Autoritäten auflisten
Dient zum Abrufen aller konfigurierten Autoritäten oder Nachweisdienste für diesen Mandanten.
HTTP-Anforderung
GET /v1.0/verifiableCredentials/authorities
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
Die Antwortnachricht ist ein Array von Autoritäten.
Beispiel:
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/"
}
}
]
}
Autorität erstellen
Dieser Aufruf erstellt einen neuen privaten Schlüssel, einen Wiederherstellungsschlüssel und einen Aktualisierungsschlüssel, speichert diese Schlüssel in der angegebenen Azure Key Vault-Instanz und legt die Berechtigungen für diese Key Vault-Instanz für den Nachweisdienst fest. Außerdem erstellt er eine neue DID mit einem zugehörigen DID-Dokument.
HTTP-Anforderung
POST /v1.0/verifiableCredentials/authorities
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie im Anforderungstext eine JSON-Darstellung der folgenden Elemente an:
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
name |
Zeichenfolge | Der Anzeigename dieser Instanz des Diensts |
linkedDomainUrl |
Zeichenfolge | Die mit dieser DID verknüpfte Domäne |
didMethod |
Zeichenfolge | Muss gleich web sein. |
keyVaultMetadata |
keyVaultMetadata | Metadaten für einen bestimmten Schlüsseltresor |
Beispielnachricht:
{
"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/"
}
}
Antwortnachricht
Bei erfolgreicher Ausführung enthält die Antwortnachricht den Namen der Autorität
Beispielnachricht für 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
}
Beispielnachricht für 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/"
}
}
Bemerkungen
Sie können mehrere Autoritäten mit ihren eigenen DIDs und privaten Schlüsseln erstellen, diese werden auf der Benutzeroberfläche des Azure-Portals nicht angezeigt. Derzeit unterstützen wir nur die Nutzung einer Autorität. Wir haben nicht alle Szenarien mit mehreren erstellten Autoritäten vollständig getestet. Wenn Sie dies versuchen, teilen Sie uns Ihre Erfahrung mit.
Autorität aktualisieren
Diese Methode kann verwendet werden, um den Anzeigenamen dieser bestimmten Instanz des Nachweisdiensts zu aktualisieren.
HTTP-Anforderung
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
Ersetzen Sie den Wert von :authorityId durch den Wert der Autoritäts-ID, die Sie aktualisieren möchten.
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie im Anforderungstext eine JSON-Darstellung der folgenden Elemente an:
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
name |
Zeichenfolge | Der Anzeigename dieser Instanz des Diensts |
Beispielnachricht
{
"name":"ExampleIssuerName"
}
Autorität löschen
Diese Methode kann zum Löschen einer Autorität verwendet werden. Derzeit können nur did:ion Autoritäten gelöscht werden. Wenn Sie eine Autorität löschen, werden alle ausgestellten Verified ID Nachweise ungültig und können nicht mehr überprüft werden, da die ausstellende Autorität nicht mehr vorhanden ist.
HTTP-Anforderung
DELETE /beta/verifiableCredentials/authorities/:authorityId
Ersetzen Sie den Wert von :authorityId durch den Wert der Autoritäts-ID, die Sie löschen möchten.
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Kein Anforderungstext
Antwortnachricht
Beispielantwortnachricht:
Erfolgreiche Löschautoritätsantwort.
HTTP/1.1 200 OK
Wenn das Löschen der Autorität erfolgreich war, aber die Bereinigung der Azure Key Vault-Schlüssel fehlgeschlagen ist, erhalten Sie die folgende Antwort.
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"
}
}
Bekannte DID-Konfiguration
Die generateWellknownDidConfiguration-Methode generiert die signierte did-configuration.json-Datei. Die Datei muss in den Ordner .well-known im Stammverzeichnis der Website hochgeladen werden, die für die Domäne in der verknüpften Domäne dieser Nachweisdienstinstanz gehostet wird. Anweisungen dazu finden Sie hier.
HTTP-Anforderung
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Sie müssen eine der Domänen im linkedDomains-Wert der angegebenen Autorität angeben.
{
"domainUrl":"https://atest/"
}
Antwortnachricht
Beispielantwortnachricht:
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>..."
]
}
Speichern Sie dieses Ergebnis mit dem Dateinamen „did-configuration.json“, und laden Sie diese Datei in den richtigen Ordner und die richtige Website hoch. Wenn Sie eine Domäne angeben, die nicht mit dieser DID bzw. diesem DID-Dokument verknüpft ist, wird eine Fehlermeldung angezeigt:
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/"
}
}
Bemerkungen
Sie können mehrere DIDs auf ein und dieselbe Domäne verweisen. Wenn Sie diese Konfiguration auswählen, müssen Sie generierte Token kombinieren und in derselben did-configuration.json-Datei ablegen. Die Datei enthält ein Array dieser Token.
Beispiel:
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbG..token1...<SNIP>...",
"eyJhbG..token2...<SNIP>..."
]
}
DID-Dokument generieren
Dieser Aufruf generiert das DID-Dokument, das für DID:WEB-Bezeichner verwendet wird. Nach dem Generieren dieses DID-Dokuments muss der Administrator die Datei am Speicherort https://domain/.well-known/did.json platzieren.
HTTP-Anforderung
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
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"
]
}
Anmerkung
Erfordert, dass der Aufrufer über KEY LIST-Berechtigungen im Zielschlüsseltresor verfügt.
Bekannte DID-Konfiguration überprüfen
Dieser Aufruf überprüft Ihre DID-Einrichtung. Er lädt die bekannte DID-Konfiguration herunter und überprüft, ob die richtige DID verwendet wird und die Signatur korrekt ist.
HTTP-Anforderung
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
HTTP/1.1 204 No Content
Content-type: application/json
Rotieren eines Signaturschlüssels
Der rotierende Signaturschlüssel erstellt einen neuen privaten Schlüssel für die did:web-Autorität. Das DID-Dokument sollte erneut registriert werden, um das Update widerzuspiegeln. Wenn dies erfolgt, teilt das synchronizeWithDidDocument dem System mit, mit der Verwendung des neuen Schlüssels für das Signieren zu beginnen.
HTTP-Anforderung
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
Der didDocumentStatus ändert sich 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
}
Mit DID-Dokument synchronisieren
Nach dem Rotieren des Signaturschlüssels sollte das DID-Dokument erneut registriert werden, um das Update widerzuspiegeln. Wenn dies erfolgt ist, teilt das synchronizeWithDidDocument dem System mit, mit der Verwendung des neuen Schlüssels für das Signieren zu beginnen.
HTTP-Anforderung
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
Der didDocumentStatus wird bei einem erfolgreichen Anruf von outOfSync nach published ändern.
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
}
Verträge
Mit diesem Endpunkt können Sie neue Verträge erstellen und vorhandene Verträge aktualisieren. Verträge bestehen aus zwei Teilen, die durch zwei JSON-Definitionen dargestellt werden. Informationen zum manuellen Entwerfen und Erstellen eines Vertrags finden Sie hier.
- Die Anzeigedefinition wird von Administratoren verwendet, um die Darstellung eines Nachweises zu steuern, z. B. Hintergrundfarbe, Logo und Titel des Nachweises. Diese Datei enthält auch die Ansprüche, die im Nachweis gespeichert werden müssen.
- Die Regeldefinition enthält Informationen zum Erfassen und Sammeln von Nachweisen wie beispielweise selbst bestätigten Ansprüchen, einem anderen Nachweis als Eingabe oder auch einem ID-Token, das nach der Anmeldung eines Benutzers bei einem OIDC-kompatiblen Identitätsanbieter empfangen wurde.
Methoden
| Methoden | Rückgabetyp | BESCHREIBUNG |
|---|---|---|
| Vertrag abrufen | Vertrag | Lesen von Eigenschaften eines Vertrags |
| Vertrag auflisten | Vertragssammlung | Abrufen einer Liste aller konfigurierten Verträge |
| Erstellen eines Vertrags | Vertrag | Erstellen eines neuen Vertrags |
| Vertrag aktualisieren | Vertrag | Aktualisieren eines Vertrags |
Vertrag abrufen
HTTP-Anforderung
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
Ersetzen Sie :authorityId und :contractId durch die richtigen Werte für Autorität und Vertrag.
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
Beispielnachricht:
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
}
Die Antwort enthält die folgenden Eigenschaften:
Vertragstyp
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
Id |
Zeichenfolge | Vertrags-ID |
name |
Zeichenfolge | Anzeigename dieses Vertrags |
status |
Zeichenfolge | Immer Enabled |
manifestUrl |
Zeichenfolge | URL zum Vertrag, die in der Ausstellungsanforderung verwendet wird |
issueNotificationEnabled |
boolean | Wird auf TRUE festgelegt, wenn Benutzer benachrichtigt werden, dass dieser Nachweis zur Ausstellung bereit ist |
issueNotificationAllowedToGroupOids |
Array aus groupId-Zeichenfolgen | Array aus Gruppen-IDs, denen dieser Nachweis angeboten wird |
availableInVcDirectory |
boolean | Angabe, ob dieser Vertrag im Nachweisnetzwerk veröffentlicht wurde |
| Regeln | rulesModel | Regeldefinition |
| Anzeige | displayModel-Array | Anzeigedefinitionen |
allowOverrideValidityIntervalOnIssuance |
boolean | Legt fest, ob der createIssuanceRequest-API-Aufruf das Ablaufen der Anmeldeinformationen außer Kraft setzen darf. Dies gilt nur für idTokenHint-Flows. |
rulesModel-Typ
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
attestations |
attestations | Beschreibung unterstützter Eingaben für die Regeln |
validityInterval |
number | Dieser Wert zeigt die Lebensdauer des Nachweises an |
vc |
vcType-Array | Typen für diesen Vertrag |
customStatusEndpoint |
[customStatusEndpoint] (#customstatusendpoint-type) (optional) | Statusendpunkt, der in den Nachweis für diesen Vertrag aufgenommen werden soll |
Wenn die Eigenschaft customStatusEndpoint nicht angegeben ist, wird der Statusendpunkt anonymous verwendet.
Nachweistyp
| Eigenschaft | Typ | BESCHREIBUNG |
|---|---|---|
idTokens |
idTokenAttestation (Array) (optional) | beschreibt ID-Tokeneingaben |
idTokenHints |
idTokenHintAttestation (Array) (optional) | beschreibt ID-Tokenhinweiseingaben |
presentations |
verifiablePresentationAttestation (Array) (optional) | beschreibt überprüfbare Präsentationseingaben |
selfIssued |
selfIssuedAttestation (Array) (optional) | beschreibt selbst ausgestellte Eingaben |
accessTokens |
accessTokenAttestation (Array) (optional) | beschreibt Zugriffstokeneingaben |
idTokenAttestation-Typ
| Eigenschaft | Typ | BESCHREIBUNG |
|---|---|---|
mapping |
claimMapping (optional) | Regeln zum Zuordnen von Eingabeansprüchen zu Ausgabeansprüchen im Nachweis |
configuration |
string (url) | Speicherort des Konfigurationsdokuments des Identitätsanbieters |
clientId |
Zeichenfolge | Client-ID, die beim Abrufen des ID-Tokens verwendet werden soll |
redirectUri |
Zeichenfolge | Umleitungs-URI zum Abrufen des ID-Tokens; MUSS „vcclient://openid/“ lauten |
scope |
Zeichenfolge | Liste der Bereiche mit Leerzeichen als Trennzeichen für das Abrufen des ID-Tokens |
required |
Boolescher Wert (Standardwert FALSE) | Gibt an, ob dieser Nachweis erforderlich ist |
idTokenHintAttestation-Typ
| Eigenschaft | Typ | BESCHREIBUNG |
|---|---|---|
mapping |
claimMapping (optional) | Regeln zum Zuordnen von Eingabeansprüchen zu Ausgabeansprüchen im Nachweis |
required |
Boolescher Wert (Standardwert FALSE) | Gibt an, ob dieser Nachweis erforderlich ist |
trustedIssuers |
Zeichenfolge (Array) | Liste der DIDs, die Nachweise für diesen Vertrag ausstellen dürfen |
verifiablePresentationAttestation-Typ
| Eigenschaft | Typ | BESCHREIBUNG |
|---|---|---|
mapping |
claimMapping (optional) | Regeln zum Zuordnen von Eingabeansprüchen zu Ausgabeansprüchen im Nachweis |
credentialType |
Zeichenfolge (optional) | Erforderlicher Anmeldeinformationentyp für die Eingabe |
required |
Boolescher Wert (Standardwert FALSE) | Gibt an, ob dieser Nachweis erforderlich ist |
trustedIssuers |
Zeichenfolge (Array) | Liste der DIDs, die Nachweise für diesen Vertrag ausstellen dürfen |
selfIssuedAttestation-Typ
| Eigenschaft | Typ | BESCHREIBUNG |
|---|---|---|
mapping |
claimMapping (optional) | Regeln zum Zuordnen von Eingabeansprüchen zu Ausgabeansprüchen im Nachweis |
required |
Boolescher Wert (Standardwert FALSE) | Gibt an, ob dieser Nachweis erforderlich ist |
accessTokenAttestation-Typ
| Eigenschaft | Typ | BESCHREIBUNG |
|---|---|---|
mapping |
claimMapping (optional) | Regeln zum Zuordnen von Eingabeansprüchen zu Ausgabeansprüchen im Nachweis |
required |
Boolescher Wert (Standardwert FALSE) | Gibt an, ob dieser Nachweis erforderlich ist |
Unterstützte
inputClaim-Werte für diemappings-Eigenschaft:givenName,displayName,preferredLanguage,userPrincipalName,surname,jobTitle,photo.
claimMapping-Typ
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
inputClaim |
Zeichenfolge | Name des Anspruchs, der von der Eingabe verwendet werden soll |
outputClaim |
Zeichenfolge | Name des Anspruchs im Nachweis |
indexed |
Boolescher Wert (Standardwert FALSE) | Angabe, ob der Wert dieses Anspruchs für die Suche verwendet wird; pro Vertrag kann jeweils nur ein clientMapping-Objekt indiziert werden |
required |
Boolescher Wert (Standardwert FALSE) | Gibt an, ob diese Zuordnung erforderlich ist |
type |
Zeichenfolge (optional) | Anspruchstyp |
customStatusEndpoint-Typ
| Eigenschaft | Typ | BESCHREIBUNG |
|---|---|---|
url |
string (url) | die URL des benutzerdefinierten Statusendpunkts |
type |
Zeichenfolge | der Typ des Endpunkts |
Beispiel:
"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"
]
}
}
displayModel-Typ
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
locale |
Zeichenfolge | Gebietsschema dieser Anzeige |
credential |
displayCredential | Anzeigeeigenschaften des Nachweises |
consent |
displayConsent | Ergänzende Daten bei der Ausstellung des Nachweises |
claims |
displayClaims-Array | Bezeichnungen für die Ansprüche, die im Nachweis enthalten sind |
displayCredential-Typ
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
title |
Zeichenfolge | Titel der Anmeldeinformationen |
issuedBy |
Zeichenfolge | Name des Ausstellers der Anmeldeinformationen |
backgroundColor |
Zahl (hexadezimal) | Hintergrundfarbe des Nachweises im Hexadezimalformat, z. B. #FFAABB |
textColor |
Zahl (hexadezimal) | Textfarbe des Nachweises im Hexadezimalformat, z. B. #FFAABB |
description |
Zeichenfolge | Ergänzender Text, der neben jeder Anmeldeinformation angezeigt wird |
logo |
displayCredentialLogo | Logo, das für die Anmeldeinformationen verwendet werden soll |
displayCredentialLogo-Typ
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
uri |
Zeichenfolge (URI) | URI des Logos. Wenn es sich hierbei um eine URL handelt, muss sie anonym über das öffentliche Internet erreichbar sein. |
description |
Zeichenfolge | Ziel des Logos |
displayConsent-Typ
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
title |
Zeichenfolge | Titel der Einwilligung |
instructions |
Zeichenfolge | Ergänzender Text, der beim Anzeigen der Einwilligung verwendet werden soll |
displayClaims-Typ
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
label |
Zeichenfolge | Bezeichnung des Anspruchs in der Anzeige |
claim |
Zeichenfolge | Name des Anspruchs, für den die Bezeichnung gilt |
type |
Zeichenfolge | Typ des Anspruchs |
description |
Zeichenfolge (optional) | Beschreibung des Anspruchs |
Beispiel:
{
"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"
}
]
}
]
}
Verträge auflisten
Diese API listet alle Verträge auf, die im aktuellen Mandanten für die angegebene Autorität konfiguriert sind.
HTTP-Anforderung
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
Beispielnachricht:
{
"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}]
}
]
}
Erstellen eines Vertrags
Beim Erstellen eines Vertrags muss der Name im Mandanten eindeutig sein. Falls Sie mehrere Autoritäten erstellt haben, muss der Vertragsname für alle Autoritäten eindeutig sein. Der Name des Vertrags ist Teil der Vertrags-URL, die in den Ausstellungsanforderungen verwendet wird.
HTTP-Anforderung
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Beispielanforderung
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
Antwortnachricht
Beispielnachricht:
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://..."
}
Vertrag aktualisieren
Mit dieser API können Sie den Vertrag aktualisieren.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid
Beispiel für eine Anforderung:
{
"rules": "<rules JSON>",
"displays": [{<display JSON}],}
"availableInVcDirectory": true
"allowOverrideValidityIntervalOnIssuance": true
}
Antwortnachricht
Beispielnachricht:
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
}
Anmeldeinformationen
Mit diesem Endpunkt können Sie nach ausgestellten Nachweisen suchen, den Widerrufstatus überprüfen und Nachweise widerrufen.
Methoden
| Methoden | Rückgabetyp | BESCHREIBUNG |
|---|---|---|
| Nachweis abrufen | Anmeldeinformationen | Lesen von Eigenschaften eines Nachweises |
| Nachweise suchen | Nachweissammlung | Durchsuchen einer Liste von Nachweisen mit einem bestimmten Anspruchswert |
| Nachweis widerrufen | Widerrufen bestimmter Nachweise |
Nachweis abrufen
Mit dieser API können Sie einen bestimmten Nachweis abrufen und den Status überprüfen, um festzustellen, ob er widerrufen wurde oder nicht.
HTTP-Anforderung
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | Anwendung/json |
Antwortnachricht
Beispielnachricht
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "valid",
"issuedAt": "2017-09-13T21:59:23.9868631Z"
}
Nachweise suchen
Sie können nach Nachweisen mit bestimmten Indexansprüchen suchen. Da nur ein Hash gespeichert ist, müssen Sie nach dem spezifischen berechneten Wert suchen. Der zu verwendende Algorithmus lautet: Base64Encode(SHA256(contractid + claimvalue)). Hier sehen Sie ein Beispiel in C#:
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 );
}
Die folgende Anforderung zeigt, wie der berechnete Wert dem Filterparameter der Anforderung hinzugefügt wird. Derzeit wird nur das Gleichungsformat „filter=indexclaimhash“ unterstützt.
HTTP-Anforderung
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
Beispielnachricht
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"
}
]
}
Nachweis widerrufen
Mit dieser API können Sie einen bestimmten Nachweis widerrufen: Nachdem Sie mithilfe der Such-API nach dem Nachweis gesucht haben, können Sie ihn widerrufen, indem Sie die spezifische Nachweis-ID angeben.
HTTP-Anforderung
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
HTTP/1.1 204 No Content
Content-type: application/json
Beendigung der Teilnahme
Mit dieser Methode werden alle Instanzen des Nachweisdiensts in diesem Mandanten vollständig entfernt. Alle konfigurierten Verträge werden entfernt. Ausgestellte Nachweise können nicht mehr auf Widerruf überprüft werden. Diese Aktion kann nicht rückgängig gemacht werden.
Warnung
Diese Aktion kann nicht rückgängig gemacht werden, und alle ausgestellten Nachweise und erstellten Verträge werden ungültig.
HTTP-Anforderung
POST /v1.0/verifiableCredentials/optout
Anforderungsheader
| Header | Wert |
|---|---|
| Authorization | Bearer (Token). Erforderlich |
| Content-Type | application/json |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwortnachricht
Beispielantwortnachricht
HTTP/1.1 200 OK
Content-type: application/json
OK
Anmerkung
Hinweis
Wenn Sie keine Löschberechtigungen für Key Vault haben, wird eine Fehlermeldung zurückgegeben, und die Deaktivierung wird trotzdem durchgeführt.
Nächste Schritte
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter: https://aka.ms/ContentUserFeedback.
Einreichen und Feedback anzeigen für