Specifikace prezentace rozhraní REST API služby Request Service

Poznámka

Ověřitelné přihlašovací údaje služby Azure Active Directory jsou teď Ověřené ID Microsoft Entra a součástí Microsoft Entra řady produktů. Přečtěte si další informace o Microsoft Entra řady řešení identit a začněte v sjednocené Microsoft Entra Centru pro správu.

Ověřené ID Microsoft Entra zahrnuje rozhraní REST API služby request. Toto rozhraní API umožňuje vydávat a ověřovat přihlašovací údaje. Tento článek určuje rozhraní REST API služby request pro žádost o prezentaci. Žádost o prezentaci požádá uživatele, aby představil ověřitelné přihlašovací údaje a pak ověřte přihlašovací údaje. Další článek popisuje , jak volat rozhraní REST API služby request.

Požadavek HTTP

Požadavek na prezentaci rozhraní REST API služby Request service podporuje následující metodu HTTP:

Metoda Poznámky
POST Datová část JSON, jak je uvedeno v tomto článku.

Požadavek na prezentaci rozhraní REST API služby Request Service vyžaduje následující hlavičky HTTP:

Metoda Hodnota
Authorization Připojte přístupový token jako nosný token k autorizační hlavičce v požadavku HTTP. Například, Authorization: Bearer <token>.
Content-Type Application/json

Vytvořte požadavek HTTP POST na rozhraní REST API služby request. Adresa tenantId URL už není potřebná, protože se nachází jako deklarace identity v souboru access_token.

https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest

Následující požadavek HTTP ukazuje požadavek prezentace na rozhraní REST API služby request:

POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Content-Type: application/json
Authorization: Bearer  <token>

{
    "includeQRCode": true,
    "callback": {
    "url": "https://www.contoso.com/api/verifier/presentationCallbac",
    "state": "11111111-2222-2222-2222-333333333333",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

K volání rozhraní REST API služby request je potřeba následující oprávnění. Další informace najdete v tématu Udělení oprávnění pro získání přístupových tokenů.

Typ oprávnění Oprávnění
Aplikace 3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Datová část žádosti o prezentaci

Datová část žádosti o prezentaci obsahuje informace o vaší žádosti o ověření přihlašovacích údajů. Následující příklad ukazuje žádost o prezentaci od konkrétního vystavitele. Výsledek tohoto požadavku vrátí kód QR s odkazem na zahájení procesu prezentace.

{
  "includeQRCode": true,
  "includeReceipt": true,
  "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://www.contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>..."
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

Datová část obsahuje následující vlastnosti.

Parametr Typ Description
includeQRCode Logická hodnota Určuje, zda je kód QR součástí odpovědi tohoto požadavku. Prezentujte kód QR a požádejte uživatele, aby ho naskenuje. Skenování kódu QR spustí ověřovací aplikaci s touto žádostí o prezentaci. Možné hodnoty jsou true (výchozí) nebo false. Když nastavíte hodnotu na falsehodnotu, použijte návratovou url vlastnost k vykreslení hlubokého odkazu.
includeReceipt Logická hodnota Určuje, zda má být potvrzení zahrnuto v odpovědi na tento požadavek. Možné hodnoty jsou true nebo false (výchozí). Potvrzení obsahuje původní datovou část odeslanou z ověřovacího objektu do služby Ověřitelné přihlašovací údaje. Potvrzení je užitečné pro řešení potíží nebo pokud potřebujete získat úplné podrobnosti datové části. Jinak není potřeba tuto hodnotu nastavit na true výchozí hodnotu. OpenId Connect SIOP V požadavku obsahuje potvrzení token ID z původního požadavku.
authority řetězec Váš decentralizovaný identifikátor (DID) vašeho ověřovatele Azure AD tenanta. Další informace najdete v tématu Shromáždění podrobností o tenantovi pro nastavení ukázkové aplikace.
registration RequestRegistration Poskytuje informace o ověřovateli.
callback Zpětného volání Povinné. Umožňuje vývojáři aktualizovat uživatelské rozhraní během ověřitelného procesu prezentace přihlašovacích údajů. Po dokončení procesu pokračujte v procesu po vrácení výsledků do aplikace.
requestedCredentials – kolekce Kolekce objektů RequestCredential .

Typ RequestRegistration

Typ RequestRegistration poskytuje registraci informací pro vystavitele. Typ RequestRegistration obsahuje následující vlastnosti:

Vlastnost Typ Description
clientName řetězec Zobrazovaný název vystavitele ověřitelných přihlašovacích údajů. Toto jméno se uživateli zobrazí v ověřovací aplikaci.

Následující snímek obrazovky ukazuje clientName vlastnost a zobrazovaný název authority (ověřovatele) v žádosti o prezentaci.

Snímek obrazovky znázorňující, jak schválit žádost o prezentaci

Typ zpětného volání

Rozhraní REST API služby Request generuje několik událostí koncového bodu zpětného volání. Tyto události umožňují aktualizovat uživatelské rozhraní a pokračovat v procesu po vrácení výsledků do aplikace. Typ Callback obsahuje následující vlastnosti:

Vlastnost Typ Description
url řetězec Identifikátor URI koncového bodu zpětného volání vaší aplikace. Identifikátor URI musí odkazovat na dostupný koncový bod na internetu, jinak služba vyvolá nečitelný adresu URL zpětného volání. Akceptované vstupy IPv4, IPv6 nebo DNS přeložitelné název hostitele.
state řetězec Koreluje událost zpětného volání se stavem předaným v původní datové části.
headers řetězec Nepovinný parametr. Můžete zahrnout kolekci hlaviček HTTP vyžadovaných přijímajícím koncem zprávy POST. Aktuální podporované hodnoty záhlaví jsou api-key záhlaví nebo Authorization záhlaví. Jakákoli jiná hlavička vyvolá neplatnou chybu záhlaví zpětného volání.

Typ RequestCredential

Poskytuje RequestCredential informace o požadovaných přihlašovacích údaji, které musí uživatel zadat. RequestCredential obsahuje následující vlastnosti:

Vlastnost Typ Description
type řetězec Ověřitelný typ přihlašovacích údajů. Musí type odpovídat typu definovanému v ověřitelném manifestu issuer přihlašovacích údajů (například VerifiedCredentialExpert). Pokud chcete získat manifest vystavitele, přečtěte si téma Shromáždění přihlašovacích údajů a podrobností o prostředí pro nastavení ukázkové aplikace. Zkopírujte adresu URL přihlašovacích údajů problému, otevřete ji ve webovém prohlížeči a zkontrolujte vlastnost ID .
purpose řetězec Zadejte informace o účelu vyžádání těchto ověřitelných přihlašovacích údajů.
acceptedIssuers kolekce řetězců Kolekce identifikátorů DID vystavitelů, která by mohla vystavit typ ověřitelných přihlašovacích údajů, které mohou předměty prezentovat. Pokud chcete získat vystavitele DID, přečtěte si téma Shromáždění přihlašovacích údajů a podrobností o prostředí pro nastavení ukázkové aplikace a zkopírování hodnoty decentralizovaného identifikátoru (DID). acceptedIssuers Pokud je kolekce prázdná, žádost o prezentaci přijme typ přihlašovacích údajů vystavený jakýmkoli vystavitelem.
configuration.validation Configuration.Validation Volitelná nastavení pro ověření prezentace.

Typ Configuration.Validation

Poskytuje Configuration.Validation informace o tom, jak by se měly ověřit uvedené přihlašovací údaje. Obsahuje následující vlastnosti:

Vlastnost Typ Description
allowRevoked Logická hodnota Určuje, jestli se má přijmout odvolání přihlašovacích údajů. Výchozí hodnota je false (neměla by být přijata).
validateLinkedDomain Logická hodnota Určuje, jestli by se měla ověřit propojená doména. Výchozí je false. Nastavení tohoto příznaku znamená false , že jako aplikace předávající strany přijmete přihlašovací údaje z neověřené propojené domény. Nastavení tohoto příznaku znamená true , že propojená doména bude ověřena a budou přijaty pouze ověřené domény.

Úspěšná odpověď

Pokud je tato metoda úspěšná, vrátí kód odpovědi (HTTP 201 Created) a kolekci objektů událostí v textu odpovědi. Následující json ukazuje úspěšnou odpověď:

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid://vc/?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/request/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

Odpověď obsahuje následující vlastnosti:

Vlastnost Typ Description
requestId řetězec ID automaticky vygenerovaného požadavku. Zpětné volání používá stejný požadavek, který umožňuje sledovat žádost o prezentaci a její zpětné volání.
url řetězec Adresa URL, která spustí ověřovací aplikaci a spustí proces prezentace. Tuto adresu URL můžete uživateli prezentovat, pokud nemůže naskenovat kód QR.
expiry integer Označuje, kdy vyprší platnost odpovědi.
qrCode řetězec Kód QR, který může uživatel naskenovat, aby spustil tok prezentace.

Když aplikace obdrží odpověď, musí aplikace uživateli předložit kód QR. Uživatel naskenuje kód QR, který otevře ověřovací aplikaci a spustí proces prezentace.

Chybová odpověď

Pokud dojde k chybě s žádostí, vrátí se odpovědi na chyby a aplikace by se měla správně zpracovat.

Události zpětného volání

Koncový bod zpětného volání se volá, když uživatel naskenuje kód QR, použije přímý odkaz ověřovací aplikace nebo dokončí proces prezentace.

Vlastnost Typ Description
requestId řetězec Namapováno na původní požadavek při publikování datové části do služby Ověřitelné přihlašovací údaje.
requestStatus řetězec Stav vrácený při načtení požadavku ověřovací aplikací. Možné hodnoty:
  • request_retrieved: Uživatel naskenuje kód QR nebo vybral odkaz, který spustí tok prezentace.
  • presentation_verified: Ověření ověřitelných přihlašovacích údajů bylo úspěšně dokončeno.
state řetězec Vrátí hodnotu stavu, kterou jste předali v původní datové části.
subject řetězec Ověřitelný uživatel přihlašovacích údajů UDĚLAL.
issuers array Vrátí pole požadovaných ověřitelných přihlašovacích údajů. Pro každou ověřitelnou přihlašovací údaje poskytuje:
  • Ověřitelné typy přihlašovacích údajů
  • DID vystavitele
  • Deklarace identity se načetly.
  • Ověřitelná doména vystavitele přihlašovacích údajů.
  • Ověřitelný stav ověření domény vystavitele přihlašovacích údajů
  • receipt řetězec Nepovinný parametr. Potvrzení obsahuje původní datovou část odeslanou z peněženky do služby Ověřitelné přihlašovací údaje. Potvrzení by se mělo použít pouze pro řešení potíží nebo ladění. Formát v potvrzení není opravený a může se změnit na základě použité peněženky a verze.

    Následující příklad ukazuje datovou část zpětného volání, když ověřovací aplikace spustí žádost o prezentaci:

    {
        "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
        "requestStatus":"request_retrieved",
        "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58"
    }
    

    Následující příklad ukazuje datovou část zpětného volání po úspěšném dokončení ověřitelné prezentace přihlašovacích údajů:

    {
      "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
      "requestStatus": "presentation_verified",
      "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
      "subject": "did:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>…",
      "verifiedCredentialsData": [
        {
          "issuer": "did:ion:issuer",
          "type": [
            "VerifiableCredential",
            "VerifiedCredentialExpert"
          ],
          "claims": {
            "firstName": "Megan",
            "lastName": "Bowen"
          },
          "credentialState": {
            "revocationStatus": "VALID"
          },
          "domainValidation": {
            "url": "https://contoso.com/"
          }
        }
      ],
      "receipt": {
        "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
        "vp_token": "...",
        "state": "..."
      }
    }
    

    Další kroky

    Zjistěte , jak volat rozhraní REST API služby request.