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
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
.
De API wordt beveiligd via Microsoft Entra-id en gebruikt OAuth2 bearer-tokens. Het toegangstoken kan voor een gebruiker of voor een toepassing zijn.
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.
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/.default
gebruiken.
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.
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.
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.
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagtekst op voor deze methode.
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.
Dit eindpunt kan worden gebruikt om een controleerbaar legitimatiebewijs service-exemplaar te maken of bij te werken.
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 |
Haal de eigenschappen van een geconfigureerde instantie of controleerbaar legitimatiebewijs service-instantie op.
GET /v1.0/verifiableCredentials/authorities/:authorityId
Vervang de :authorityId
waarde van een van de geconfigureerde instanties.
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagbody op voor deze methode
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.
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 |
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 |
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 |
Alle geconfigureerde instanties of controleerbaar legitimatiebewijs-services voor deze tenant ophalen
GET /v1.0/verifiableCredentials/authorities
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagtekst op voor deze methode.
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/"
}
}
]
}
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.
POST /v1.0/verifiableCredentials/authorities
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
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/"
}
}
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/"
}
}
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.
Deze methode kan worden gebruikt om de schermnaam van dit specifieke exemplaar van de controleerbaar legitimatiebewijs-service bij te werken.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
Vervang de waarde :authorityId
door de waarde van de instantie-id die u wilt bijwerken.
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
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"
}
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.
DELETE /beta/verifiableCredentials/authorities/:authorityId
Vervang de waarde door :authorityId
de waarde van de instantie-id die u wilt verwijderen.
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geen aanvraagbody
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"
}
}
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).
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
U moet een van de domeinen in de linkedDomains van de opgegeven instantie opgeven.
{
"domainUrl":"https://atest/"
}
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/"
}
}
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>..."
]
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagtekst op voor deze methode.
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"
]
}
Vereist dat de aanroeper de sleuteloverzichttmachtigingen heeft voor de doelsleutelkluis.
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagtekst op voor deze methode.
HTTP/1.1 204 No Content
Content-type: application/json
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagtekst op voor deze methode.
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
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagtekst op voor deze methode.
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
}
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 | 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 |
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
Vervang de :authorityId
en :contractId
door de juiste waarde van de autoriteit en het contract.
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagtekst op voor deze methode.
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
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 . |
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.
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 |
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 |
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 |
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 |
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 |
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 demappings
eigenschap zijn:givenName
,displayName
,preferredLanguage
,userPrincipalName
,surname
,jobTitle
,photo
.
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 |
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"
]
}
}
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 |
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 |
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 |
Eigenschap | Type | Omschrijving |
---|---|---|
title |
tekenreeks | titel van de toestemming |
instructions |
tekenreeks | aanvullende tekst die moet worden gebruikt bij het weergeven van de toestemming |
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"
}
]
}
]
}
Deze API bevat alle contracten die zijn geconfigureerd in de huidige tenant voor de opgegeven instantie.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagtekst op voor deze methode.
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}]
}
]
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Voorbeeld van aanvraag
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
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://..."
}
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
}
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
}
Met dit eindpunt kunt u zoeken naar uitgegeven controleerbaar legitimatiebewijzen, de intrekkingsstatus controleren en referenties intrekken.
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 |
Met deze API kunt u een specifieke referentie ophalen en de status controleren om te zien of deze is ingetrokken of niet.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
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"
}
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.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagtekst op voor deze methode.
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"
}
]
}
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.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagtekst op voor deze methode.
HTTP/1.1 204 No Content
Content-type: application/json
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.
POST /v1.0/verifiableCredentials/optout
Kop | Waarde |
---|---|
Autorisatie | Bearer (token). Vereist |
Content-Type | application/json |
Geef geen aanvraagbody op voor deze methode
Voorbeeld van antwoordbericht
HTTP/1.1 200 OK
Content-type: application/json
OK
Notitie
Als u geen verwijderingsmachtigingen hebt voor Key Vault wordt een foutbericht geretourneerd en wordt er nog steeds een afmelding weergegeven