Ellenőrizhető hitelesítő adatok rendszergazdai API
A Microsoft Entra Ellenőrzött azonosító Rendszergazda 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
Kiindulási URL-cím
A Rendszergazda 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
.
Hitelesítés
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.
Felhasználói jogkivonatok
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.
Alkalmazás tulajdonosi jogkivonatai
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.
Előkészítés
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.
HTTP-kérelem
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.
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Ehhez a metódushoz ne adjon meg kérelemtörzset.
Üzenet visszaküldése
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.
Hatóságok
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
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 |
Szolgáltató lekérése
Egy konfigurált szolgáltató vagy ellenőrizhető hitelesítőadat-szolgáltatáspéldány tulajdonságainak lekérése.
HTTP-kérelem
GET /v1.0/verifiableCredentials/authorities/:authorityId
Cserélje le az :authorityId
egyik konfigurált hatóság értékét.
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Ne adjon meg kérelemtörzset ehhez a metódushoz
Válaszüzenet
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.
Szolgáltató típusa
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 |
didModel típus
Webes
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 |
keyVaultMetadata típus
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 |
Hatóságok listázása
A bérlő összes konfigurált hatóságának vagy ellenőrizhető hitelesítő adatainak lekérése
HTTP-kérelem
GET /v1.0/verifiableCredentials/authorities
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Ehhez a metódushoz ne adjon meg kérelemtörzset.
Válaszüzenet
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/"
}
}
]
}
Szolgáltató létrehozása
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.
HTTP-kérelem
POST /v1.0/verifiableCredentials/authorities
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
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/"
}
}
Válaszüzenet
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/"
}
}
Megjegyzések
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.
Frissítési szolgáltató
Ezzel a módszerrel frissíthető az ellenőrizhető hitelesítőadat-szolgáltatás ezen példányának megjelenítendő neve.
HTTP-kérelem
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.
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
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"
}
Szolgáltató törlése
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.
HTTP-kérelem
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.
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Nincs kérelemtörzs
Válaszüzenet
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"
}
}
Jól ismert DID-konfiguráció
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.
HTTP-kérelem
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Meg kell adnia az egyik tartományt a megadott szolgáltató linkedDomains tartományaiban.
{
"domainUrl":"https://atest/"
}
Válaszüzenet
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/"
}
}
Megjegyzések
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>..."
]
}
DID-dokumentum létrehozása
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.
HTTP-kérelem
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Ehhez a metódushoz ne adjon meg kérelemtörzset.
Válaszüzenet
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"
]
}
Megjegyzés
A hívónak rendelkeznie kell a KEY List engedélyekkel a célkulcstartón.
Jól ismert DID-konfiguráció ellenőrzése
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.
HTTP-kérelem
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Ehhez a metódushoz ne adjon meg kérelemtörzset.
Válaszüzenet
HTTP/1.1 204 No Content
Content-type: application/json
Aláírókulcs elforgatása
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.
HTTP-kérelem
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérelem törzse
Ehhez a metódushoz ne adjon meg kérelemtörzset.
Válaszüzenet
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
}
Szinkronizálás DID-dokumentummal
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.
HTTP-kérelem
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérelem törzse
Ehhez a metódushoz ne adjon meg kérelemtörzset.
Válaszüzenet
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
}
Szerződések
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
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 |
Szerződés lekérése
HTTP-kérelem
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.
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Ehhez a metódushoz ne adjon meg kérelemtörzset.
Válaszüzenet
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:
Szerződés típusa
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. |
rulesModel típus
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.
igazolások típusa
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 |
idTokenAttestation type
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 |
idTokenHintAttestation típus
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 |
verifiablePresentationAttestation type
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 |
selfIssuedAttestation típus
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 |
accessTokenAttestation type
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
claimMapping típus
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 |
customStatusEndpoint-típus
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"
]
}
}
displayModel típus
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 |
displayCredential type
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 |
displayCredentialLogo típus
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 |
displayConsent típus
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 |
displayClaims típus
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.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png"
}
},
"consent": {
"instructions": "Please login with your bankofWoodgrove account to receive this credential.",
"title": "Do you want to accept the verifiedbankofWoodgrove Identity?"
},
"claims": [
{
"claim": "vc.credentialSubject.givenName",
"label": "Name",
"type": "String"
},
{
"claim": "vc.credentialSubject.familyName",
"label": "Surname",
"type": "String"
}
]
}
]
}
Szerződések listázása
Ez az API felsorolja a megadott szolgáltató aktuális bérlőjében konfigurált összes szerződést.
HTTP-kérelem
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Ehhez a metódushoz ne adjon meg kérelemtörzset.
Válaszüzenet
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ása
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.
HTTP-kérelem
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Példa kérésre:
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
Válaszüzenet
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://..."
}
Szerződés frissítése
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
}
Válaszüzenet
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
}
Igazolás
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
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 |
Hitelesítő adatok lekérése
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.
HTTP-kérés
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Válaszüzenet
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"
}
Hitelesítő adatok keresése
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.
HTTP-kérelem
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Ehhez a metódushoz ne adjon meg kérelemtörzset.
Válaszüzenet
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"
}
]
}
Hitelesítő adatok visszavonása
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.
HTTP-kérelem
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Ehhez a metódushoz ne adjon meg kérelemtörzset.
Válaszüzenet
HTTP/1.1 204 No Content
Content-type: application/json
Letiltás
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.
HTTP-kérés
POST /v1.0/verifiableCredentials/optout
Kérésfejlécek
Fejléc | Érték |
---|---|
Engedélyezés | Tulajdonos (jogkivonat). Kötelező |
Content-Type | application/json |
Kérés törzse
Ne adjon meg kérelemtörzset ehhez a metódushoz
Válaszüzenet
Példa válaszüzenet
HTTP/1.1 200 OK
Content-type: application/json
OK
Megjegyzés
Feljegyzés
Ha nem rendelkezik törlési engedélyekkel a Key Vaulton, hibaüzenetet küldünk, és továbbra is elutasítjuk