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.

Základní adresa URL

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.

Ověřování

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.

Nosné tokeny uživatele

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í.

Nosné tokeny aplikací

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/.defaultprostř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.

Onboarding

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.

Žádost HTTP

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é.

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Pro tuto metodu nezadávajte tělo požadavku.

Návratová zpráva

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ě.

Úřady

Tento koncový bod lze použít k vytvoření nebo aktualizaci ověřitelné instance služby Credential.

Metody

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

Získání autority

Načtěte vlastnosti nakonfigurované autority nebo ověřitelné instance služby přihlašovacích údajů.

Žádost HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId

:authorityId Nahraďte hodnotou jedné z nakonfigurovaných autorit.

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Nezadávejte text požadavku pro tuto metodu

Zpráva odpovědi

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.

Typ autority

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

didModel – typ

Web

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

keyVaultMetadata – typ

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

Seznam citací

Získání všech nakonfigurovaných autorit nebo ověřitelných služeb přihlašovacích údajů pro tohoto tenanta

Žádost HTTP

GET /v1.0/verifiableCredentials/authorities

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Pro tuto metodu nezadávajte tělo požadavku.

Zpráva odpovědi

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/"
            }
        }
    ]
}

Vytvoření autority

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.

Žádost HTTP

POST /v1.0/verifiableCredentials/authorities

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

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/"
  }
}

Zpráva odpovědi

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/"
    }
}

Poznámky

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.

Aktualizovat autoritu

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ů.

Žádost HTTP

PATCH /v1.0/verifiableCredentials/authorities/:authorityId

Nahraďte hodnotu :authorityId hodnotou ID autority, kterou chcete aktualizovat.

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

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"
}

Odstranit autoritu

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č.

Žádost HTTP

DELETE /beta/verifiableCredentials/authorities/:authorityId

Nahraďte hodnotu :authorityId hodnotou ID autority, které chcete odstranit.

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Bez textu požadavku

Zpráva odpovědi

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"
    }
}

Známá konfigurace DID

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.

Žádost HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Potřebujete zadat jednu z domén v propojených doménách zadané autority.

{
    "domainUrl":"https://atest/"
}

Zpráva odpovědi

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/"
  }
}

Poznámky

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>..."
    ]
}

Generování dokumentu DID

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í.

Žádost HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Pro tuto metodu nezadávajte tělo požadavku.

Zpráva odpovědi

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"
    ]
}

Poznámka

Vyžaduje, aby volající měl oprávnění k seznamu klíčů v cílovém trezoru klíčů.

Ověření dobře známé konfigurace DID

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ý.

Žádost HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Pro tuto metodu nezadávajte tělo požadavku.

Zpráva odpovědi

HTTP/1.1 204 No Content
Content-type: application/json

Otočení podpisového klíče

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í.

Žádost HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/signingKeys/rotate

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Pro tuto metodu nezadávajte tělo požadavku.

Zpráva odpovědi

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
}

Synchronizace s dokumentem DID

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í.

Žádost HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/didInfo/synchronizeWithDidDocument

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Pro tuto metodu nezadávajte tělo požadavku.

Zpráva odpovědi

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
}

Smlouvy

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

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

Získání kontraktu

Žádost HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId

:authorityId Nahraďte a :contractId za správnou hodnotu autority a smlouvy.

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Pro tuto metodu nezadávajte tělo požadavku.

Zpráva odpovědi

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.

Typ kontraktu

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 .

typ rulesModel

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.

typ ověření identity

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.

idTokenAttestation – typ

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

idTokenHintAttestation – typ

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

ověřitelný typPresentationAttestation

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

selfIssuedAttestation – typ

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

accessTokenAttestation – typ

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 pro mappings vlastnost: givenName, displayName, preferredLanguage, userPrincipalName, surname, mail, jobTitle. photo

typ claimMapping

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

customStatusEndpoint – typ

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"
        ]
    }
}

displayModel – typ

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ů

displayCredential type

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

displayCredentialLogo – typ

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

displayConsent – typ

Vlastnost Type Description
title string název souhlasu
instructions string doplňkový text, který se má použít při zobrazení souhlasu

displayClaims – typ

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"
                }
            ]
        }
    ]
}

Výpis kontraktů

Toto rozhraní API obsahuje seznam všech kontraktů nakonfigurovaných v aktuálním tenantovi pro zadanou autoritu.

Žádost HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Pro tuto metodu nezadávajte tělo požadavku.

Zpráva odpovědi

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}]
        }
    ]
}

Vytvoření kontraktu

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í.

Žádost HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Příklad požadavku

{
    "name": "ExampleContractName1",
    "rules": "<rules JSON>",
    "displays": [{<display JSON}],
}

Zpráva odpovědi

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://..."
}

Aktualizace kontraktu

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
}

Zpráva odpovědi

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
}

Přihlašovací údaje

Tento koncový bod umožňuje vyhledat vydané ověřitelné přihlašovací údaje, zkontrolovat stav odvolání a odvolat přihlašovací údaje.

Metody

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ů

Získání 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.

Požadavek HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialId

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Zpráva odpovědi

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"
}

Prohledat přihlašovací údaje

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.

Žádost HTTP

GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials?filter=indexclaimhash eq {hashedsearchclaimvalue}

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Pro tuto metodu nezadávajte tělo požadavku.

Zpráva odpovědi

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"
        }
    ]
}

Odvolání přihlašovacích údajů

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ů.

Žádost HTTP

POST /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId/credentials/:credentialid/revoke

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Pro tuto metodu nezadávajte tělo požadavku.

Zpráva odpovědi

HTTP/1.1 204 No Content
Content-type: application/json

Odhlášení

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.

Požadavek HTTP

POST /v1.0/verifiableCredentials/optout

Záhlaví žádosti

Hlavička Hodnota
Autorizace Nosný (token). Požaduje se
Content-Type application/json

Text požadavku

Nezadávejte text požadavku pro tuto metodu

Zpráva odpovědi

Příklad zprávy odpovědi

HTTP/1.1 200 OK
Content-type: application/json

OK

Poznámka

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.

Další kroky