Läs på engelska

Dela via


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

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

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

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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
    "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
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 .

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

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

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": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
    "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

Anteckning

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

Nästa steg