Controleerbare legitimatiebewijzen Admin API

Artikel
12/07/2023

Met de Microsoft Entra Verified-id Admin API kunt u alle aspecten van de service controleerbaar legitimatiebewijs beheren. Het biedt een manier om een gloednieuwe service in te stellen, controleerbaar legitimatiebewijs-contracten te beheren en te maken, controleerbaar legitimatiebewijzen in te trekken en de service volledig uit te sluiten.

De API is bedoeld voor ontwikkelaars die vertrouwd zijn met RESTful API's en voldoende machtigingen voor de Microsoft Entra-tenant om de service in te schakelen

Basis-URL

De Admin API is server via HTTPS. Alle URL's waarnaar in de documentatie wordt verwezen, hebben de volgende basis: https://verifiedid.did.msidentity.com.

Verificatie

De API wordt beveiligd via Microsoft Entra-id en gebruikt OAuth2 bearer-tokens. Het toegangstoken kan voor een gebruiker of voor een toepassing zijn.

Bearer-tokens voor gebruikers

De app-registratie moet beschikken over de API-machtiging voor Verifiable Credentials Service Admin en moet vervolgens bij het verkrijgen van het toegangstoken het bereik 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access gebruiken. Het toegangstoken moet voor een gebruiker met de rol globale beheerder of verificatiebeleidsbeheerder zijn. Een gebruiker met globale rollezer kan ALLEEN-lezen API-aanroepen uitvoeren.

Bearer-tokens voor toepassingen

De Verifiable Credentials Service Admin service ondersteunt de volgende toepassingsmachtigingen.

Machtiging	Beschrijving
VerifiableCredential.Authority.ReadWrite	Machtiging voor het lezen/schrijven van instantieobjecten
VerifiableCredential.Contract.ReadWrite	Machtiging voor het lezen/schrijven van contractobjecten
VerifiableCredential.Credential.Search	Machtiging om te zoeken naar een referentie om in te trekken
VerifiableCredential.Credential.Revoke	Machtiging om een eerder uitgegeven referentie in te trekken
VerifiableCredential.Network.Read	Machtiging voor het lezen van vermeldingen uit het geverifieerde id-netwerk

De app-registratie moet beschikken over de API-machtiging voor Verifiable Credentials Service Admin en machtigingen die zijn vereist uit de bovenstaande tabel. Wanneer het toegangstoken wordt opgehaald, moet de app via de clientreferentiestroom het bereik 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.defaultgebruiken.

Als de app een nieuwe instantie wil maken, heeft deze twee dingen nodig. Eerst heeft de app-registratie de VerifiableCredential.Authority.ReadWrite machtiging nodig. Ten tweede heeft de app toegangsbeleid voor Key Vaults nodig Create Key . Als de app alleen bestaande instanties leest/schrijft, heeft deze de Key Vault-machtiging niet nodig.

Onboarding

Deze API is bedoeld om een nieuwe omgeving te maken, zodat nieuwe instanties kunnen worden ingesteld. Dit kan handmatig worden geactiveerd door te navigeren naar de pagina controleerbaar legitimatiebewijs in de Azure-portal. U hoeft deze API maar één keer aan te roepen en alleen als u een gloednieuwe omgeving wilt instellen met de API.

HTTP-aanvraag

POST /v1.0/verifiableCredentials/onboard

Gebruik dit eindpunt om het inrichten van de controleerbaar legitimatiebewijs-service in uw tenant te voltooien. Het systeem maakt de rest van de service-principals als deze nog niet zijn ingericht.

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef geen aanvraagtekst op voor deze methode.

Retourbericht

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

Herhaaldelijk aanroepen van deze API resulteert in exact hetzelfde retourbericht.

Instanties

Dit eindpunt kan worden gebruikt om een controleerbaar legitimatiebewijs service-exemplaar te maken of bij te werken.

Methoden

Methoden	Retourtype	Beschrijving
Instantie ophalen	Instantie	Eigenschappen van een instantie lezen
Instantie weergeven	Instantiematrix	Een lijst ophalen met alle geconfigureerde instanties/controleerbaar legitimatiebewijs-services
Instantie maken	Instantie	Een nieuwe instantie maken
Instantie bijwerken	Instantie	Instantie bijwerken
Instantie verwijderen	Instantie	Instantie verwijderen
Bekende DID-configuratie genereren
DID-document genereren
Bekende DID-configuratie valideren
Ondertekeningssleutel draaien	Instantie	Ondertekeningssleutel draaien
Synchroniseren met DID-document	Instantie	DID-document synchroniseren met nieuwe ondertekeningssleutel

Instantie ophalen

Haal de eigenschappen van een geconfigureerde instantie of controleerbaar legitimatiebewijs service-instantie op.

HTTP-aanvraag

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

Vervang de :authorityId waarde van een van de geconfigureerde instanties.

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef geen aanvraagbody op voor deze methode

Antwoordbericht

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

Het antwoord bevat de volgende eigenschappen.

Instantietype

Eigenschap	Type	Omschrijving
`Id`	tekenreeks	Een automatisch gegenereerde unieke id, die kan worden gebruikt om het specifieke exemplaar van de controleerbaar legitimatiebewijs-service op te halen of bij te werken
`name`	tekenreeks	De beschrijvende naam van dit exemplaar van de controleerbaar legitimatiebewijs-service
`status`	tekenreeks	status van de service, deze waarde is altijd `enabled`
didModel	didModel	Informatie over de DID en sleutels
keyVaultMetadata	keyVaultMeta-gegevens	Informatie over de gebruikte Key Vault

didModel-type

Web

Eigenschap	Type	Omschrijving
`did`	tekenreeks	De DID voor dit controleerbaar legitimatiebewijs service-exemplaar
`signingKeys`	tekenreeksmatrix	URL naar de ondertekeningssleutel
`linkedDomainUrls`	tekenreeksmatrix	Domeinen die aan deze DID zijn gekoppeld, verwachten één vermelding
didModel	didModel	Informatie over de DID en sleutels
`didDocumentStatus`	tekenreeks	status van de DID, waarde is altijd `published` voor deze methode

keyVaultMetadata-type

Eigenschap	Type	Omschrijving
`subscriptionId`	tekenreeks	Het Azure-abonnement waarin Key Vault zich bevindt
`resourceGroup`	tekenreeks	naam van de resourcegroep uit deze Key Vault
`resourceName`	tekenreeks	Naam van de sleutelkluis
`resourceUrl`	tekenreeks	URL naar deze Key Vault

Instanties weergeven

Alle geconfigureerde instanties of controleerbaar legitimatiebewijs-services voor deze tenant ophalen

HTTP-aanvraag

GET /v1.0/verifiableCredentials/authorities

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef geen aanvraagtekst op voor deze methode.

Antwoordbericht

Antwoordbericht is een matrix van bronvermeldingen

Voorbeeld:

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

Instantie maken

Met deze aanroep maakt u een nieuwe persoonlijke sleutel, herstelsleutel en updatesleutel, slaat u deze sleutels op in de opgegeven Azure Key Vault en stelt u de machtigingen voor deze sleutelkluis in voor de verifieerbare referentieservice en maakt u een nieuwe DID met het bijbehorende DID-document.

HTTP-aanvraag

POST /v1.0/verifiableCredentials/authorities

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef in de aanvraagbody een JSON-weergave van het volgende op

Eigenschap	Type	Omschrijving
`name`	tekenreeks	De schermnaam van dit exemplaar van de service
`linkedDomainUrl`	tekenreeks	Het domein dat aan dit DID is gekoppeld
`didMethod`	tekenreeks	Moet `web` zijn
`keyVaultMetadata`	keyVaultMetadata	metagegevens voor specifieke sleutelkluis

Voorbeeldbericht:

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

Antwoordbericht

Wanneer het antwoordbericht is geslaagd, bevat het de naam van de instantie

Voorbeeldbericht voor 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
}

Voorbeeldbericht voor did:web:

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

Opmerkingen

U kunt meerdere instanties maken met hun eigen DID- en persoonlijke sleutels. Deze zijn niet zichtbaar in de gebruikersinterface van Azure Portal. Momenteel ondersteunen we slechts één instantie. We hebben niet alle scenario's met meerdere gemaakte instanties volledig getest. Als u dit probeert, laat ons dan weten wat uw ervaring is.

Instantie bijwerken

Deze methode kan worden gebruikt om de schermnaam van dit specifieke exemplaar van de controleerbaar legitimatiebewijs-service bij te werken.

HTTP-aanvraag

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

Vervang de waarde :authorityId door de waarde van de instantie-id die u wilt bijwerken.

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef in de aanvraagbody een JSON-weergave van het volgende op.

Eigenschap	Type	Omschrijving
`name`	tekenreeks	De schermnaam van dit exemplaar van de service

Voorbeeldbericht

{
  "name":"ExampleIssuerName"
}

Instantie verwijderen

Deze methode kan worden gebruikt om een instantie te verwijderen. Momenteel kunnen alleen did:ion autoriteiten worden verwijderd. Wanneer u een instantie verwijdert, worden alle uitgegeven geverifieerde id-referenties ongeldig en kunnen ze niet meer worden geverifieerd omdat de verlenende instantie is verdwenen.

HTTP-aanvraag

DELETE /beta/verifiableCredentials/authorities/:authorityId

Vervang de waarde door :authorityId de waarde van de instantie-id die u wilt verwijderen.

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geen aanvraagbody

Antwoordbericht

Voorbeeld van antwoordbericht:

Geslaagde verwijdering van het antwoord van de instantie.

HTTP/1.1 200 OK

Als het verwijderen van de instantie is geslaagd maar het opschonen van Azure Key Vault-sleutels is mislukt, krijgt u het onderstaande antwoord.

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

Bekende DID-configuratie

Met de generateWellknownDidConfiguration methode wordt het ondertekende bestand did-configuration.json gegenereerd. Het bestand moet worden geüpload naar de .well-known map in de hoofdmap van de website die wordt gehost voor het domein in het gekoppelde domein van dit controleerbaar legitimatiebewijs-exemplaar. Instructies vindt u hier (Engelstalig).

HTTP-aanvraag

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

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

U moet een van de domeinen in de linkedDomains van de opgegeven instantie opgeven.

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

Antwoordbericht

Voorbeeld van antwoordbericht:

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

Sla dit resultaat op met de bestandsnaam did-configuration.json en upload dit bestand naar de juiste map en website. Als u een domein opgeeft dat niet is gekoppeld aan dit DID/DID-document, krijgt u een foutmelding:

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

Opmerkingen

U kunt meerdere DID's naar hetzelfde domein verwijzen. Als u deze configuratie kiest, moet u gegenereerde tokens combineren en deze in hetzelfde bestand did-configuration.json plaatsen. Het bestand bevat een matrix van deze tokens.

Voorbeeld:

{
    "@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
    "linked_dids": [
        "eyJhbG..token1...<SNIP>...",
        "eyJhbG..token2...<SNIP>..."
    ]
}

DID-document genereren

Met deze aanroep wordt het DID-document gegenereerd dat wordt gebruikt voor DID:WEB-id's. Na het genereren van dit DID-document moet de beheerder het bestand op de https://domain/.well-known/did.json locatie plaatsen.

HTTP-aanvraag

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

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef geen aanvraagtekst op voor deze methode.

Antwoordbericht

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

Opmerking

Vereist dat de aanroeper de sleuteloverzichttmachtigingen heeft voor de doelsleutelkluis.

Bekende DID-configuratie valideren

Met deze aanroep wordt uw DID-installatie gecontroleerd. Het downloadt de bekende DID-configuratie en valideert of de juiste DID wordt gebruikt en de handtekening juist is.

HTTP-aanvraag

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

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef geen aanvraagtekst op voor deze methode.

Antwoordbericht

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

Ondertekeningssleutel draaien

Met de ondertekeningssleutel draaien wordt een nieuwe persoonlijke sleutel gemaakt voor de did:web-instantie. Het DID-document moet opnieuw worden geregistreerd om de update weer te geven. Wanneer dit is gebeurd, geeft de syncWithDidDocument aan dat het systeem de nieuwe sleutel voor ondertekening moet gaan gebruiken.

HTTP-aanvraag

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

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagbody

Geef geen aanvraagtekst op voor deze methode.

Antwoordbericht

De didDocumentStatus naam wordt gewijzigd in outOfSync.

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

{
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": "APItesta",
    "status": "Enabled",
    "didModel": {
        "did": "did:web:verifiedid.contoso.com",
        "signingKeys": [
            "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/5255b9f2d9b94dc19a369ff0d36e3407"
        ],
        "recoveryKeys": [],
        "updateKeys": [],
        "encryptionKeys": [],
        "linkedDomainUrls": [
            "https://verifiedid.contoso.com/"
        ],
        "didDocumentStatus": "outOfSync"
    },
    "keyVaultMetadata": {
        "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
        "resourceGroup": "verifiablecredentials",
        "resourceName": "vcwingtipskv",
        "resourceUrl": "https://vcwingtipskv.vault.azure.net/"
    },
    "linkedDomainsVerified": false
}

Synchroniseren met DID-document

Nadat de ondertekeningssleutel is gedraaid, moet het DID-document opnieuw worden geregistreerd om de update weer te geven. Wanneer dit is gebeurd, geeft de syncWithDidDocument aan dat het systeem de nieuwe sleutel voor ondertekening moet gaan gebruiken.

HTTP-aanvraag

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

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagbody

Geef geen aanvraagtekst op voor deze methode.

Antwoordbericht

De didDocumentStatus wijziging wordt gewijzigd van outOfSync in published een geslaagde oproep.

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
}

Contracten

Met dit eindpunt kunt u nieuwe contracten maken en bestaande contracten bijwerken. Contracten bestaan uit twee delen die worden vertegenwoordigd door twee JSON-definities. Hier vindt u informatie over het handmatig ontwerpen en maken van een contract.

De weergavedefinitie wordt door beheerders gebruikt om het uiterlijk van een controleerbaar legitimatiebewijs te bepalen, bijvoorbeeld achtergrondkleur, logo en titel van het controleerbaar legitimatiebewijs. Dit bestand bevat ook de claims die moeten worden opgeslagen in het controleerbaar legitimatiebewijs.
De definitie van de regels bevat de informatie over het verzamelen en verzamelen van attestations, zoals zelf-geteste claims, een ander controleerbaar legitimatiebewijs als invoer of misschien een id-token dat is ontvangen nadat een gebruiker zich heeft aangemeld bij een OIDC-compatibele id-provider.

Methoden

Methoden	Retourtype	Beschrijving
Contract ophalen	Contract	Eigenschappen van een contract lezen
Contracten weergeven	Contractverzameling	Een lijst met alle geconfigureerde contracten ophalen
Contract maken	Contract	Een nieuw contract maken
Contract bijwerken	Contract	Contract bijwerken

Contract ophalen

HTTP-aanvraag

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

Vervang de :authorityId en :contractId door de juiste waarde van de autoriteit en het contract.

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef geen aanvraagtekst op voor deze methode.

Antwoordbericht

voorbeeldbericht:

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
}

Het antwoord bevat de volgende eigenschappen

Contracttype

Eigenschap	Type	Omschrijving
`Id`	tekenreeks	contract-id
`name`	tekenreeks	De beschrijvende naam van dit contract
`status`	tekenreeks	Altijd `Enabled`
`manifestUrl`	tekenreeks	URL naar het contract dat wordt gebruikt in de uitgifteaanvraag
`issueNotificationEnabled`	boolean	ingesteld op true als gebruikers een melding ontvangen dat deze VC gereed is om te worden uitgegeven
`issueNotificationAllowedToGroupOids`	matrix van groupId-tekenreeksen	matrix van groeps-id's wordt deze referentie aangeboden aan
`availableInVcDirectory`	boolean	Is dit contract gepubliceerd in het controleerbaar legitimatiebewijs
regels	rulesModel	regeldefinitie
weergegeven	displayModel-matrix	weergavedefinities
`allowOverrideValidityIntervalOnIssuance`	boolean	Als de createIssuanceRequest-API-aanroep de vervaldatum van de referentie mag overschrijven. Dit is alleen geldig voor idTokenHint-stromen .

Type rulesModel

Eigenschap	Type	Description
`attestations`	Getuigschriften	beschrijft ondersteunde invoer voor de regels
`validityInterval`	Nummer	deze waarde toont de levensduur van de referentie
`vc`	vcType-matrix	typen voor dit contract
`customStatusEndpoint`	[customStatusEndpoint] (#customstatusendpoint-type) (optioneel)	statuseindpunt dat moet worden opgenomen in het controleerbaar legitimatiebewijs voor dit contract

Als de eigenschap customStatusEndpoint niet is opgegeven, wordt het anonymous statuseindpunt gebruikt.

Attestations-type

Eigenschap	Type	Description
`idTokens`	idTokenAttestation (matrix) (optioneel)	beschrijft id-tokeninvoer
`idTokenHints`	idTokenHintAttestation (matrix) (optioneel)	beschrijft id-tokenhintinvoer
`presentations`	verifiablePresentationAttestation (matrix) (optioneel)	beschrijft verifieerbare presentatiesinvoer
`selfIssued`	selfIssuedAttestation (matrix) (optioneel)	beschrijft zelf uitgegeven invoer
`accessTokens`	accessTokenAttestation (matrix) (optioneel)	beschrijft invoer van toegangstokens

type idTokenAttestation

Eigenschap	Type	Description
`mapping`	claimMapping (optioneel)	regels voor het toewijzen van invoerclaims aan uitvoerclaims in het controleerbaar legitimatiebewijs
`configuration`	tekenreeks (URL)	locatie van het configuratiedocument van de id-provider
`clientId`	tekenreeks	client-id die moet worden gebruikt bij het verkrijgen van het id-token
`redirectUri`	tekenreeks	omleidings-URI die moet worden gebruikt bij het verkrijgen van het id-token, MOET vcclient://openid/ zijn
`scope`	tekenreeks	door spaties gescheiden lijst van bereiken die moeten worden gebruikt bij het verkrijgen van het id-token
`required`	Booleaanse waarde (standaard onwaar)	geeft aan of deze attestation vereist is of niet

Type idTokenHintAttestation

Eigenschap	Type	Description
`mapping`	claimMapping (optioneel)	regels voor het toewijzen van invoerclaims aan uitvoerclaims in het controleerbaar legitimatiebewijs
`required`	Booleaanse waarde (standaard onwaar)	geeft aan of deze attestation vereist is of niet
`trustedIssuers`	tekenreeks (matrix)	een lijst van DID's die het controleerbaar legitimatiebewijs mogen uitgeven voor dit contract

Type verifiablePresentationAttestation

Eigenschap	Type	Description
`mapping`	claimMapping (optioneel)	regels voor het toewijzen van invoerclaims aan uitvoerclaims in het controleerbaar legitimatiebewijs
`credentialType`	tekenreeks (optioneel)	vereist type aanmeldingsgegeven van de invoer
`required`	Booleaanse waarde (standaard onwaar)	geeft aan of deze attestation vereist is of niet
`trustedIssuers`	tekenreeks (matrix)	een lijst van DID's die het controleerbaar legitimatiebewijs mogen uitgeven voor dit contract

type selfIssuedAttestation

Eigenschap	Type	Description
`mapping`	claimMapping (optioneel)	regels voor het toewijzen van invoerclaims aan uitvoerclaims in het controleerbaar legitimatiebewijs
`required`	Booleaanse waarde (standaard onwaar)	geeft aan of deze attestation vereist is of niet

type accessTokenAttestation

Eigenschap	Type	Description
`mapping`	claimMapping (optioneel)	regels voor het toewijzen van invoerclaims aan uitvoerclaims in het controleerbaar legitimatiebewijs
`required`	Booleaanse waarde (standaard onwaar)	geeft aan of deze attestation vereist is of niet

Ondersteunde inputClaim waarden voor de mappings eigenschap zijn: givenName, displayName, preferredLanguage, userPrincipalName, surname, mail, jobTitle, photo.

Type claimMapping

Eigenschap	Type	Omschrijving
`inputClaim`	tekenreeks	de naam van de claim uit de invoer die moet worden gebruikt
`outputClaim`	tekenreeks	de naam van de claim in het controleerbaar legitimatiebewijs
`indexed`	Booleaanse waarde (standaard onwaar)	geeft aan of de waarde van deze claim wordt gebruikt om te zoeken; slechts één clientMapping-object is indexeerbaar voor een bepaald contract
`required`	Booleaanse waarde (standaard onwaar)	geeft aan of deze toewijzing vereist is of niet
`type`	tekenreeks (optioneel)	type claim

type customStatusEndpoint

Eigenschap	Type	Description
`url`	tekenreeks (URL)	de URL van het aangepaste statuseindpunt
`type`	tekenreeks	het type eindpunt

voorbeeld:

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

type displayModel

Eigenschap	Type	Omschrijving
`locale`	tekenreeks	de landinstelling van deze weergave
`credential`	displayCredential	de weergave-eigenschappen van het controleerbaar legitimatiebewijs
`consent`	displayConsent	aanvullende gegevens wanneer het controleerbaar legitimatiebewijs wordt uitgegeven
`claims`	displayClaims-matrix	labels voor de claims in het controleerbaar legitimatiebewijs

type displayCredential

Eigenschap	Type	Omschrijving
`title`	tekenreeks	titel van het aanmeldingsgegeven
`issuedBy`	tekenreeks	de naam van de uitgever van het aanmeldingsgegeven
`backgroundColor`	getal (hexadecimaal)	hexadecimale achtergrondkleur van het aanmeldingsgegeven in, bijvoorbeeld #FFAABB
`textColor`	getal (hexadecimaal)	hexadecimaal van het aanmeldingsgegeven in, bijvoorbeeld #FFAABB
`description`	tekenreeks	aanvullende tekst die naast elk aanmeldingsgegeven wordt weergegeven
`logo`	displayCredentialLogo	het logo dat moet worden gebruikt voor het aanmeldingsgegeven

type displayCredentialLogo

Eigenschap	Type	Description
`uri`	tekenreeks (URI)	URI van het logo. Als dit een URL is, moet deze anoniem bereikbaar zijn via het openbare internet.
`description`	tekenreeks	de beschrijving van het logo

type displayConsent

Eigenschap	Type	Omschrijving
`title`	tekenreeks	titel van de toestemming
`instructions`	tekenreeks	aanvullende tekst die moet worden gebruikt bij het weergeven van de toestemming

Type displayClaims

Eigenschap	Type	Omschrijving
`label`	tekenreeks	het label van de claim in de weergave
`claim`	tekenreeks	de naam van de claim waarop het label van toepassing is
`type`	tekenreeks	het type claim
`description`	tekenreeks (optioneel)	de beschrijving van de claim

voorbeeld:

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

Contracten weergeven

Deze API bevat alle contracten die zijn geconfigureerd in de huidige tenant voor de opgegeven instantie.

HTTP-aanvraag

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

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef geen aanvraagtekst op voor deze methode.

Antwoordbericht

voorbeeldbericht:

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

Contract maken

Bij het maken van een contract moet de naam uniek zijn in de tenant. Als u meerdere instanties hebt gemaakt, moet de naam van het contract uniek zijn voor alle instanties. De naam van het contract maakt deel uit van de contract-URL, die wordt gebruikt in de uitgifteaanvragen.

HTTP-aanvraag

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

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Voorbeeld van aanvraag

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

Antwoordbericht

Voorbeeldbericht:

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

Contract bijwerken

Met deze API kunt u het contract bijwerken.

PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid

Voorbeeldaanvraag:

{
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],}
    "availableInVcDirectory": true
    "allowOverrideValidityIntervalOnIssuance": true
}

Antwoordbericht

Voorbeeldbericht:

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
}

Referentie

Met dit eindpunt kunt u zoeken naar uitgegeven controleerbaar legitimatiebewijzen, de intrekkingsstatus controleren en referenties intrekken.

Methoden

Methoden	Retourtype	Beschrijving
Referentie ophalen	Referentie	Eigenschappen van een referentie lezen
Referenties zoeken	Referentieverzameling	Zoeken in een lijst met referenties met een specifieke claimwaarde
Referentie intrekken		Specifieke referentie intrekken

Referentie ophalen

Met deze API kunt u een specifieke referentie ophalen en de status controleren om te zien of deze is ingetrokken of niet.

HTTP-aanvraag

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

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Antwoordbericht

Voorbeeldbericht

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

{
    "id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
    "contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
    "status": "valid",
    "issuedAt": "2017-09-13T21:59:23.9868631Z"
}

Referenties zoeken

U kunt zoeken naar controleerbaar legitimatiebewijzen met specifieke indexclaims. Omdat alleen een hash is opgeslagen, moet u zoeken naar de specifieke berekende waarde. Het algoritme dat u moet gebruiken is: Base64Encode(SHA256(contractid + claimwaarde)) Een voorbeeld in C# ziet er als volgt uit:

  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 );
  }

De volgende aanvraag laat zien hoe u de berekende waarde toevoegt aan de filterparameter van de aanvraag. Op dit moment wordt alleen de indeling filter=indexclaimhash eq ondersteund.

HTTP-aanvraag

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

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef geen aanvraagtekst op voor deze methode.

Antwoordbericht

Voorbeeldbericht

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

Referentie intrekken

Met deze API kunt u een specifieke referentie intrekken nadat u hebt gezocht naar de referentie met behulp van de zoek-API, kan de referentie worden ingetrokken door de specifieke referentie-id op te geven.

HTTP-aanvraag

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

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef geen aanvraagtekst op voor deze methode.

Antwoordbericht

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

Afmelden

Met deze methode worden alle exemplaren van het controleerbaar legitimatiebewijs in deze tenant volledig verwijderd. Hiermee worden alle geconfigureerde contracten verwijderd. Elk uitgegeven controleerbaar legitimatiebewijs kan niet worden gecontroleerd op intrekking. Deze actie kan niet ongedaan worden gemaakt.

Waarschuwing

Deze actie kan niet ongedaan worden gemaakt en alle uitgegeven controleerbaar legitimatiebewijzen en gemaakte contracten ongeldig maken.

HTTP-aanvraag

POST /v1.0/verifiableCredentials/optout

Aanvraagheaders

Kop	Waarde
Autorisatie	Bearer (token). Vereist
Content-Type	application/json

Aanvraagtekst

Geef geen aanvraagbody op voor deze methode

Antwoordbericht

Voorbeeld van antwoordbericht

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

OK

Opmerking

Notitie

Als u geen verwijderingsmachtigingen hebt voor Key Vault wordt een foutbericht geretourneerd en wordt er nog steeds een afmelding weergegeven

Delen via

Controleerbare legitimatiebewijzen Admin API

Basis-URL

Verificatie

Bearer-tokens voor gebruikers

Bearer-tokens voor toepassingen

Onboarding

HTTP-aanvraag

Aanvraagheaders

Aanvraagtekst

Retourbericht

Instanties

Methoden

Instantie ophalen

HTTP-aanvraag

Aanvraagheaders

Aanvraagtekst

Antwoordbericht

Instantietype

didModel-type

Web

keyVaultMetadata-type

Instanties weergeven

HTTP-aanvraag

Aanvraagheaders

Aanvraagtekst

Antwoordbericht

Instantie maken

HTTP-aanvraag

Aanvraagheaders

Aanvraagtekst

Antwoordbericht

Opmerkingen

Instantie bijwerken

HTTP-aanvraag

Aanvraagheaders

Aanvraagtekst

Instantie verwijderen

HTTP-aanvraag

Aanvraagheaders

Aanvraagtekst

Antwoordbericht

Bekende DID-configuratie

HTTP-aanvraag

Aanvraagheaders

Aanvraagtekst

Antwoordbericht

Opmerkingen

DID-document genereren

HTTP-aanvraag

Aanvraagheaders

Aanvraagtekst

Antwoordbericht

Opmerking

Bekende DID-configuratie valideren

HTTP-aanvraag

Aanvraagheaders

Aanvraagtekst

Antwoordbericht

Ondertekeningssleutel draaien

HTTP-aanvraag

Aanvraagheaders

Aanvraagbody

Antwoordbericht

Synchroniseren met DID-document

HTTP-aanvraag

Aanvraagheaders

Aanvraagbody

Antwoordbericht

Contracten

Methoden

Contract ophalen

HTTP-aanvraag

Aanvraagheaders

Aanvraagtekst

Antwoordbericht

Contracttype

Type rulesModel

Attestations-type

type idTokenAttestation