Ellenőrizhető hitelesítő adatok rendszergazdai API
A Microsoft Entra Ellenőrzött azonosító Felügyeleti API lehetővé teszi az Ellenőrizhető hitelesítő adatok szolgáltatás minden aspektusának kezelését. Lehetővé teszi egy teljesen új szolgáltatás beállítását, az ellenőrizhető hitelesítő adatokra vonatkozó szerződések kezelését és létrehozását, az ellenőrizhető hitelesítő adatok visszavonását és a szolgáltatás teljes lemondását.
Az API-t a restful API-kkal és a Microsoft Entra-bérlőre vonatkozó megfelelő engedélyekkel rendelkező fejlesztőknek szántuk a szolgáltatás engedélyezéséhez
A Felügyeleti API https-en keresztüli kiszolgáló. A dokumentációban hivatkozott összes URL-cím alapja a következő: https://verifiedid.did.msidentity.com
.
Az API a Microsoft Entra-azonosítón keresztül védett, és OAuth2 tulajdonosi jogkivonatokat használ. A hozzáférési jogkivonat lehet felhasználó vagy alkalmazás számára is.
Az alkalmazásregisztrációnak rendelkeznie kell az API-engedéllyel Verifiable Credentials Service Admin
, majd a hozzáférési jogkivonat beszerzésekor az alkalmazásnak hatókört 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access
kell használnia. A hozzáférési jogkivonatnak globális rendszergazdai vagy hitelesítési házirend-rendszergazdai szerepkörrel rendelkező felhasználónak kell lennie. A globális olvasó szerepkörrel rendelkező felhasználók írásvédett API-hívásokat hajthatnak végre.
A Verifiable Credentials Service Admin
szolgáltatás az alábbi alkalmazásengedélyeket támogatja.
Engedély | Leírás |
---|---|
VerifiableCredential.Authority.ReadWrite | Olvasási/írási jogosultsággal rendelkező objektum(ok) olvasására/írására vonatkozó engedély |
VerifiableCredential.Contract.ReadWrite | Szerződésobjektum(ok) olvasására/írására vonatkozó engedély |
VerifiableCredential.Credential.Search | Engedély a visszavonandó hitelesítő adatok kereséséhez |
VerifiableCredential.Credential.Revoke | Korábban kiadott hitelesítő adatok visszavonásának engedélyezése |
VerifiableCredential.Network.Read | Az ellenőrzött azonosító hálózat bejegyzéseinek olvasására vonatkozó engedély |
Az alkalmazásregisztrációnak rendelkeznie kell a fenti táblázat API-engedélyével Verifiable Credentials Service Admin
és engedélyével. A hozzáférési jogkivonat beszerzésekor az ügyfél hitelesítő adatainak folyamatán keresztül az alkalmazásnak hatókört 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default
kell használnia.
Ha az alkalmazás új szolgáltatót kíván létrehozni, két dologra van szüksége. Először is az alkalmazásregisztrációnak szüksége van az engedélyre VerifiableCredential.Authority.ReadWrite
. Másodszor, az alkalmazásnak rendelkeznie Create Key
kell engedéllyel a Key Vaults hozzáférési szabályzataiban. Ha az alkalmazás csak a meglévő hatóságokat olvassa vagy írja, nincs szüksége a Key Vault engedélyére.
Ez az API egy új környezet létrehozásához nyújt segítséget, hogy új hatóságokat lehessen beállítani. Ezt manuálisan is aktiválhatja az Azure Portal Ellenőrizhető hitelesítő adatai lapjára való navigálással. Ezt az API-t csak egyszer kell meghívnia, és csak akkor, ha egy teljesen új környezetet szeretne beállítani csak az API-val.
POST /v1.0/verifiableCredentials/onboard
Ezzel a végponttal fejezheti be a ellenőrizhető hitelesítő adatok szolgáltatás kiépítését a bérlőben. A rendszer létrehozza a többi szolgáltatásnevet, ha még nincsenek kiépítve.
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ehhez a metódushoz ne adjon meg kérelemtörzset.
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"
}
Az API ismételt meghívása pontosan ugyanazt a visszatérési üzenetet eredményezi.
Ez a végpont használható ellenőrizhető hitelesítőadat-szolgáltatáspéldány létrehozásához vagy frissítéséhez.
Metódusok | Visszatérési típus | Leírás |
---|---|---|
Szolgáltató lekérése | Hatóság | Egy szolgáltató olvasási tulajdonságai |
Listaszolgáltató | Szolgáltatói tömb | Az összes konfigurált hatóság/ellenőrizhető hitelesítőadat-szolgáltatás listájának lekérése |
Szolgáltató létrehozása | Hatóság | Új szolgáltató létrehozása |
Frissítési szolgáltató | Hatóság | Frissítési szolgáltató |
Szolgáltató törlése | Hatóság | Szolgáltató törlése |
Jól ismert DID-konfiguráció létrehozása | ||
DID-dokumentum létrehozása | ||
Jól ismert DID-konfiguráció ellenőrzése | ||
Aláírókulcs elforgatása | Hatóság | Aláírókulcs elforgatása |
Szinkronizálás DID-dokumentummal | Hatóság | DID-dokumentum szinkronizálása új aláíró kulccsal |
Egy konfigurált szolgáltató vagy ellenőrizhető hitelesítőadat-szolgáltatáspéldány tulajdonságainak lekérése.
GET /v1.0/verifiableCredentials/authorities/:authorityId
Cserélje le az :authorityId
egyik konfigurált hatóság értékét.
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ne adjon meg kérelemtörzset ehhez a metódushoz
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/"
}
}
A válasz a következő tulajdonságokat tartalmazza.
Tulajdonság | Típus | Leírás |
---|---|---|
Id |
húr | Automatikusan létrehozott egyedi azonosító, amely az ellenőrizhető hitelesítőadat-szolgáltatás adott példányának lekérésére vagy frissítésére használható |
name |
húr | Az ellenőrizhető hitelesítőadat-szolgáltatás jelen példányának rövid neve |
status |
húr | állapotában, ez az érték mindig a enabled |
didModel | didModel | Információk a DID-ről és a kulcsokról |
keyVaultMetadata | keyVaultMeta-adatok | Információk a használt Key Vaultról |
Tulajdonság | Típus | Leírás |
---|---|---|
did |
húr | Az ellenőrizhető hitelesítőadat-szolgáltatáspéldány DID-címe |
signingKeys |
sztringtömb | Az aláírókulcs URL-címe |
linkedDomainUrls |
sztringtömb | A DID-hoz társított tartományok egyetlen bejegyzést várnak |
didModel | didModel | Információk a DID-ről és a kulcsokról |
didDocumentStatus |
húr | a DID állapota, az érték mindig published ehhez a metódushoz tartozik |
Tulajdonság | Típus | Leírás |
---|---|---|
subscriptionId |
húr | A Key Vaultban található Azure-előfizetés |
resourceGroup |
húr | a Key Vaultból származó erőforráscsoport neve |
resourceName |
húr | Key Vault neve |
resourceUrl |
húr | A Key Vault URL-címe |
A bérlő összes konfigurált hatóságának vagy ellenőrizhető hitelesítő adatainak lekérése
GET /v1.0/verifiableCredentials/authorities
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ehhez a metódushoz ne adjon meg kérelemtörzset.
A válaszüzenet a Hatóságok tömbje
Példa:
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/"
}
}
]
}
Ez a hívás létrehoz egy új titkos kulcsot, helyreállítási kulcsot és frissítési kulcsot, tárolja ezeket a kulcsokat a megadott Azure Key Vaultban, és beállítja az engedélyeket erre a Key Vaultra az ellenőrizhető hitelesítőadat-szolgáltatáshoz, és létrehoz egy új DID-t a megfelelő DID-dokumentummal.
POST /v1.0/verifiableCredentials/authorities
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
A kérelem törzsében adja meg a következő JSON-reprezentációt:
Tulajdonság | Típus | Leírás |
---|---|---|
name |
húr | A szolgáltatás jelen példányának megjelenített neve |
linkedDomainUrl |
húr | Az ehhez a DID-hez társított tartomány |
didMethod |
húr | Kell web |
keyVaultMetadata |
keyVaultMetadata | metaadatok adott kulcstartóhoz |
Példaüzenet:
{
"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/"
}
}
Sikeresség esetén a válaszüzenet tartalmazza a szolgáltató nevét
Példaüzenet a következőhöz: 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
}
Példaüzenet a következőhöz: did:ion:
HTTP/1.1 201 Created
Content-type: application/json
{
"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": "APItest6",
"status": "Enabled",
"didModel": {
"did": "did:web:verifiedid.contoso.com",
"signingKeys": [
"https://vccontosokv.vault.azure.net/keys/vcSigningKey-00aa00aa-bb11-cc22-dd33-44ee44ee44ee/f8f149eaee194beb83dfca14714ef62a"
],
"recoveryKeys": [],
"updateKeys": [],
"encryptionKeys": [],
"linkedDomainUrls": [
"https://verifiedid.contoso.com/"
],
"didDocumentStatus": "submitted"
},
"keyVaultMetadata": {
"subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"resourceGroup": "verifiablecredentials",
"resourceName": "vccontosokv",
"resourceUrl": "https://vccontosokv.vault.azure.net/"
}
}
Több hatóságot is létrehozhat saját DID és privát kulcsokkal, ezek nem jelennek meg az Azure Portal felhasználói felületén. Jelenleg csak 1 szolgáltatót támogatunk. Nem teszteltük teljes mértékben az összes forgatókönyvet több létrehozott hatósággal. Ha ezt próbálja, kérjük, ossza meg velünk tapasztalatait.
Ezzel a módszerrel frissíthető az ellenőrizhető hitelesítőadat-szolgáltatás ezen példányának megjelenítendő neve.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
Cserélje le az értéket :authorityId
a frissíteni kívánt szolgáltatóazonosító értékére.
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
A kérelem törzsében adja meg a következők JSON-ábrázolását.
Tulajdonság | Típus | Leírás |
---|---|---|
name |
húr | A szolgáltatás jelen példányának megjelenített neve |
Példaüzenet
{
"name":"ExampleIssuerName"
}
Ezzel a módszerrel törölhet egy szolgáltatót. Jelenleg csak did:ion
a hatóságok törölhetők. Ha töröl egy szolgáltatót, a kiadott ellenőrzött azonosítójú hitelesítő adatok érvénytelenek lesznek, és a kiállító hatóság eltűnése után már nem ellenőrizhetők.
DELETE /beta/verifiableCredentials/authorities/:authorityId
Cserélje le az értéket :authorityId
a törölni kívánt szolgáltatóazonosító értékére.
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Nincs kérelemtörzs
Példa válaszüzenet:
Sikeres törlési szolgáltatói válasz.
HTTP/1.1 200 OK
Ha a szolgáltató törlése sikeres volt, de az Azure Key Vault-kulcsok törlése sikertelen volt, az alábbi választ kapja.
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"
}
}
A generateWellknownDidConfiguration
metódus létrehozza az aláírt did-configuration.json fájlt. A fájlt fel kell tölteni az .well-known
ellenőrizhető hitelesítőadat-példány csatolt tartományához tartozó tartományhoz tartozó webhely gyökérmappájába. Az utasítások itt találhatók.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Meg kell adnia az egyik tartományt a megadott szolgáltató linkedDomains tartományaiban.
{
"domainUrl":"https://atest/"
}
Példa válaszüzenet:
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>..."
]
}
Mentse az eredményt a did-configuration.json fájlnévvel, és töltse fel a fájlt a megfelelő mappába és webhelyre. Ha olyan tartományt ad meg, amely nem kapcsolódik ehhez a DID/DID-dokumentumhoz, hibaüzenet jelenik meg:
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/"
}
}
Több DID-t is ugyanarra a tartományra irányíthat. Ha ezt a konfigurációt választja, egyesítenie kell a létrehozott jogkivonatokat, és ugyanabba a did-configuration.json fájlba kell őket helyeznie. A fájl ezeknek a jogkivonatoknak egy tömböt tartalmaz.
Példa:
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbG..token1...<SNIP>...",
"eyJhbG..token2...<SNIP>..."
]
}
Ez a hívás létrehozza a DID:WEB-azonosítókhoz használt DID-dokumentumot. A DID-dokumentum létrehozása után a rendszergazdának a megfelelő helyre kell helyeznie a https://domain/.well-known/did.json fájlt.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ehhez a metódushoz ne adjon meg kérelemtörzset.
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"
]
}
A hívónak rendelkeznie kell a KEY List engedélyekkel a célkulcstartón.
Ez a hívás ellenőrzi a DID beállítását. Letölti a jól ismert DID-konfigurációt, és ellenőrzi, hogy a megfelelő DID van-e használva, és az aláírás helyes-e.
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ehhez a metódushoz ne adjon meg kérelemtörzset.
HTTP/1.1 204 No Content
Content-type: application/json
A rotálási aláíró kulcs létrehoz egy új titkos kulcsot a did:webszolgáltató számára. A DID-dokumentumot újra regisztrálni kell a frissítésnek megfelelően. Ha ez megtörtént, a szinkronizáltWithDidDocument arra utasítja a rendszert, hogy kezdje el használni az új kulcsot az aláíráshoz.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ehhez a metódushoz ne adjon meg kérelemtörzset.
A didDocumentStatus
program a következőre változik 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
}
Az aláírókulcs elforgatása után a DID dokumentumot újra regisztrálni kell a frissítésnek megfelelően. Ha ez megtörtént, a szinkronizáltWithDidDocument arra utasítja a rendszert, hogy kezdje el használni az új kulcsot az aláíráshoz.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ehhez a metódushoz ne adjon meg kérelemtörzset.
A didDocumentStatus
rendszer a sikeres hívásról outOfSync
a sikeres hívásra published
vált.
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
}
Ez a végpont lehetővé teszi új szerződések létrehozását és a meglévő szerződések frissítését. A szerződések két részből állnak, amelyeket két JSON-definíció jelöl. A szerződés manuális tervezésére és létrehozására vonatkozó információk itt találhatók.
- A megjelenítési definícióval a rendszergazdák szabályozhatják az ellenőrizhető hitelesítő adatok megjelenését, például a háttérszínt, az emblémát és az ellenőrizhető hitelesítő adatok címét. Ez a fájl tartalmazza azokat a jogcímeket is, amelyeket az ellenőrizhető hitelesítő adatokban kell tárolni.
- A szabályok definíciója tartalmazza az olyan igazolások gyűjtésére és gyűjtésére vonatkozó információkat, mint az önaláírt jogcímek, egy másik ellenőrizhető hitelesítő adat bemenetként, vagy esetleg egy olyan azonosító jogkivonat, amely azután érkezett, hogy a felhasználó bejelentkezett egy OIDC-kompatibilis identitásszolgáltatóhoz.
Metódusok | Visszatérési típus | Leírás |
---|---|---|
Szerződés lekérése | Contract | Szerződés olvasási tulajdonságai |
Szerződések listázása | Szerződésgyűjtés | Az összes konfigurált szerződés listájának lekérése |
Szerződés létrehozása | Contract | Új szerződés létrehozása |
Szerződés frissítése | Contract | Szerződés frissítése |
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
Cserélje le a :authorityId
szolgáltató és :contractId
a szerződés megfelelő értékét.
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ehhez a metódushoz ne adjon meg kérelemtörzset.
példaüzenet:
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
}
A válasz a következő tulajdonságokat tartalmazza:
Tulajdonság | Típus | Leírás |
---|---|---|
Id |
húr | szerződés azonosítója |
name |
húr | A szerződés rövid neve |
status |
húr | Mindig Enabled |
manifestUrl |
húr | A kiállítási kérelemben használt szerződés URL-címe |
issueNotificationEnabled |
Logikai | értéke igaz, ha a felhasználók értesítést kapnak arról, hogy a VC készen áll a kiadásukra |
issueNotificationAllowedToGroupOids |
groupId sztringek tömbje | csoportazonosítók tömbje. Ezt a hitelesítő adatot a rendszer felajánlja a |
availableInVcDirectory |
Logikai | Ez a szerződés a Hitelesítő adatok ellenőrizhető hálózatában van közzétéve |
Szabályok | rulesModel | szabályok definíciója |
Megjeleníti | displayModel tömb | definíciók megjelenítése |
allowOverrideValidityIntervalOnIssuance |
Logikai | Ha a createIssuanceRequest API-hívás lehetővé teszi a hitelesítő adatok lejáratának felülbírálását. Ez csak idTokenHint-folyamatokra érvényes. |
Tulajdonság | Típus | Leírás |
---|---|---|
attestations |
igazolások | a szabályok támogatott bemeneteinek leírása |
validityInterval |
szám | ez az érték a hitelesítő adatok élettartamát mutatja |
vc |
vcType tömb | a szerződés típusai |
customStatusEndpoint |
[customStatusEndpoint] (#customstatusendpoint típusú) (nem kötelező) | állapotvégpont, amely szerepel a szerződés ellenőrizhető hitelesítő adatai között |
Ha a tulajdonságtulajdonság customStatusEndpoint
nincs megadva, akkor a rendszer az anonymous
állapotvégpontot használja.
Tulajdonság | Típus | Leírás |
---|---|---|
idTokens |
idTokenAttestation (tömb) (nem kötelező) | az azonosító jogkivonat bemeneteit ismerteti |
idTokenHints |
idTokenHintAttestation (tömb) (nem kötelező) | az azonosító-jogkivonatok tippbemeneteit ismerteti |
presentations |
verifiablePresentationAttestation (tömb) (nem kötelező) | ellenőrizhető bemutatók bemeneteinek leírása |
selfIssued |
selfIssuedAttestation (tömb) (nem kötelező) | önkibocsátott bemenetek leírása |
accessTokens |
accessTokenAttestation (tömb) (nem kötelező) | a hozzáférési jogkivonat bemeneteinek ismertetése |
Tulajdonság | Típus | Leírás |
---|---|---|
mapping |
claimMapping (nem kötelező) | szabályok a bemeneti jogcímek kimeneti jogcímekké való leképezéséhez az ellenőrizhető hitelesítő adatokban |
configuration |
sztring (URL) | az identitásszolgáltató konfigurációs dokumentumának helye |
clientId |
húr | az azonosító jogkivonat beszerzésekor használandó ügyfélazonosító |
redirectUri |
húr | az azonosító jogkivonat beszerzésekor használandó átirányítási uri-nak vcclient://openid/ |
scope |
húr | az azonosító jogkivonat beszerzésekor használandó hatókörök szóközzel tagolt listája |
required |
logikai (alapértelmezett hamis) | annak jelzése, hogy szükséges-e ez az igazolás, vagy sem |
Tulajdonság | Típus | Leírás |
---|---|---|
mapping |
claimMapping (nem kötelező) | szabályok a bemeneti jogcímek kimeneti jogcímekké való leképezéséhez az ellenőrizhető hitelesítő adatokban |
required |
logikai (alapértelmezett hamis) | annak jelzése, hogy szükséges-e ez az igazolás, vagy sem |
trustedIssuers |
sztring (tömb) | azon DID-k listája, amely lehetővé teszi a szerződés ellenőrizhető hitelesítő adatainak kiállítását |
Tulajdonság | Típus | Leírás |
---|---|---|
mapping |
claimMapping (nem kötelező) | szabályok a bemeneti jogcímek kimeneti jogcímekké való leképezéséhez az ellenőrizhető hitelesítő adatokban |
credentialType |
sztring (nem kötelező) | a bemenet szükséges hitelesítő adattípusa |
required |
logikai (alapértelmezett hamis) | annak jelzése, hogy szükséges-e ez az igazolás, vagy sem |
trustedIssuers |
sztring (tömb) | azon DID-k listája, amely lehetővé teszi a szerződés ellenőrizhető hitelesítő adatainak kiállítását |
Tulajdonság | Típus | Leírás |
---|---|---|
mapping |
claimMapping (nem kötelező) | szabályok a bemeneti jogcímek kimeneti jogcímekké való leképezéséhez az ellenőrizhető hitelesítő adatokban |
required |
logikai (alapértelmezett hamis) | annak jelzése, hogy szükséges-e ez az igazolás, vagy sem |
Tulajdonság | Típus | Leírás |
---|---|---|
mapping |
claimMapping (nem kötelező) | szabályok a bemeneti jogcímek kimeneti jogcímekké való leképezéséhez az ellenőrizhető hitelesítő adatokban |
required |
logikai (alapértelmezett hamis) | annak jelzése, hogy szükséges-e ez az igazolás, vagy sem |
A tulajdonság támogatott
inputClaim
értékei amappings
következők:givenName
,displayName
, ,preferredLanguage
,userPrincipalName
surname
,jobTitle
.photo
Tulajdonság | Típus | Leírás |
---|---|---|
inputClaim |
húr | a bemenetből használandó jogcím neve |
outputClaim |
húr | a jogcím neve az ellenőrizhető hitelesítő adatokban |
indexed |
logikai (alapértelmezett hamis) | annak jelzése, hogy a jogcím értéke keresésre van-e használva; egy adott szerződéshez csak egy clientMapping objektum indexelhető |
required |
logikai (alapértelmezett hamis) | annak jelzése, hogy szükséges-e ez a megfeleltetés |
type |
sztring (nem kötelező) | jogcím típusa |
Tulajdonság | Típus | Leírás |
---|---|---|
url |
sztring (URL) | az egyéni állapotvégpont URL-címe |
type |
húr | a végpont típusa |
példa:
"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"
]
}
}
Tulajdonság | Típus | Leírás |
---|---|---|
locale |
húr | a kijelző területi beállítása |
credential |
displayCredential | az ellenőrizhető hitelesítő adatok megjelenítési tulajdonságai |
consent |
displayConsent | kiegészítő adatok az ellenőrizhető hitelesítő adatok kiadásakor |
claims |
displayClaims tömb | az ellenőrizhető hitelesítő adatokban szereplő jogcímek címkéi |
Tulajdonság | Típus | Leírás |
---|---|---|
title |
húr | a hitelesítő adatok címe |
issuedBy |
húr | a hitelesítő adatok kiállítójának neve |
backgroundColor |
szám (hexa) | a hitelesítő adatok háttérszíne a hexában, például #FFAABB |
textColor |
szám (hexa) | a hitelesítő adatok szövegszíne hexában, például #FFAABB |
description |
húr | kiegészítő szöveg jelenik meg az egyes hitelesítő adatok mellett |
logo |
displayCredentialLogo | a hitelesítő adatokhoz használandó embléma |
Tulajdonság | Típus | Leírás |
---|---|---|
uri |
sztring (uri) | uri az embléma. Ha ez egy URL-cím, akkor névtelenül el kell érnie a nyilvános interneten keresztül. |
description |
húr | az embléma leírása |
Tulajdonság | Típus | Leírás |
---|---|---|
title |
húr | a hozzájárulás címe |
instructions |
húr | a hozzájárulás megjelenítésekor használandó kiegészítő szöveg |
Tulajdonság | Típus | Leírás |
---|---|---|
label |
húr | a jogcím címkéje látható |
claim |
húr | annak a jogcímnek a neve, amelyre a címke vonatkozik |
type |
húr | a jogcím típusa |
description |
sztring (nem kötelező) | a jogcím leírása |
példa:
{
"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"
}
]
}
]
}
Ez az API felsorolja a megadott szolgáltató aktuális bérlőjében konfigurált összes szerződést.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ehhez a metódushoz ne adjon meg kérelemtörzset.
példaüzenet:
{
"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}]
}
]
}
Szerződés létrehozásakor a névnek egyedinek kell lennie a bérlőben. Ha több hatóságot hozott létre, a szerződés nevének minden hatóságnál egyedinek kell lennie. A szerződés neve a szerződés URL-címének része lesz, amelyet a kiállítási kérelmek használnak.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Példa kérésre:
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
Példaüzenet:
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://..."
}
Ez az API lehetővé teszi a szerződés frissítését.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid
Példakérés:
{
"rules": "<rules JSON>",
"displays": [{<display JSON}],}
"availableInVcDirectory": true
"allowOverrideValidityIntervalOnIssuance": true
}
Példaüzenet:
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
}
Ez a végpont lehetővé teszi a kiadott ellenőrizhető hitelesítő adatok keresését, a visszavonás állapotának ellenőrzését és a hitelesítő adatok visszavonását.
Metódusok | Visszatérési típus | Leírás |
---|---|---|
Hitelesítő adatok lekérése | Hitelesítő adat | Hitelesítő adatok olvasási tulajdonságai |
Hitelesítő adatok keresése | Hitelesítő adatok gyűjtése | Adott jogcímértékkel rendelkező hitelesítő adatok listájának keresése |
Hitelesítő adatok visszavonása | Adott hitelesítő adatok visszavonása |
Ezzel az API-val lekérhet egy adott hitelesítő adatot, és ellenőrizheti az állapotot annak ellenőrzéséhez, hogy visszavonták-e vagy sem.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Példaüzenet
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "valid",
"issuedAt": "2017-09-13T21:59:23.9868631Z"
}
Ellenőrizhető hitelesítő adatokat kereshet adott indexjogcímekkel. Mivel csak kivonatot tárol, meg kell keresnie a megadott számított értéket. A használni kívánt algoritmus a következő: Base64Encode(SHA256(contractid + jogcímérték)) A C#-ban egy példa a következőképpen néz ki:
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 );
}
Az alábbi kérés bemutatja, hogyan adhat hozzá számított értéket a kérelem szűrőparaméteréhez. Jelenleg csak a filter=indexclaimhash eq formátum támogatott.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ehhez a metódushoz ne adjon meg kérelemtörzset.
Példaüzenet
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"
}
]
}
Ez az API lehetővé teszi egy adott hitelesítő adat visszavonását, miután a keresési API-val rákeresett a hitelesítő adatokra, a hitelesítő adatok visszavonhatók az adott hitelesítő azonosító megadásával.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ehhez a metódushoz ne adjon meg kérelemtörzset.
HTTP/1.1 204 No Content
Content-type: application/json
Ez a metódus teljesen eltávolítja a bérlő ellenőrizhető hitelesítőadat-szolgáltatásának összes példányát. Eltávolítja az összes konfigurált szerződést. Nem ellenőrizhető minden kiadott ellenőrizhető hitelesítő adat visszavonása. Ez a művelet nem vonható vissza.
Figyelmeztetés
Ez a művelet nem vonható vissza, és érvényteleníti az összes kiállított ellenőrizhető hitelesítő adatot és létrehozott szerződést.
POST /v1.0/verifiableCredentials/optout
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Ne adjon meg kérelemtörzset ehhez a metódushoz
Példa válaszüzenet
HTTP/1.1 200 OK
Content-type: application/json
OK
Megjegyzés
Ha nem rendelkezik törlési engedélyekkel a Key Vaulton, hibaüzenetet küldünk, és továbbra is elutasítjuk