Megosztás a következőn keresztül:


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_accesskell 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/.defaultkell 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 a mappings következők: givenName, displayName, , preferredLanguage, userPrincipalNamesurname, mail, 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

Következő lépések