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