Specifikace prezentace rozhraní REST API služby request

Článek
02/07/2024

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>

{
    "includeQRCode": true,
    "callback": {
      "url": "https://contoso.com/api/verifier/presentationCallback",
      "state": "11111111-2222-2222-2222-333333333333",
      "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.

{
  "includeQRCode": true,
  "includeReceipt": true,
  "authority": "did:web:verifiedid.contoso.com",
  "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` (výchozí) nebo `false`. Když nastavíte hodnotu na `false`hodnotu , 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é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	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ů.
`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/12345678-0000-0000-0000-000000000000/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ů.

Share via