Sdílet prostřednictvím


Specifikace prezentace rozhraní REST API služby request

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

Žádost HTTP

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

metoda Notes
POST S datovou částí JSON, jak je uvedeno v tomto článku.

Požadavek na prezentaci rozhraní REST API služby request 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 požadavku. Adresa tenantId URL už není potřebná, protože se nachází jako deklarace identity v adrese access_token.

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

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

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

{
    "callback": {
      "url": "https://contoso.com/api/verifier/presentationCallback",
      "state": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

K volání rozhraní REST API vyžádané služby se vyžaduje 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 prezentace obsahuje informace o žádosti o ověřitelné přihlašovací údaje. Následující příklad ukazuje žádost o prezentaci od konkrétního vystavitele. Výsledek této žádosti vrátí kód QR s odkazem pro zahájení procesu prezentace.

{
  "authority": "did:web:verifiedid.contoso.com",
  "includeReceipt": true,
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://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:web:verifiedid.contoso.com"
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

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

Parametr Typ Popis
includeQRCode Logické Nepovinné. Určuje, zda je kód QR zahrnutý v odpovědi na tento požadavek. 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 nebo false (výchozí). Když nastavíte hodnotu na falsehodnotu , použijte návratovou url vlastnost k vykreslení hlubokého odkazu.
includeReceipt Logická hodnota Nepovinné. Určuje, zda má být příjemka zahrnuta v odpovědi na tuto žádost. 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 tuto hodnotu true nemusíte ve výchozím nastavení nastavovat. OpenId Connect SIOP V požadavku obsahuje potvrzení token ID z původního požadavku.
authority string Váš decentralizovaný identifikátor (DID) vašeho ověřitele tenanta Microsoft Entra. 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é 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 Type Description
clientName string Zobrazovaný název ověřovatele ověřitelných přihlašovacích údajů. Toto jméno se uživateli zobrazí v ověřovací aplikaci.
purpose string Nepovinné. Řetězec, který se zobrazí, aby uživatele informoval, proč jsou požadovány ověřitelné přihlašovací údaje.
logoUrl Adresa URL Nepovinné. Adresa URL pro logotyp ověřovatele. Aplikace Authenticator ji nepoužívá.
termsOfServiceUrl Adresa URL Nepovinné. Adresa URL podmínek služby pro ověřovatele. Aplikace Authenticator ji nepoužívá.

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

Snímek obrazovky, který ukazuje, 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 Type Description
url string 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ý kód URL zpětného volání. Akceptované vstupy IPv4, IPv6 nebo DNS přeložitelné názvy hostitelů. Pokud chcete posílit zabezpečení sítě, přečtěte si nejčastější dotazy.
state string Koreluje událost zpětného volání se stavem předaným v původní datové části.
headers string Nepovinné. Můžete zahrnout kolekci hlaviček HTTP vyžadovaných příjmem 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 hlavičky zpětného volání.

Typ RequestCredential

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

Vlastnost Type Description
type string 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 string Nepovinné. Zadejte informace o účelu žádosti o ověřitelné přihlašovací údaje. Aplikace Authenticator ji nepoužívá.
acceptedIssuers kolekce řetězců Nepovinné. Kolekce identifikátorů DID vystavitelů, která by mohla vydat 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á nebo není k dispozici, žá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.
constraints Omezení Nepovinné. Kolekce omezení deklarací identity

Typ Configuration.Validation

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

Vlastnost Type Popis
allowRevoked Logické Nepovinné. Určuje, jestli se mají přijmout odvolané přihlašovací údaje. Výchozí hodnota je false (neměla by být přijata).
validateLinkedDomain Logická hodnota Nepovinné. Určuje, jestli se má propojená doména ověřit. Výchozí hodnota 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ím tohoto příznaku true se ověří propojená doména a akceptují se jenom ověřené domény.
faceCheck faceCheck Nepovinné. Umožňuje požádat o kontrolu živé aktivity během prezentace.

Typ omezení

Typ constraints obsahuje kolekci omezení deklarací identity, která musí být splněna, když peněženka vybere přihlašovací údaje kandidáta. To umožňuje vyžádání přihlašovacích údajů s konkrétní hodnotou deklarace identity. Zadaná omezení budou používat logiku AND, tj. pokud zadáte tři omezení, musí být splněny všechny. Pro každé omezení v kolekci musíte vybrat jeden operand hodnot, obsahuje nebo startsWith. Hodnoty nemohou být regulárními výrazy. Všechna porovnání nerozlišují malá a velká písmena.

Vlastnost Type Description
claimName string Povinné. Název deklarace identity pro omezení Toto je název deklarace identity v ověřitelných přihlašovacích údajích. Viz outputClaim v typu claimMapping.
values kolekce řetězců Sada hodnot, které by se měly shodovat s hodnotou deklarace identity. Pokud zadáte více hodnot, například ["red", "green", "blue"], je to shoda, pokud hodnota deklarace identity v přihlašovacích údajích obsahuje některou z hodnot v kolekci.
contains string Omezení se vyhodnotí jako true, pokud hodnota deklarace identity obsahuje zadanou hodnotu.
startsWith string Omezení se vyhodnotí jako true, pokud hodnota deklarace identity začíná zadanou hodnotou.

FaceCheck type

Typ faceCheck obsahuje informace pro provádění kontroly aktivity během prezentace přihlašovacích údajů. Požadované přihlašovací údaje musí obsahovat fotografii držitele v žádosti s názvem sourcePhotoClaimName. Prezentace bude úspěšná, pokud kontrola aktivity dosáhne úrovně spolehlivosti stejné nebo vyšší, co je zadáno ve vlastnosti matchConfidenceThreshold. Pokud prahová hodnota není splněna, celá prezentace selže.

Vlastnost Type Description
sourcePhotoClaimName string Povinné. Název deklarace identity v přihlašovacích údajích, které obsahují fotografii. Viz outputClaim v typu claimMapping.
matchConfidenceThreshold integer Nepovinné. Důvěrná prahová hodnota pro úspěšnou kontrolu mezi fotkou a daty o liveness. Musí být celé číslo od 50 do 100. Výchozí hodnota je 70.

Ú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/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/presentationRequests/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

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

Vlastnost Type Description
requestId string 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 string Adresa URL, která spustí ověřovací aplikaci a spustí proces prezentace. Tuto adresu URL můžete uživateli prezentovat, pokud kód QR nemůže naskenovat.
expiry integer Označuje, kdy vyprší platnost odpovědi.
qrCode string Kód QR, který může uživatel naskenovat, aby spustil tok prezentace.

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

Chybná odpověď

Pokud dojde k chybě s požadavkem, vrátí se chybové odpovědi 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í aplikaci nebo dokončí proces prezentace.

Vlastnost Type Description
requestId string Namapováno na původní požadavek, když se datová část publikovala do služby Ověřitelné přihlašovací údaje.
requestStatus string 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ěřitelné ověření přihlašovacích údajů bylo úspěšně dokončeno.
  • Li>presentation_error: V prezentaci došlo k chybě.
state string Vrátí hodnotu stavu, kterou jste předali v původní datové části.
subject string Ověřitelný uživatel přihlašovacích údajů PROVEDL.
verifiedCredentialsData pole 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
  • Načetly se deklarace identity.
  • Ověřitelná doména vystavitele přihlašovacích údajů.
  • Ověřitelný stav ověření domény vystavitele přihlašovacích údajů.
  • receipt string Nepovinné. 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 účtenku 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í při spuštění žádosti o prezentaci ověřovací aplikace:

    {
        "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:web:verifiedid.contoso.com",
      "verifiedCredentialsData": [
        {
          "issuer": "did:web:issuer...",
          "type": [
            "VerifiableCredential",
            "VerifiedCredentialExpert"
          ],
          "claims": {
            "firstName": "Megan",
            "lastName": "Bowen"
          },
          "credentialState": {
            "revocationStatus": "VALID"
          },
          "domainValidation": {
            "url": "https://contoso.com/"
          },
          "issuanceDate": "yyyy-MM-ddTHH:mm:ssZ",
          "expirationDate": "yyyy-MM-ddTHH:mm:ssZ"
        }
      ],
      "receipt": {
        "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
        "vp_token": "...",
        "state": "..."
      }
    }
    

    Další kroky

    Zjistěte , jak volat rozhraní REST API služby požadavků.