Controleerbare legitimatiebewijzen Admin API

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

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

Volgende stappen