Administratörs-API för verifierbara autentiseringsuppgifter
Med Microsoft Entra – verifierat ID admin-API:et kan du hantera alla aspekter av verifierbara autentiseringsuppgifter. Det erbjuder ett sätt att konfigurera en helt ny tjänst, hantera och skapa verifierbara autentiseringsuppgifter, återkalla verifierbara autentiseringsuppgifter och helt välja bort tjänsten också.
API:et är avsett för utvecklare som är bekväma med RESTful-API:er och tillräcklig behörighet för Microsoft Entra-klientorganisationen för att aktivera tjänsten
Administratörs-API:et är en server via HTTPS. Alla URL:er som refereras i dokumentationen har följande bas: https://verifiedid.did.msidentity.com
.
API:et skyddas via Microsoft Entra-ID och använder OAuth2-ägartoken. Åtkomsttoken kan vara för en användare eller för ett program.
Appregistreringen måste ha API-behörigheten för Verifiable Credentials Service Admin
och när du hämtar åtkomsttoken ska appen använda omfånget 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access
. Åtkomsttoken måste vara för en användare med rollen Global administratör eller administratör för autentiseringsprincip. En användare med rollen global läsare kan utföra skrivskyddade API-anrop.
Tjänsten Verifiable Credentials Service Admin
stöder följande programbehörigheter.
Behörighet | beskrivning |
---|---|
VerifiableCredential.Authority.ReadWrite | Behörighet att läsa/skriva utfärdarobjekt |
VerifiableCredential.Contract.ReadWrite | Behörighet att läsa/skriva kontraktobjekt |
VerifiableCredential.Credential.Search | Behörighet att söka efter en autentiseringsuppgift att återkalla |
VerifiableCredential.Credential.Revoke | Behörighet att återkalla en tidigare utfärdad autentiseringsuppgift |
VerifiableCredential.Network.Read | Behörighet att läsa poster från det verifierade ID-nätverket |
Appregistreringen måste ha API-behörighet för Verifiable Credentials Service Admin
och behörigheter som krävs från tabellen ovan. När du hämtar åtkomsttoken ska appen använda omfånget 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default
via flödet för klientautentiseringsuppgifter.
Om appen har för avsikt att skapa en ny utfärdare behöver den två saker. Först behöver appregistreringen behörigheten VerifiableCredential.Authority.ReadWrite
. För det andra måste appen ha Create Key
behörighet i Key Vaults-åtkomstprinciper. Om appen bara läser/skriver befintliga myndigheter behöver den inte key vault-behörigheten.
Det här API:et hjälper dig att skapa en ny miljö så att nya myndigheter kan konfigureras. Detta kan utlösas manuellt genom att navigera till sidan Verifiable Credential i Azure Portal också. Du behöver bara anropa det här API:et en gång och bara om du vill konfigurera en helt ny miljö bara med API:et.
POST /v1.0/verifiableCredentials/onboard
Använd den här slutpunkten för att slutföra etableringen av verifierbara autentiseringsuppgifter i klientorganisationen. Systemet skapar resten av tjänstens huvudnamn om de inte har etablerats ännu.
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange ingen begärandetext för den här metoden.
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"
}
Upprepade gånger resulterar anropet av det här API:et i exakt samma returmeddelande.
Den här slutpunkten kan användas för att skapa eller uppdatera en verifierbar tjänstinstans för autentiseringsuppgifter.
Metoder | Returtyp | beskrivning |
---|---|---|
Hämta utfärdare | Utfärdare | Läs egenskaper för en utfärdare |
Lista över utfärdare | Utfärdarmatris | Hämta en lista över alla konfigurerade tjänster för myndigheter/verifierbara autentiseringsuppgifter |
Skapa utfärdare | Utfärdare | Skapa en ny utfärdare |
Uppdatera utfärdare | Utfärdare | Uppdatera utfärdare |
Ta bort utfärdare | Utfärdare | Ta bort utfärdare |
Generera välkänd DID-konfiguration | ||
Generera DID-dokument | ||
Verifiera välkänd DID-konfiguration | ||
Rotera signeringsnyckel | Utfärdare | Rotera signeringsnyckel |
Synkronisera med DID-dokument | Utfärdare | Synkronisera DID-dokument med ny signeringsnyckel |
Hämta egenskaperna för en konfigurerad utfärdare eller verifierbar tjänstinstans för autentiseringsuppgifter.
GET /v1.0/verifiableCredentials/authorities/:authorityId
:authorityId
Ersätt med värdet för en av de konfigurerade myndigheterna.
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange inte en begärandetext för den här metoden
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/"
}
}
Svaret innehåller följande egenskaper.
Property | Type | Description |
---|---|---|
Id |
sträng | Ett automatiskt genererat unikt ID som kan användas för att hämta eller uppdatera den specifika instansen av den verifierbara autentiseringstjänsten |
name |
sträng | Det egna namnet på den här instansen av den verifierbara autentiseringstjänsten |
status |
sträng | status för tjänsten kommer det här värdet alltid att vara enabled |
didModel | didModel | Information om DID och nycklar |
keyVaultMetadata | keyVaultMeta-data | Information om det använda Key Vault |
Property | Type | Description |
---|---|---|
did |
sträng | DID för den här verifierbara tjänstinstansen för autentiseringsuppgifter |
signingKeys |
strängmatris | URL till signeringsnyckeln |
linkedDomainUrls |
strängmatris | Domäner som är länkade till den här DID-filen förväntar sig en enda post |
didModel | didModel | Information om DID och nycklar |
didDocumentStatus |
sträng | status för DID är värdet alltid published för den här metoden |
Property | Type | Description |
---|---|---|
subscriptionId |
sträng | Den Azure-prenumeration som det här Key Vault finns i |
resourceGroup |
sträng | namnet på resursgruppen från det här Nyckelvalvet |
resourceName |
sträng | Key Vault-namn |
resourceUrl |
sträng | URL till det här Nyckelvalvet |
Hämta alla konfigurerade myndigheter eller verifierbara autentiseringsuppgifter för den här klientorganisationen
GET /v1.0/verifiableCredentials/authorities
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange ingen begärandetext för den här metoden.
Svarsmeddelande är en matris med myndigheter
Exempel:
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/"
}
}
]
}
Det här anropet skapar en ny privat nyckel, en återställningsnyckel och en uppdateringsnyckel, lagrar dessa nycklar i det angivna Azure Key Vault och anger behörigheterna till det här nyckelvalvet för den verifierbara autentiseringstjänsten och en ny DID-skapande med motsvarande DID-dokument.
POST /v1.0/verifiableCredentials/authorities
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
I begärandetexten anger du en JSON-representation av följande
Property | Type | Description |
---|---|---|
name |
sträng | Visningsnamnet för den här instansen av tjänsten |
linkedDomainUrl |
sträng | Domänen som är länkad till denna DID |
didMethod |
sträng | Måste vara web |
keyVaultMetadata |
keyVaultMetadata | metadata för specifika nyckelvalv |
Exempelmeddelande:
{
"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/"
}
}
När svarsmeddelandet har slutförts innehåller det namnet på utfärdaren
Exempelmeddelande 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
}
Exempelmeddelande 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/"
}
}
Du kan skapa flera myndigheter med egna DID och privata nycklar. Dessa visas inte i användargränssnittet för Azure Portal. För närvarande stöder vi endast att ha en auktoritet. Vi har inte testat alla scenarier fullständigt med flera skapade myndigheter. Om du provar detta kan du berätta för oss om din upplevelse.
Den här metoden kan användas för att uppdatera visningsnamnet för den här specifika instansen av den verifierbara autentiseringstjänsten.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
Ersätt värdet :authorityId
för med värdet för det utfärdar-ID som du vill uppdatera.
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange en JSON-representation av följande i begärandetexten.
Property | Type | Description |
---|---|---|
name |
sträng | Visningsnamnet för den här instansen av tjänsten |
Exempelmeddelande
{
"name":"ExampleIssuerName"
}
Den här metoden kan användas för att ta bort en utfärdare. För närvarande kan endast did:ion
myndigheter tas bort. När du tar bort en utfärdare blir alla utfärdade verifierade ID-autentiseringsuppgifter ogiltiga och kan inte verifieras längre när den utfärdande utfärdaren är borta.
DELETE /beta/verifiableCredentials/authorities/:authorityId
Ersätt värdet :authorityId
för med värdet för det utfärdar-ID som du vill ta bort.
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ingen begärandetext
Exempel på svarsmeddelande:
Svar på en borttagningsutfärdaråtgärd har slutförts.
HTTP/1.1 200 OK
Om borttagningen av utfärdaren lyckades men rensningen av Azure Key Vault-nycklar misslyckades får du svaret nedan.
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"
}
}
Metoden generateWellknownDidConfiguration
genererar den signerade did-configuration.json-filen. Filen måste laddas upp till .well-known
mappen i roten på den webbplats som finns för domänen i den länkade domänen för den här verifierbara instansen av autentiseringsuppgifter. Instruktioner finns här.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Du måste ange en av domänerna i den angivna utfärdarens länkadeDomäner.
{
"domainUrl":"https://atest/"
}
Exempel på svarsmeddelande:
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>..."
]
}
Spara det här resultatet med filnamnet did-configuration.json och ladda upp filen till rätt mapp och webbplats. Om du anger en domän som inte är länkad till det här DID/DID-dokumentet får du ett fel:
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/"
}
}
Du kan peka flera DID:er till samma domän. Om du väljer den här konfigurationen måste du kombinera genererade token och placera dem i samma did-configuration.json fil. Filen innehåller en matris med dessa token.
Till exempel:
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbG..token1...<SNIP>...",
"eyJhbG..token2...<SNIP>..."
]
}
Det här anropet genererar DID-dokumentet som används för DID:WEB-identifierare. När du har genererat det här DID-dokumentet måste administratören placera filen på platsen https://domain/.well-known/did.json .
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange ingen begärandetext för den här metoden.
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"
]
}
Kräver att anroparen har behörigheter för nyckellistan i målnyckelvalvet.
Det här anropet kontrollerar konfigurationen av DID. Den laddar ned den välkända DID-konfigurationen och verifierar om rätt DID används och signaturen är korrekt.
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange ingen begärandetext för den här metoden.
HTTP/1.1 204 No Content
Content-type: application/json
Rotationssigneringsnyckeln skapar en ny privat nyckel för did:web-utfärdaren. DID-dokumentet bör registreras igen för att återspegla uppdateringen. När detta är klart instruerar synchronizeWithDidDocument systemet att börja använda den nya nyckeln för signering.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange ingen begärandetext för den här metoden.
Ändras didDocumentStatus
till 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
}
När du har roterat signeringsnyckeln bör DID-dokumentet registreras igen för att återspegla uppdateringen. När detta är klart instruerar synchronizeWithDidDocument systemet att börja använda den nya nyckeln för signering.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange ingen begärandetext för den här metoden.
Kommer didDocumentStatus
att ändras från outOfSync
till published
vid ett lyckat anrop.
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
}
Med den här slutpunkten kan du skapa nya kontrakt och uppdatera befintliga kontrakt. Kontrakt består av två delar som representeras av två JSON-definitioner. Information om hur du utformar och skapar ett kontrakt manuellt finns här.
- Visningsdefinitionen används av administratörer för att styra utseendet på en verifierbar autentiseringsuppgift, till exempel bakgrundsfärg, logotyp och rubrik för de verifierbara autentiseringsuppgifterna. Den här filen innehåller också de anspråk som måste lagras i den verifierbara autentiseringsuppgiften.
- Regeldefinitionen innehåller information om hur du samlar in och samlar in attesteringar som självbebevisade anspråk, en annan verifierbar autentiseringsuppgift som indata eller kanske en ID-token som tas emot efter att en användare har loggat in på en OIDC-kompatibel identitetsprovider.
Metoder | Returtyp | beskrivning |
---|---|---|
Hämta kontrakt | Contract | Läsa egenskaper för ett kontrakt |
Lista kontrakt | Kontraktsinsamling | Hämta en lista över alla konfigurerade kontrakt |
Skapa kontrakt | Contract | Skapa ett nytt kontrakt |
Uppdatera kontrakt | Contract | Uppdatera kontrakt |
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
:authorityId
Ersätt och :contractId
med rätt värde för utfärdaren och kontraktet.
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange ingen begärandetext för den här metoden.
exempelmeddelande:
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
}
Svaret innehåller följande egenskaper
Property | Type | Description |
---|---|---|
Id |
sträng | kontrakts-ID |
name |
sträng | Det egna namnet på det här kontraktet |
status |
sträng | Alltid Enabled |
manifestUrl |
sträng | URL till kontraktet som används i utfärdandebegäran |
issueNotificationEnabled |
boolean | inställd på true om användarna får ett meddelande om att den här VC:en är redo att utfärdas |
issueNotificationAllowedToGroupOids |
matris med groupId-strängar | matris med grupp-ID:t som den här autentiseringsuppgiften erbjuds till |
availableInVcDirectory |
boolean | Är det här kontraktet publicerat i verifierbart autentiseringsnätverk |
reglemente | rulesModel | regeldefinition |
Visar | displayModel-matris | visa definitioner |
allowOverrideValidityIntervalOnIssuance |
boolean | Om API-anropet createIssuanceRequest tillåts åsidosätta förfallodatum för autentiseringsuppgifterna. Detta är endast giltigt för idTokenHint-flöden . |
Property | Type | Beskrivning |
---|---|---|
attestations |
Intyg | beskriva indata som stöds för reglerna |
validityInterval |
Nummer | det här värdet visar livslängden för autentiseringsuppgifterna |
vc |
vcType-matris | typer för det här kontraktet |
customStatusEndpoint |
[customStatusEndpoint] (#customstatusendpoint-typ) (valfritt) | statusslutpunkt som ska inkluderas i den verifierbara autentiseringsuppgiften för det här kontraktet |
Om egenskapsegenskapen customStatusEndpoint
inte har angetts anonymous
används statusslutpunkten.
Property | Type | Beskrivning |
---|---|---|
idTokens |
idTokenAttestation (matris) (valfritt) | beskriver indata för ID-token |
idTokenHints |
idTokenHintAttestation (matris) (valfritt) | beskriver indata för ID-tokentips |
presentations |
verifiablePresentationAttestation (matris) (valfritt) | beskriver verifierbara presentationsindata |
selfIssued |
selfIssuedAttestation (matris) (valfritt) | beskriver själv utfärdade indata |
accessTokens |
accessTokenAttestation (matris) (valfritt) | beskriver indata för åtkomsttoken |
Property | Type | Beskrivning |
---|---|---|
mapping |
claimMapping (valfritt) | regler för att mappa indataanspråk till utdataanspråk i den verifierbara autentiseringsuppgiften |
configuration |
sträng (url) | plats för identitetsproviderns konfigurationsdokument |
clientId |
sträng | klient-ID som ska användas när du hämtar ID-token |
redirectUri |
sträng | omdirigerings-URI som ska användas när du hämtar ID-token MÅSTE vara vcclient://openid/ |
scope |
sträng | utrymmesavgränsad lista över omfång som ska användas när du hämtar ID-token |
required |
booleskt värde (standard falskt) | som anger om detta attestering krävs eller inte |
Property | Type | Beskrivning |
---|---|---|
mapping |
claimMapping (valfritt) | regler för att mappa indataanspråk till utdataanspråk i den verifierbara autentiseringsuppgiften |
required |
booleskt värde (standard falskt) | som anger om detta attestering krävs eller inte |
trustedIssuers |
sträng (matris) | en lista över DID:ar som tillåts utfärda verifierbara autentiseringsuppgifter för det här kontraktet |
Property | Type | Beskrivning |
---|---|---|
mapping |
claimMapping (valfritt) | regler för att mappa indataanspråk till utdataanspråk i den verifierbara autentiseringsuppgiften |
credentialType |
sträng (valfritt) | nödvändig typ av autentiseringsuppgifter för indata |
required |
booleskt värde (standard falskt) | som anger om detta attestering krävs eller inte |
trustedIssuers |
sträng (matris) | en lista över DID:ar som tillåts utfärda verifierbara autentiseringsuppgifter för det här kontraktet |
Property | Type | Beskrivning |
---|---|---|
mapping |
claimMapping (valfritt) | regler för att mappa indataanspråk till utdataanspråk i den verifierbara autentiseringsuppgiften |
required |
booleskt värde (standard falskt) | som anger om detta attestering krävs eller inte |
Property | Type | Beskrivning |
---|---|---|
mapping |
claimMapping (valfritt) | regler för att mappa indataanspråk till utdataanspråk i den verifierbara autentiseringsuppgiften |
required |
booleskt värde (standard falskt) | som anger om detta attestering krävs eller inte |
Värden som stöds
inputClaim
för egenskapenmappings
är:givenName
,displayName
,preferredLanguage
,userPrincipalName
,surname
,jobTitle
.photo
Property | Type | Description |
---|---|---|
inputClaim |
sträng | namnet på anspråket som ska användas från indata |
outputClaim |
sträng | namnet på anspråket i den verifierbara autentiseringsuppgiften |
indexed |
booleskt värde (standard falskt) | som anger om värdet för det här anspråket används för sökning. Endast ett clientMapping-objekt kan indexeras för ett visst kontrakt |
required |
booleskt värde (standard falskt) | som anger om den här mappningen krävs eller inte |
type |
sträng (valfritt) | typ av anspråk |
Property | Type | Beskrivning |
---|---|---|
url |
sträng (url) | URL:en för den anpassade statusslutpunkten |
type |
sträng | typ av slutpunkt |
exempel:
"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"
]
}
}
Property | Type | Description |
---|---|---|
locale |
sträng | språkvarianten för den här skärmen |
credential |
displayCredential | visningsegenskaperna för de verifierbara autentiseringsuppgifterna |
consent |
displayConsent | kompletterande data när de verifierbara autentiseringsuppgifterna utfärdas |
claims |
displayClaims-matris | etiketter för de anspråk som ingår i de verifierbara autentiseringsuppgifterna |
Property | Type | Description |
---|---|---|
title |
sträng | rubrik för autentiseringsuppgifterna |
issuedBy |
sträng | namnet på utfärdaren av autentiseringsuppgifterna |
backgroundColor |
tal (hex) | bakgrundsfärg för autentiseringsuppgifterna i hex, till exempel #FFAABB |
textColor |
tal (hex) | textfärg för autentiseringsuppgifterna i hex, till exempel #FFAABB |
description |
sträng | kompletterande text som visas tillsammans med varje autentiseringsuppgift |
logo |
displayCredentialLogo | logotypen som ska användas för autentiseringsuppgifterna |
Property | Type | Beskrivning |
---|---|---|
uri |
string (uri) | URI för logotypen. Om det här är en URL måste den kunna nås via det offentliga internet anonymt. |
description |
sträng | beskrivningen av logotypen |
Property | Type | Description |
---|---|---|
title |
sträng | medgivandets titel |
instructions |
sträng | kompletterande text som ska användas när medgivande visas |
Property | Type | Description |
---|---|---|
label |
sträng | etiketten för anspråket som visas |
claim |
sträng | namnet på det anspråk som etiketten gäller för |
type |
sträng | anspråkets typ |
description |
sträng (valfritt) | beskrivningen av anspråket |
exempel:
{
"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"
}
]
}
]
}
Det här API:et visar alla kontrakt som konfigurerats i den aktuella klientorganisationen för den angivna utfärdaren.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange ingen begärandetext för den här metoden.
exempelmeddelande:
{
"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}]
}
]
}
När du skapar ett kontrakt måste namnet vara unikt i klientorganisationen. Om du har skapat flera myndigheter måste kontraktsnamnet vara unikt för alla myndigheter. Namnet på kontraktet kommer att ingå i kontrakts-URL:en, som används i utfärdandebegäranden.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Exempelbegäranden
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
Exempelmeddelande:
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://..."
}
Med det här API:et kan du uppdatera kontraktet.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid
Exempelbegäran:
{
"rules": "<rules JSON>",
"displays": [{<display JSON}],}
"availableInVcDirectory": true
"allowOverrideValidityIntervalOnIssuance": true
}
Exempelmeddelande:
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
}
Med den här slutpunkten kan du söka efter utfärdade verifierbara autentiseringsuppgifter, kontrollera återkallningsstatus och återkalla autentiseringsuppgifter.
Metoder | Returtyp | beskrivning |
---|---|---|
Hämta autentiseringsuppgifter | Merit | Läsa egenskaper för en autentiseringsuppgift |
Autentiseringsuppgifter för sökning | Samling med autentiseringsuppgifter | Söka i en lista med autentiseringsuppgifter med ett specifikt anspråksvärde |
Återkalla autentiseringsuppgifter | Återkalla specifika autentiseringsuppgifter |
Med det här API:et kan du hämta en specifik autentiseringsuppgift och kontrollera statusen för att se om den har återkallats eller inte.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Exempelmeddelande
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "valid",
"issuedAt": "2017-09-13T21:59:23.9868631Z"
}
Du kan söka efter verifierbara autentiseringsuppgifter med specifika indexanspråk. Eftersom endast en hash lagras måste du söka efter det specifika beräknade värdet. Algoritmen du behöver använda är: Base64Encode(SHA256(contractid + anspråksvärde)) Ett exempel i C# ser ut så här:
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 );
}
Följande begäran visar hur du lägger till det beräknade värdet i filterparametern för begäran. Just nu stöds endast formatet filter=indexclaimhash eq.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange ingen begärandetext för den här metoden.
Exempelmeddelande
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"
}
]
}
Med det här API:et kan du återkalla en specifik autentiseringsuppgift, när du har sökt efter autentiseringsuppgifterna med hjälp av sök-API:et kan autentiseringsuppgifterna återkallas genom att ange det specifika autentiserings-ID:t.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange ingen begärandetext för den här metoden.
HTTP/1.1 204 No Content
Content-type: application/json
Den här metoden tar helt bort alla instanser av den verifierbara autentiseringstjänsten i den här klientorganisationen. Det tar bort alla konfigurerade kontrakt. Alla utfärdade verifierbara autentiseringsuppgifter kan inte kontrolleras för återkallning. Det går inte att ångra den här åtgärden.
Varning
Den här åtgärden kan inte ångras och ogiltigförklarar alla utfärdade verifierbara autentiseringsuppgifter och skapade kontrakt.
POST /v1.0/verifiableCredentials/optout
Header | Värde |
---|---|
Auktorisering | Bearer (token). Obligatoriskt |
Innehållstyp | application/json |
Ange inte en begärandetext för den här metoden
Exempel på svarsmeddelande
HTTP/1.1 200 OK
Content-type: application/json
OK
Anteckning
Om du inte har borttagningsbehörigheter för Key Vault returnerar vi ett felmeddelande och avregistrerar dig fortfarande