Specifikace vystavování rozhraní REST API služby request

Článek
12/07/2023

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 požadavku na vystavení. Další článek popisuje , jak volat rozhraní REST API služby požadavků.

Žádost HTTP

Požadavek na vystavení rozhraní REST API požadavku služby podporuje následující metodu HTTP:

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

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

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

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

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

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

{
    "includeQRCode": true,
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "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 vystavení

Datová část žádosti o vystavení obsahuje informace o vaší ověřitelné žádosti o vystavení přihlašovacích údajů. Následující příklad ukazuje žádost o vystavení pomocí toku kódu PIN s deklaracemi identity uživatelů, jako je křestní jméno a příjmení. Výsledek tohoto požadavku vrátí kód QR s odkazem pro zahájení procesu vystavení.

{
  "includeQRCode": false,
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "authority": "did:web:verifiedid.contoso.com",
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

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

Parametr	Typ	Popis
`includeQRCode`	Logické	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 vystavení. 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.
`callback`	Zpětného volání	Povinné. Umožňuje vývojáři asynchronně získat informace o toku během ověřitelného procesu vystavování přihlašovacích údajů. Vývojář může například chtít volání, když uživatel naskenoval kód QR nebo pokud žádost o vystavení proběhne úspěšně nebo selže.
`authority`	string	Decentralizovaný identifikátor vystavitele (DID). Další informace najdete v tématu Shromáždění přihlašovacích údajů a podrobností o prostředí pro nastavení ukázkové aplikace.
`registration`	RequestRegistration	Poskytuje informace o vystaviteli, který se dá zobrazit v ověřovací aplikaci.
`type`	string	Ověřitelný typ přihlašovacích údajů. Měl by odpovídat typu definovanému v ověřitelném manifestu přihlašovacích údajů. Například: `VerifiedCredentialExpert`. Další informace najdete v tématu Vytvoření ověřené karty expertů na přihlašovací údaje v Azure.
`manifest`	string	Adresa URL ověřitelného dokumentu manifestu přihlašovacích údajů. Další informace najdete v tématu Shromáždění přihlašovacích údajů a podrobností o prostředí pro nastavení ukázkové aplikace.
`claims`	string	Nepovinné. Lze použít pouze pro tok ověření identity tokenu ID, aby zahrnoval kolekci kontrolních výrazů provedených o předmětu v ověřitelných přihlašovacích údajích.
`pin`	PIN	Nepovinné. Kód PIN se dá použít jenom s tokem ověření identity tokenu ID. Číslo PIN kódu, které zajistí dodatečné zabezpečení během vystavování. Vygenerujete kód PIN a předáte ho uživateli ve vaší aplikaci. Uživatel musí zadat kód PIN, který jste vygenerovali.
`expirationDate`	string	Nepovinné. Datum vypršení platnosti je možné použít pouze s tokem ověření identity tokenu ID. Pokud je tato hodnota zadaná, musí být datum vyjádřené ve formátu ISO8601 . Datum přepíše platnostInterval v definici pravidel přihlašovacích údajů pro tuto žádost o vystavení. Pomocí tohoto nastavení můžete explicitně řídit, kdy vyprší platnost přihlašovacích údajů, jako je konec dne, konec měsíce nebo konec roku bez ohledu na to, kdy je vydána. Upozorňujeme, že datum je vyjádřeno ve formátu UTC. Pokud zadáte konec roku s časem nastaveným na `23:59:59`hodnotu 1 sekunda na půlnoc v čase UTC. Každý uživatel v jiném časovém pásmu získá datum vypršení platnosti uvedené v místním časovém pásmu v aplikaci Microsoft Authenticator. To znamená, že pokud jste v časovém pásmu CET, zobrazí se jako 11. ledna. Kontrakt přihlašovacích údajů musí mít příznak allowOverrideValidityOnIsuance nastaven na hodnotu true.

V současné době existují čtyři typy ověření identity, které můžete odeslat v datové části. Ověřené ID Microsoft Entra používá čtyři způsoby vložení deklarací do ověřitelných přihlašovacích údajů a otestovat je pomocí DID vystavitele. Toto jsou čtyři typy:

Token ID
Tip tokenu ID
Ověřitelné přihlašovací údaje prostřednictvím ověřitelné prezentace
Self-attested claims

Podrobné informace o vstupních typech najdete v části Přizpůsobení ověřitelných přihlašovacích údajů.

Typ RequestRegistration

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

Vlastnost	Type	Description
`clientName`	string	Zobrazovaný název vystavitele ověřitelných přihlašovacích údajů.
`logoUrl`	string	Nepovinné. Adresa URL loga vystavitele.
`termsOfServiceUrl`	string	Nepovinné. Adresa URL podmínek použití ověřitelných přihlašovacích údajů, které vydáváte.

Poznámka:

V tuto chvíli RequestRegistration se informace během vystavování v aplikaci Microsoft Authenticator nezobrazují. Tyto informace se ale dají použít v datové části.

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í. Přijaté formáty 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 připnutí

Typ pin definuje kód PIN, který se dá zobrazit jako součást vystavení. pin je nepovinný a pokud se použije, měl by být vždy odeslán mimo pásmo. Při použití kódu HASH PIN je nutné definovat salt, alga iterations vlastnosti. pin obsahuje následující vlastnosti:

Vlastnost	Type	Description
`value`	string	Obsahuje hodnotu PIN ve formátu prostého textu. Pokud používáte kód PIN s hodnotou hash, vlastnost value obsahuje hodnotu hash, která je zakódovaná v base64.
`type`	string	Typ kódu PIN. Možná hodnota: `numeric` (výchozí).
`length`	integer	Délka kódu PIN. Výchozí délka je 6, minimum je 4 a maximum je 16.
`salt`	string	Sůl kódu PIN s hodnotou hash. Sůl se předpočítá během výpočtu hodnoty hash. Kódování: UTF-8.
`alg`	string	Algoritmus hash pro hashovaný PIN. Podporovaný algoritmus: `sha256`.
`iterations`	integer	Počet iterací hash. Možná hodnota: `1`.

Ú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": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "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 vystavení a její zpětná volání.
`url`	string	Adresa URL, která spustí ověřovací aplikaci a spustí proces vystavování. 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 vystavení.

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

Chybná odpověď

Pokud dojde k chybě s požadavkem, vrátí se chybová odpověď a aplikace by ji 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 vystavení.

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ý pro požadavek. Možné hodnoty: `request_retrieved`: Uživatel naskenuje kód QR nebo vybral odkaz, který spustí tok vystavení. `issuance_successful`: Vystavení ověřitelných přihlašovacích údajů bylo úspěšné. `issuance_error`: Při vystavování došlo k chybě. Podrobnosti najdete v `error` této vlastnosti.
`state`	string	Vrátí hodnotu stavu, kterou jste předali v původní datové části.
`error`	chyba	`code` Pokud je `issuance_error`hodnota vlastnosti , tato vlastnost obsahuje informace o chybě.
`error.code`	string	Návratový kód chyby.
`error.message`	string	Chybová zpráva

Následující příklad ukazuje datovou část zpětného volání při spuštění žádosti o vystavení ověřovací aplikace:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"request_retrieved",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}

Následující příklad ukazuje datovou část zpětného volání po úspěšném dokončení procesu vystavení uživatele:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"issuance_successful",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
}

Chyby zpětného volání

Koncový bod zpětného volání se může volat s chybovou zprávou. Následující tabulka uvádí kódy chyb:

Zpráva	Definice
`fetch_contract_error`	Nelze načíst ověřitelný kontrakt přihlašovacích údajů. K této chybě obvykle dochází v případě, že rozhraní API nemůže načíst manifest, který zadáte v objektu RequestIssuance datové části požadavku.
`issuance_service_error`	Služba Ověřitelné přihlašovací údaje nemůže ověřit požadavky nebo se v ověřitelných přihlašovacích údajích něco nepovedlo.
`unspecified_error`	Tato chyba je neobvyklá, ale stojí za to prozkoumat.

Následující příklad ukazuje datovou část zpětného volání, když došlo k chybě:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus": "issuance_error",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",  
    "error": { 
      "code":"IssuanceFlowFailed", 
      "message":"issuance_service_error”, 
    } 
}

Další kroky

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

Share via