Ověřitelné rozhraní API pro správu přihlašovacích údajů
Rozhraní API pro správu Ověřené ID Microsoft Entra umožňuje spravovat všechny aspekty ověřitelné služby přihlašovacích údajů. Nabízí způsob, jak nastavit zcela novou službu, spravovat a vytvářet ověřitelné smlouvy s přihlašovacími údaji, odvolat ověřitelné přihlašovací údaje a zcela zrušit i službu.
Rozhraní API je určené pro vývojáře, kteří mají rozhraní RESTful API a dostatečná oprávnění k povolení služby v tenantovi Microsoft Entra.
Rozhraní API pro správu je server přes PROTOKOL HTTPS. Všechny adresy URL odkazované v dokumentaci mají následující základ: https://verifiedid.did.msidentity.com
.
Rozhraní API je chráněné prostřednictvím ID Microsoft Entra a používá nosné tokeny OAuth2. Přístupový token může být pro uživatele nebo pro aplikaci.
Registrace aplikace musí mít oprávnění rozhraní API pro Verifiable Credentials Service Admin
získání přístupového tokenu, pro který by aplikace měla použít obor 6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access
. Přístupový token musí být pro uživatele s rolí globálního správce nebo správce zásad ověřování. Uživatel s globální čtenář rolí může provádět volání rozhraní API jen pro čtení.
Služba Verifiable Credentials Service Admin
podporuje následující oprávnění aplikace.
Oprávnění | Popis |
---|---|
OvěřitiableCredential.Authority.ReadWrite | Oprávnění k objektům autority pro čtení a zápis |
OvěřitiableCredential.Contract.ReadWrite | Oprávnění ke čtení a zápisu objektů kontraktů |
OvěřitelnéCredential.Credential.Search | Oprávnění k vyhledání přihlašovacích údajů, které se mají odvolat |
OvěřitiableCredential.Credential.Revoke | Oprávnění k odvolání dříve vydaných přihlašovacích údajů |
OvěřitelnéCredential.Network.Read | Oprávnění ke čtení položek ze sítě ověřených ID |
Registrace aplikace musí mít oprávnění rozhraní API a Verifiable Credentials Service Admin
požadovaná oprávnění z výše uvedené tabulky. Při získávání přístupového tokenu by aplikace měla používat obor 6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default
prostřednictvím toku přihlašovacích údajů klienta.
Pokud chce aplikace vytvořit novou autoritu, potřebuje dvě věci. Nejprve registrace aplikace potřebuje VerifiableCredential.Authority.ReadWrite
oprávnění. Za druhé, aplikace potřebuje mít Create Key
oprávnění v zásadách přístupu ke službě Key Vaults. Pokud aplikace jen pro čtení a zápisy existující autority nepotřebuje oprávnění ke službě Key Vault.
Toto rozhraní API vám pomůže vytvořit nové prostředí, aby bylo možné nastavit nové autority. To se dá aktivovat ručně tak, že na webu Azure Portal přejdete na stránku Ověřitelné přihlašovací údaje. Toto rozhraní API stačí volat jen jednou a jenom v případě, že chcete nastavit úplně nové prostředí jenom s rozhraním API.
POST /v1.0/verifiableCredentials/onboard
Pomocí tohoto koncového bodu dokončete zřizování ověřitelné služby přihlašovacích údajů ve vašem tenantovi. Systém vytvoří zbytek instančních objektů, pokud ještě nejsou zřízené.
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Pro tuto metodu nezadávajte tělo požadavku.
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"
}
Opakované volání tohoto rozhraní API vede ke stejné návratové zprávě.
Tento koncový bod lze použít k vytvoření nebo aktualizaci ověřitelné instance služby Credential.
Metody | Návratový typ | Popis |
---|---|---|
Získat autoritu | Autorita | Čtení vlastností autority |
List Authority | Pole autority | Získání seznamu všech nakonfigurovaných autorit nebo ověřitelných služeb přihlašovacích údajů |
Vytvořit autoritu | Autorita | Vytvoření nové autority |
Aktualizovat autoritu | Autorita | Aktualizovat autoritu |
Odstranit autoritu | Autorita | Odstranit autoritu |
Generování dobře známé konfigurace DID | ||
Generování dokumentu DID | ||
Ověření dobře známé konfigurace DID | ||
Otočení podpisového klíče | Autorita | Otočení podpisového klíče |
Synchronizace s dokumentem DID | Autorita | Synchronizace dokumentu DID s novým podpisovým klíčem |
Načtěte vlastnosti nakonfigurované autority nebo ověřitelné instance služby přihlašovacích údajů.
GET /v1.0/verifiableCredentials/authorities/:authorityId
:authorityId
Nahraďte hodnotou jedné z nakonfigurovaných autorit.
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Nezadávejte text požadavku pro tuto metodu
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/"
}
}
Odpověď obsahuje následující vlastnosti.
Vlastnost | Type | Description |
---|---|---|
Id |
string | Automaticky vygenerované jedinečné ID, které lze použít k načtení nebo aktualizaci konkrétní instance ověřitelné služby přihlašovacích údajů |
name |
string | Popisný název této instance ověřitelné služby přihlašovacích údajů |
status |
string | stav služby, tato hodnota bude vždy enabled |
didModel | didModel | Informace o DID a klíčích |
keyVaultMetadata | keyVaultMeta data | Informace o použité službě Key Vault |
Vlastnost | Type | Description |
---|---|---|
did |
string | DID pro tuto ověřitelnou instanci služby přihlašovacích údajů |
signingKeys |
Řetězcové pole | Adresa URL podpisového klíče |
linkedDomainUrls |
Řetězcové pole | Domény propojené s tímto objektem DID, které očekávají jednu položku |
didModel | didModel | Informace o DID a klíčích |
didDocumentStatus |
string | stav DID, hodnota je vždy published pro tuto metodu |
Vlastnost | Type | Description |
---|---|---|
subscriptionId |
string | Předplatné Azure, které se nachází ve službě Key Vault |
resourceGroup |
string | název skupiny prostředků z této služby Key Vault |
resourceName |
string | Název trezoru klíčů |
resourceUrl |
string | Adresa URL pro tuto službu Key Vault |
Získání všech nakonfigurovaných autorit nebo ověřitelných služeb přihlašovacích údajů pro tohoto tenanta
GET /v1.0/verifiableCredentials/authorities
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Pro tuto metodu nezadávajte tělo požadavku.
Zpráva odpovědi je pole citací .
Příklad:
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/"
}
}
]
}
Toto volání vytvoří nový privátní klíč, obnovovací klíč a aktualizační klíč, uloží tyto klíče do zadané služby Azure Key Vault a nastaví oprávnění k tomuto trezoru klíčů pro ověřitelnou službu přihlašovacích údajů a vytvoří nový KÓD DID s odpovídajícím dokumentem DID.
POST /v1.0/verifiableCredentials/authorities
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
V textu požadavku zadejte reprezentaci JSON následujících možností:
Vlastnost | Type | Description |
---|---|---|
name |
string | Zobrazovaný název této instance služby |
linkedDomainUrl |
string | Doména propojená s touto službou DID |
didMethod |
string | Musí být web |
keyVaultMetadata |
keyVaultMetadata | meta data pro konkrétní trezor klíčů |
Příklad zprávy:
{
"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/"
}
}
Po úspěšném dokončení zprávy odpovědi obsahuje název autority .
Příklad zprávy pro 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říklad zprávy pro 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/"
}
}
Můžete vytvořit více autorit s vlastními DID a privátními klíči, které nebudou viditelné v uživatelském rozhraní webu Azure Portal. V současné době podporujeme pouze 1 autoritu. Netestovali jsme všechny scénáře s více vytvořenými autoritami. Pokud to zkoušíte, dejte nám vědět, jaké máte zkušenosti.
Tuto metodu lze použít k aktualizaci zobrazovaného názvu této konkrétní instance ověřitelné služby přihlašovacích údajů.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId
Nahraďte hodnotu :authorityId
hodnotou ID autority, kterou chcete aktualizovat.
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
V textu požadavku zadejte následující reprezentaci JSON.
Vlastnost | Type | Description |
---|---|---|
name |
string | Zobrazovaný název této instance služby |
Ukázková zpráva
{
"name":"ExampleIssuerName"
}
Tuto metodu lze použít k odstranění autority. V současné době je možné odstranit pouze did:ion
autority. Když odstraníte autoritu, všechny vydané ověřené ID přihlašovací údaje se stanou neplatnými a už se nedají ověřit, protože vydávající autorita je pryč.
DELETE /beta/verifiableCredentials/authorities/:authorityId
Nahraďte hodnotu :authorityId
hodnotou ID autority, které chcete odstranit.
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Bez textu požadavku
Příklad zprávy odpovědi:
Úspěšná odpověď na odstranění autority
HTTP/1.1 200 OK
Pokud odstranění autority proběhlo úspěšně, ale vyčištění klíčů služby Azure Key Vault selhalo, zobrazí se následující odpověď.
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"
}
}
Metoda generateWellknownDidConfiguration
vygeneruje podepsaný did-configuration.json soubor. Soubor se musí nahrát do .well-known
složky v kořenovém adresáři webu hostovaného pro doménu v propojené doméně této ověřitelné instance přihlašovacích údajů. Pokyny najdete tady.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Potřebujete zadat jednu z domén v propojených doménách zadané autority.
{
"domainUrl":"https://atest/"
}
Příklad zprávy odpovědi:
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>..."
]
}
Uložte tento výsledek s názvem souboru did-configuration.json a nahrajte tento soubor do správné složky a webu. Pokud zadáte doménu, která není propojená s tímto dokumentem DID/DID, zobrazí se chyba:
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/"
}
}
Více identifikátorů DID můžete nasměrovat na stejnou doménu. Pokud zvolíte tuto konfiguraci, musíte zkombinovat vygenerované tokeny a vložit je do stejného did-configuration.json souboru. Soubor obsahuje pole těchto tokenů.
Příklad:
{
"@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
"linked_dids": [
"eyJhbG..token1...<SNIP>...",
"eyJhbG..token2...<SNIP>..."
]
}
Toto volání vygeneruje dokument DID použitý pro identifikátory DID:WEB. Po vygenerování tohoto dokumentu DID musí správce umístit soubor do https://domain/.well-known/did.json umístění.
POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Pro tuto metodu nezadávajte tělo požadavku.
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"
]
}
Vyžaduje, aby volající měl oprávnění k seznamu klíčů v cílovém trezoru klíčů.
Toto volání zkontroluje nastavení DID. Stáhne známou konfiguraci DID a ověří, jestli se používá správná funkce DID, a podpis je správný.
POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Pro tuto metodu nezadávajte tělo požadavku.
HTTP/1.1 204 No Content
Content-type: application/json
Podpisový klíč pro obměna vytvoří nový privátní klíč pro did:web authority. Dokument DID by se měl znovu zaregistrovat, aby odrážel aktualizaci. Po dokončení synchronizaceWithDidDocument řekne systému, aby začal používat nový klíč pro podepisování.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Pro tuto metodu nezadávajte tělo požadavku.
Změní se didDocumentStatus
na 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
}
Po otočení podpisového klíče by se dokument DID měl znovu zaregistrovat , aby odrážel aktualizaci. Po dokončení synchronizaceWithDidDocument řekne systému, aby začal používat nový klíč pro podepisování.
POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Pro tuto metodu nezadávajte tělo požadavku.
Změní didDocumentStatus
se z outOfSync
na published
úspěšné volání.
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
}
Tento koncový bod umožňuje vytvářet nové kontrakty a aktualizovat stávající kontrakty. Kontrakty se skládají ze dvou částí reprezentovaných dvěma definicemi JSON. Informace o tom, jak navrhnout a vytvořit kontrakt ručně, najdete tady.
- Definici zobrazení používají správci k řízení vzhledu ověřitelných přihlašovacích údajů, například barvy pozadí, loga a názvu ověřitelných přihlašovacích údajů. Tento soubor obsahuje také deklarace identity, které je potřeba uložit uvnitř ověřitelných přihlašovacích údajů.
- Definice pravidel obsahuje informace o tom, jak shromažďovat a shromažďovat ověření identity, jako jsou samoobslužné deklarace identity, další ověřitelné přihlašovací údaje jako vstup nebo token ID přijatý poté, co se uživatel přihlásil ke zprostředkovateli identity kompatibilnímu s OIDC.
Metody | Návratový typ | Popis |
---|---|---|
Získání kontraktu | Smlouva | Čtení vlastností kontraktu |
Výpis kontraktů | Kolekce kontraktů | Získání seznamu všech nakonfigurovaných kontraktů |
Vytvoření kontraktu | Smlouva | Vytvoření nového kontraktu |
Aktualizace kontraktu | Smlouva | Aktualizace kontraktu |
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId
:authorityId
Nahraďte a :contractId
za správnou hodnotu autority a smlouvy.
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Pro tuto metodu nezadávajte tělo požadavku.
příklad zprávy:
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
}
Odpověď obsahuje následující vlastnosti.
Vlastnost | Type | Description |
---|---|---|
Id |
string | ID smlouvy |
name |
string | Popisný název této smlouvy |
status |
string | Vždy Enabled |
manifestUrl |
string | Adresa URL kontraktu použitého v žádosti o vystavení |
issueNotificationEnabled |
boolean | nastavená na hodnotu True, pokud budou uživatelé upozorněni, že je tento virtuální počítač připravený k vydání |
issueNotificationAllowedToGroupOids |
pole řetězců groupId | pole ID skupin, kterým budou tyto přihlašovací údaje nabídnuty |
availableInVcDirectory |
boolean | Je tato smlouva publikovaná v ověřitelné síti přihlašovacích údajů. |
pravidla | rulesModel | definice pravidel |
zobrazuje | displayModel array | zobrazení definic |
allowOverrideValidityIntervalOnIssuance |
boolean | Pokud volání rozhraní API createIssuanceRequest může přepsat vypršení platnosti přihlašovacích údajů. To platí jenom pro toky idTokenHint . |
Vlastnost | Type | Popis |
---|---|---|
attestations |
Osvědčení | popis podporovaných vstupů pro pravidla |
validityInterval |
Číslo | tato hodnota zobrazuje životnost přihlašovacích údajů. |
vc |
Pole vcType | typy pro tuto smlouvu |
customStatusEndpoint |
[customStatusEndpoint] (typ #customstatusendpoint) (volitelné) | koncový bod stavu, který se má zahrnout do ověřitelných přihlašovacích údajů pro tento kontrakt |
Pokud vlastnost vlastnosti customStatusEndpoint
není zadaná, anonymous
použije se koncový bod stavu.
Vlastnost | Type | Popis |
---|---|---|
idTokens |
idTokenAttestation (pole) (volitelné) | popisuje vstupy tokenů ID. |
idTokenHints |
idTokenHintAttestation (pole) (volitelné) | popisuje vstupy nápovědy tokenu ID. |
presentations |
ověřitelné ověřováníPresentationAttestation (pole) (volitelné) | popisuje ověřitelné vstupy prezentací. |
selfIssued |
selfIssuedAttestation (pole) (volitelné) | popisuje samostavěné vstupy. |
accessTokens |
accessTokenAttestation (pole) (volitelné) | popisuje vstupy přístupového tokenu. |
Vlastnost | Type | Popis |
---|---|---|
mapping |
deklarace identity ( volitelné) | pravidla pro mapování vstupních deklarací na výstupní deklarace identity v ověřitelných přihlašovacích údajích |
configuration |
řetězec (adresa URL) | umístění konfiguračního dokumentu zprostředkovatele identity |
clientId |
string | ID klienta, které se má použít při získávání tokenu ID |
redirectUri |
string | identifikátor URI přesměrování, který se má použít při získání tokenu ID, MUSÍ BÝT vcclient://openid/ |
scope |
string | seznam oborů oddělených mezerami, které se mají použít při získání tokenu ID |
required |
logická hodnota (výchozí false) | označující, zda je toto ověření povinné, nebo ne |
Vlastnost | Type | Popis |
---|---|---|
mapping |
deklarace identity ( volitelné) | pravidla pro mapování vstupních deklarací na výstupní deklarace identity v ověřitelných přihlašovacích údajích |
required |
logická hodnota (výchozí false) | označující, zda je toto ověření povinné, nebo ne |
trustedIssuers |
řetězec (pole) | seznam identifikátorů DID povolených k vydání ověřitelných přihlašovacích údajů pro tuto smlouvu |
Vlastnost | Type | Popis |
---|---|---|
mapping |
deklarace identity ( volitelné) | pravidla pro mapování vstupních deklarací na výstupní deklarace identity v ověřitelných přihlašovacích údajích |
credentialType |
řetězec (volitelné) | požadovaný typ přihlašovacích údajů vstupu |
required |
logická hodnota (výchozí false) | označující, zda je toto ověření povinné, nebo ne |
trustedIssuers |
řetězec (pole) | seznam identifikátorů DID povolených k vydání ověřitelných přihlašovacích údajů pro tuto smlouvu |
Vlastnost | Type | Popis |
---|---|---|
mapping |
deklarace identity ( volitelné) | pravidla pro mapování vstupních deklarací na výstupní deklarace identity v ověřitelných přihlašovacích údajích |
required |
logická hodnota (výchozí false) | označující, zda je toto ověření povinné, nebo ne |
Vlastnost | Type | Popis |
---|---|---|
mapping |
deklarace identity ( volitelné) | pravidla pro mapování vstupních deklarací na výstupní deklarace identity v ověřitelných přihlašovacích údajích |
required |
logická hodnota (výchozí false) | označující, zda je toto ověření povinné, nebo ne |
Podporované
inputClaim
hodnoty promappings
vlastnost:givenName
,displayName
,preferredLanguage
,userPrincipalName
,surname
,jobTitle
.photo
Vlastnost | Type | Description |
---|---|---|
inputClaim |
string | název deklarace identity, která se má použít ze vstupu |
outputClaim |
string | název deklarace identity v ověřitelných přihlašovacích údajích |
indexed |
logická hodnota (výchozí false) | označující, zda se hodnota této deklarace identity používá k vyhledávání; Pro daný kontrakt může být indexován pouze jeden objekt clientMapping. |
required |
logická hodnota (výchozí false) | označující, zda je toto mapování povinné, nebo ne |
type |
řetězec (volitelné) | typ deklarace identity |
Vlastnost | Type | Popis |
---|---|---|
url |
řetězec (adresa URL) | adresa URL vlastního koncového bodu stavu |
type |
string | typ koncového bodu |
Příklad:
"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"
]
}
}
Vlastnost | Type | Description |
---|---|---|
locale |
string | národní prostředí tohoto zobrazení |
credential |
displayCredential | vlastnosti zobrazení ověřitelných přihlašovacích údajů |
consent |
displayConsent | doplňující data při vydání ověřitelných přihlašovacích údajů |
claims |
displayClaims array | popisky deklarací identity zahrnuté do ověřitelných přihlašovacích údajů |
Vlastnost | Type | Description |
---|---|---|
title |
string | název přihlašovacích údajů |
issuedBy |
string | název vystavitele přihlašovacích údajů |
backgroundColor |
číslo (šestnáctkové) | barva pozadí přihlašovacích údajů v šestnáctkovém formátu, například #FFAABB |
textColor |
číslo (šestnáctkové) | textová barva přihlašovacích údajů v šestnáctkovém formátu, například #FFAABB |
description |
string | doplňkový text zobrazený společně s jednotlivými přihlašovacími údaji |
logo |
displayCredentialLogo | logo, které se má použít pro přihlašovací údaje |
Vlastnost | Type | Popis |
---|---|---|
uri |
string (URI) | uri loga. Pokud se jedná o adresu URL, musí být přístupná prostřednictvím veřejného internetu anonymně. |
description |
string | popis loga |
Vlastnost | Type | Description |
---|---|---|
title |
string | název souhlasu |
instructions |
string | doplňkový text, který se má použít při zobrazení souhlasu |
Vlastnost | Type | Description |
---|---|---|
label |
string | popisek deklarace identity v zobrazení |
claim |
string | název deklarace identity, na kterou se popisek vztahuje |
type |
string | typ deklarace identity |
description |
řetězec (volitelné) | popis deklarace identity |
Příklad:
{
"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"
}
]
}
]
}
Toto rozhraní API obsahuje seznam všech kontraktů nakonfigurovaných v aktuálním tenantovi pro zadanou autoritu.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Pro tuto metodu nezadávajte tělo požadavku.
příklad zprávy:
{
"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}]
}
]
}
Při vytváření kontraktu musí být název v tenantovi jedinečný. V případě, že jste vytvořili více autorit, musí být název smlouvy jedinečný ve všech autoritách. Název kontraktu bude součástí adresy URL smlouvy, která se používá v žádostech o vystavení.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Příklad požadavku
{
"name": "ExampleContractName1",
"rules": "<rules JSON>",
"displays": [{<display JSON}],
}
Příklad zprávy:
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://..."
}
Toto rozhraní API umožňuje aktualizovat kontrakt.
PATCH /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractid
Příklad požadavku:
{
"rules": "<rules JSON>",
"displays": [{<display JSON}],}
"availableInVcDirectory": true
"allowOverrideValidityIntervalOnIssuance": true
}
Příklad zprávy:
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
}
Tento koncový bod umožňuje vyhledat vydané ověřitelné přihlašovací údaje, zkontrolovat stav odvolání a odvolat přihlašovací údaje.
Metody | Návratový typ | Popis |
---|---|---|
Získání přihlašovacích údajů | Reference | Čtení vlastností přihlašovacích údajů |
Prohledat přihlašovací údaje | Kolekce přihlašovacích údajů | Prohledání seznamu přihlašovacích údajů s konkrétní hodnotou deklarace identity |
Odvolání přihlašovacích údajů | Odvolání konkrétních přihlašovacích údajů |
Toto rozhraní API umožňuje načíst konkrétní přihlašovací údaje a zkontrolovat stav a zjistit, jestli je odvolaný nebo ne.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Ukázková zpráva
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "urn:pic:aea42fb3724b4ef08bd2d2712e79bda2",
"contractId": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhdGVzdDM",
"status": "valid",
"issuedAt": "2017-09-13T21:59:23.9868631Z"
}
Můžete vyhledat ověřitelné přihlašovací údaje s konkrétními deklaracemi indexu. Protože je uložena pouze hodnota hash, musíte vyhledat konkrétní počítanou hodnotu. Algoritmus, který potřebujete použít, je: Base64Encode(SHA256(contractid + hodnota deklarace identity)) Příklad v jazyce C# vypadá takto:
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 );
}
Následující požadavek ukazuje, jak přidat počítanou hodnotu do parametru filtru požadavku. V tuto chvíli se podporuje pouze formát filter=indexclaimhash eq.
GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Pro tuto metodu nezadávajte tělo požadavku.
Ukázková zpráva
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"
}
]
}
Toto rozhraní API umožňuje odvolat konkrétní přihlašovací údaje po vyhledání přihlašovacích údajů pomocí vyhledávacího rozhraní API, které přihlašovací údaje můžou být odvolány zadáním konkrétního ID přihlašovacích údajů.
POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Pro tuto metodu nezadávajte tělo požadavku.
HTTP/1.1 204 No Content
Content-type: application/json
Tato metoda zcela odebere všechny instance ověřitelné služby přihlašovacích údajů v tomto tenantovi. Odebere všechny nakonfigurované kontrakty. U všech vydaných ověřitelných přihlašovacích údajů není možné zkontrolovat odvolání. Tuto akci nelze vrátit zpět.
Upozornění
Tuto akci nelze vrátit zpět a zneplatní všechny vydané ověřitelné přihlašovací údaje a vytvořené kontrakty.
POST /v1.0/verifiableCredentials/optout
Hlavička | Hodnota |
---|---|
Autorizace | Nosný (token). Požaduje se |
Content-Type | application/json |
Nezadávejte text požadavku pro tuto metodu
Příklad zprávy odpovědi
HTTP/1.1 200 OK
Content-type: application/json
OK
Poznámka
Pokud nemáte oprávnění k odstranění ve službě Key Vault, vrátíme chybovou zprávu a přesto se odhlásíme.