Administratörs-API för verifierbara autentiseringsuppgifter

Artikel
03/12/2024

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

Bas-URL

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.

Autentisering

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.

Användarbäraretoken

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.

Programbäraretoken

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/.defaultvia 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.

Introduktion

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 gå till sidan Verifiable Credential i Azure-portalen. 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.

HTTP-begäran

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.

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange ingen begärandetext för den här metoden.

Returmeddelande

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.

Myndigheterna

Den här slutpunkten kan användas för att skapa eller uppdatera en verifierbar tjänstinstans för autentiseringsuppgifter.

Metoder

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 utfärdare

Hämta egenskaperna för en konfigurerad utfärdare eller verifierbar tjänstinstans för autentiseringsuppgifter.

HTTP-begäran

GET /v1.0/verifiableCredentials/authorities/:authorityId

:authorityId Ersätt med värdet för en av de konfigurerade myndigheterna.

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange inte en begärandetext för den här metoden

Svarsmeddelande

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.

Typ av utfärdare

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

didModel-typ

Webb

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

keyVaultMetadata-typ

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

Lista myndigheter

Hämta alla konfigurerade myndigheter eller verifierbara autentiseringsuppgifter för den här klientorganisationen

HTTP-begäran

GET /v1.0/verifiableCredentials/authorities

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange ingen begärandetext för den här metoden.

Svarsmeddelande

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/"
            }
        }
    ]
}

Skapa utfärdare

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.

HTTP-begäran

POST /v1.0/verifiableCredentials/authorities

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

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/"
  }
}

Svarsmeddelande

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/"
    }
}

Kommentarer

Du kan skapa flera myndigheter med egna DID-nycklar och privata nycklar. Dessa visas inte i användargränssnittet i Azure-portalen. 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.

Uppdatera utfärdare

Den här metoden kan användas för att uppdatera visningsnamnet för den här specifika instansen av den verifierbara autentiseringstjänsten.

HTTP-begäran

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.

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

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"
}

Ta bort utfärdare

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.

HTTP-begäran

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.

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ingen begärandetext

Svarsmeddelande

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"
    }
}

Välkänd DID-konfiguration

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.

HTTP-begäran

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Du måste ange en av domänerna i den angivna utfärdarens länkadeDomäner.

{
    "domainUrl":"https://atest/"
}

Svarsmeddelande

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/"
  }
}

Kommentarer

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>..."
    ]
}

Generera DID-dokument

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 .

HTTP-begäran

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange ingen begärandetext för den här metoden.

Svarsmeddelande

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"
    ]
}

Anmärkning

Kräver att anroparen har behörigheter för nyckellistan i målnyckelvalvet.

Verifiera välkänd DID-konfiguration

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.

HTTP-begäran

POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange ingen begärandetext för den här metoden.

Svarsmeddelande

HTTP/1.1 204 No Content
Content-type: application/json

Rotera signeringsnyckel

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.

HTTP-begäran

POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange ingen begärandetext för den här metoden.

Svarsmeddelande

Ä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
}

Synkronisera med DID-dokument

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.

HTTP-begäran

POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange ingen begärandetext för den här metoden.

Svarsmeddelande

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
}

Kontrakt

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

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

Hämta kontrakt

HTTP-begäran

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId

:authorityId Ersätt och :contractId med rätt värde för utfärdaren och kontraktet.

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange ingen begärandetext för den här metoden.

Svarsmeddelande

exempelmeddelande:

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

{
    "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
    "name": "contractname",
    "status": "Enabled",
    "issueNotificationEnabled": false,
    "availableInVcDirectory": false,
    "manifestUrl": "...",
    "issueNotificationAllowedToGroupOids" : null,
    "rules": <rulesModel>,
    "displays": <displayModel[]>,
    "allowOverrideValidityIntervalOnIssuance": false
}

Svaret innehåller följande egenskaper

Kontraktstyp

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
Regler	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 .

rulesModel-typ

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.

typ av attesteringar

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

idTokenAttestation-typ

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

idTokenHintAttestation-typ

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

verifiablePresentationAttestation-typ

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

selfIssuedAttestation-typ

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

accessTokenAttestation-typ

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 egenskapen mappings är: givenName, displayName, preferredLanguage, userPrincipalName, surname, mail, , jobTitle. photo

claimMapping-typ

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

customStatusEndpoint-typ

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"
        ]
    }
}

displayModel-typ

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

displayCredential-typ

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

displayCredentialLogo-typ

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

displayConsent-typ

Property	Type	Description
`title`	sträng	medgivandets titel
`instructions`	sträng	kompletterande text som ska användas när medgivande visas

displayClaims-typ

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.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"
                }
            ]
        }
    ]
}

Lista kontrakt

Det här API:et visar alla kontrakt som konfigurerats i den aktuella klientorganisationen för den angivna utfärdaren.

HTTP-begäran

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange ingen begärandetext för den här metoden.

Svarsmeddelande

exempelmeddelande:

{
    "value":
    [
        {
            "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg",
            "name": "test1",
            "authorityId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
            "status": "Enabled",
            "issueNotificationEnabled": false,
            "manifestUrl" : "https://...",
            "rules": "<rules JSON>",
            "displays": [{<display JSON}]
        },
        {
            "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDI",
            "name": "test2",
            "authorityId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
            "status": "Enabled",
            "issueNotificationEnabled": false,
            "manifestUrl" : "https://...",
            "rules": "<rules JSON>",
            "displays": [{<display JSON}]
        }
    ]
}

Skapa kontrakt

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.

HTTP-begäran

POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Exempelbegäranden

{
    "name": "ExampleContractName1",
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],
}

Svarsmeddelande

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://..."
}

Uppdatera kontrakt

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
}

Svarsmeddelande

Exempelmeddelande:

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

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

Merit

Med den här slutpunkten kan du söka efter utfärdade verifierbara autentiseringsuppgifter, kontrollera återkallningsstatus och återkalla autentiseringsuppgifter.

Metoder

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

Hämta 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.

HTTP-begäran

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Svarsmeddelande

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"
}

Autentiseringsuppgifter för sökning

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.

HTTP-begäran

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange ingen begärandetext för den här metoden.

Svarsmeddelande

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"
        }
    ]
}

Återkalla autentiseringsuppgifter

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.

HTTP-begäran

POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange ingen begärandetext för den här metoden.

Svarsmeddelande

HTTP/1.1 204 No Content
Content-type: application/json

Avregistrera dig

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.

HTTP-begäran

POST /v1.0/verifiableCredentials/optout

Begärandehuvuden

Header	Värde
Auktorisering	Bearer (token). Obligatoriskt
Innehållstyp	application/json

Begärandetext

Ange inte en begärandetext för den här metoden

Svarsmeddelande

Exempel på svarsmeddelande

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

OK

Anmärkning

Kommentar

Om du inte har borttagningsbehörigheter för Key Vault returnerar vi ett felmeddelande och avregistrerar dig fortfarande

Dela via

Administratörs-API för verifierbara autentiseringsuppgifter

Bas-URL

Autentisering

Användarbäraretoken

Programbäraretoken

Introduktion

HTTP-begäran

Begärandehuvuden

Begärandetext

Returmeddelande

Myndigheterna

Metoder

Hämta utfärdare

HTTP-begäran

Begärandehuvuden

Begärandetext

Svarsmeddelande

Typ av utfärdare

didModel-typ

Webb

keyVaultMetadata-typ

Lista myndigheter

HTTP-begäran

Begärandehuvuden

Begärandetext

Svarsmeddelande

Skapa utfärdare

HTTP-begäran

Begärandehuvuden

Begärandetext

Svarsmeddelande

Kommentarer

Uppdatera utfärdare

HTTP-begäran

Begärandehuvuden

Begärandetext

Ta bort utfärdare

HTTP-begäran

Begärandehuvuden

Begärandetext

Svarsmeddelande

Välkänd DID-konfiguration

HTTP-begäran

Begärandehuvuden

Begärandetext

Svarsmeddelande

Kommentarer

Generera DID-dokument

HTTP-begäran

Begärandehuvuden

Begärandetext

Svarsmeddelande

Anmärkning

Verifiera välkänd DID-konfiguration

HTTP-begäran

Begärandehuvuden

Begärandetext

Svarsmeddelande

Rotera signeringsnyckel

HTTP-begäran

Begärandehuvuden

Begärandetext

Svarsmeddelande

Synkronisera med DID-dokument

HTTP-begäran

Begärandehuvuden

Begärandetext

Svarsmeddelande

Kontrakt

Metoder

Hämta kontrakt

HTTP-begäran

Begärandehuvuden

Begärandetext

Svarsmeddelande

Kontraktstyp

rulesModel-typ

typ av attesteringar

idTokenAttestation-typ