Kérelemszolgáltatás REST API-kiállítási specifikációja

Cikk
10/02/2024

Microsoft Entra Ellenőrzött azonosító tartalmazza a Request Service REST API-t. Ez az API lehetővé teszi a hitelesítő adatok kiállítását és ellenőrzését. Ez a cikk a kérelemszolgáltatás REST API-jának megadása egy kiállítási kérelemhez. Egy másik cikk bemutatja , hogyan hívhatja meg a Kérelemszolgáltatás REST API-t.

HTTP-kérés

A Kérelemszolgáltatás REST API-kiállítási kérése a következő HTTP-módszert támogatja:

Módszer	Notes
POSTA	A cikkben megadott JSON hasznos adatokkal.

A Kérelemszolgáltatás REST API-kiállítási kéréséhez a következő HTTP-fejlécek szükségesek:

Név	Érték
`Authorization`	Csatolja a hozzáférési jogkivonatot tulajdonosi jogkivonatként egy HTTP-kérés engedélyezési fejlécéhez. Például: `Authorization: Bearer <token>`.
`Content-Type`	`application/json`

HTTP POST-kérés létrehozása a Kérelemszolgáltatás REST API-jának.

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

A következő HTTP-kérés bemutatja a Kérelemszolgáltatás REST API-jának való kérést:

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

{
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "headers": {
            "api-key": "an-api-key-can-go-here"
        }
    },
    ...
}

A kérelemszolgáltatás REST API-jának meghívásához a következő engedély szükséges. További információ: Engedélyek megadása hozzáférési jogkivonatok lekéréséhez.

Engedély típusa	Engedély
Alkalmazás	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

A kiállítási kérelem hasznos adatai

A kiállítási kérelem hasznos adatai információkat tartalmaznak az ellenőrizhető hitelesítő adatok kiállítási kéréséről. Az alábbi példa egy pin-kódfolyamat felhasználói jogcímekkel , például utónévvel és vezetéknévvel történő használatával mutatja be a kiállítási kérelmet. A kérés eredménye egy QR-kódot ad vissza egy hivatkozással a kiállítási folyamat elindításához.

{
  "authority": "did:web:verifiedid.contoso.com",
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "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"
}

A hasznos adatok a következő tulajdonságokat tartalmazzák:

Paraméter	Típus	Leírás
`includeQRCode`	Logikai	Szabadon választható. Meghatározza, hogy szerepel-e QR-kód a kérés válaszában. Mutassa be a QR-kódot, és kérje meg a felhasználót, hogy vizsgálja meg. A QR-kód vizsgálata elindítja a hitelesítő alkalmazást ezzel a kiállítási kéréssel. A lehetséges értékek a következők `true` : vagy `false` (alapértelmezett). Az érték `false`beállításakor a visszatérési `url` tulajdonság használatával jelenítsen meg egy mélyhivatkozást.
`callback`	Visszahívási	Kötelező. Lehetővé teszi, hogy a fejlesztő aszinkron módon lekérje a folyamat adatait az ellenőrizhető hitelesítő adatok kiállítási folyamata során. Előfordulhat például, hogy a fejlesztő hívást szeretne, ha a felhasználó megvizsgálta a QR-kódot, vagy ha a kiállítási kérelem sikeres vagy sikertelen.
`authority`	húr	A kibocsátó decentralizált azonosítója (DID). További információ: Hitelesítő adatok és környezetadatok összegyűjtése a mintaalkalmazás beállításához.
`registration`	RequestRegistration	Információt nyújt a kiállítóról, amely megjeleníthető a hitelesítő alkalmazásban.
`type`	húr	Az ellenőrizhető hitelesítőadat-típus. Meg kell egyeznie az ellenőrizhető hitelesítőadat-jegyzékben meghatározott típussal. Például: `VerifiedCredentialExpert`. További információ: Igazolt hitelesítőadat-szakértői kártya létrehozása az Azure-ban.
`manifest`	húr	Az ellenőrizhető hitelesítőadat-jegyzékdokumentum URL-címe. További információ: Hitelesítő adatok és környezetadatok összegyűjtése a mintaalkalmazás beállításához.
`claims`	húr	Szabadon választható. Csak az azonosító jogkivonat-igazolási folyamatához használható, hogy a tárgyra vonatkozó állítások gyűjteménye szerepeljen az ellenőrizhető hitelesítő adatokban.
`pin`	GOMBOSTŰ	Szabadon választható. PIN-kód csak az azonosító jogkivonat-igazolási folyamattal használható. PIN-kódszám, amely további biztonságot nyújt a kiállítás során. Létre kell hoznia egy PIN-kódot, és be kell mutatnia a felhasználónak az alkalmazásban. A felhasználónak meg kell adnia a létrehozott PIN-kódot.
`expirationDate`	húr	Szabadon választható. A expirationDate csak az azonosító jogkivonat-igazolási folyamattal használható. Ha meg van adva, az értéknek ISO8601 formátumban kifejezett dátumnak kell lennie. A dátum felülírja a kiállítási kérelem hitelesítőadat-szabályok definíciójában szereplő validityInterval értéket. Ezzel a beállítással explicit módon szabályozhatja, hogy mikor jár le egy hitelesítő adat, például a nap végén, a hónap végén vagy az év végén, függetlenül attól, hogy mikor adják ki. Vegye figyelembe, hogy a dátum UTC formátumban van kifejezve. Ha az év végi dátumot adja meg, és az idő értéke `23:59:59`1 másodperc és éjfél között van UTC-idő szerint. Egy másik időzóna bármely felhasználója megkapja a lejárati dátumot a Microsoft Authenticator helyi időzónájában. Ez azt jelenti, hogy ha a CET időzónájában van, az január 1.11-én jelenik meg. A hitelesítőadat-szerződésnek igazra kell állítania az AllowOverrideValidityOnIssuance jelzőt.

Jelenleg négy jogcímigazolási típust küldhet a hasznos adatok között. Microsoft Entra Ellenőrzött azonosító négy módon szúr be jogcímeket egy ellenőrizhető hitelesítő adatokba, és ezeket az információkat a kiállító DID-jével igazolja. A következő négy típust különböztetjük meg:

Azonosító jogkivonata
Azonosító jogkivonat-tipp
Ellenőrizhető hitelesítő adatok ellenőrizhető bemutatón keresztül
Önigazolt jogcímek

Az ellenőrizhető hitelesítő adatok testreszabásával kapcsolatos bemeneti típusokkal kapcsolatos részletes információkat talál.

Kérelemregistráció típusa

A RequestRegistration típus információregisztrációt biztosít a kiállító számára. A RequestRegistration típus a következő tulajdonságokat tartalmazza:

Ingatlan	Típus	Leírás
`clientName`	húr	Az ellenőrizhető hitelesítő adatok kiállítójának megjelenítendő neve.
`logoUrl`	húr	Szabadon választható. A kiállító embléma URL-címe.
`termsOfServiceUrl`	húr	Szabadon választható. A kibocsátott ellenőrizhető hitelesítő adatok használati feltételeinek URL-címe.

Jegyzet

Az információk jelenleg RequestRegistration nem jelennek meg a Microsoft Authenticator alkalmazásban való kiállítás során. Ezek az információk azonban felhasználhatók a hasznos adatokban.

Visszahívás típusa

A Kérelemszolgáltatás REST API több eseményt hoz létre a visszahívási végponton. Ezek az események lehetővé teszik a felhasználói felület frissítését és a folyamat folytatását az eredmények alkalmazásba való visszatérése után. A Callback típus a következő tulajdonságokat tartalmazza:

Ingatlan	Típus	Leírás
`url`	húr	URI az alkalmazás visszahívási végpontjához. Az URI-nak egy elérhető végpontra kell mutatnia az interneten, ellenkező esetben a szolgáltatás olvashatatlanul küld visszahívási URL-címet. Elfogadott formátumok: IPv4, IPv6 vagy DNS feloldható állomásnév
`state`	húr	Korrelálja a visszahívási eseményt az eredeti hasznos adatban átadott állapottal.
`headers`	húr	Szabadon választható. A POST üzenet fogadásához http-fejlécek gyűjteményét is felveheti. Az aktuálisan támogatott fejlécértékek a `api-key` fejlécek vagy a `Authorization` fejlécek. Bármely más fejléc érvénytelen visszahívási fejlécet eredményez

Rögzítés típusa

A pin típus meghatároz egy PIN-kódot, amely a kiállítás részeként jeleníthető meg. pin nem kötelező, és ha ezt használja, mindig sávon kívül kell elküldeni. HA KIVONATOS PIN-kódot használ, meg kell határoznia a , algés iterations a salttulajdonságokat. pin a következő tulajdonságokat tartalmazza:

Ingatlan	Típus	Leírás
`value`	húr	A PIN-kód értékét egyszerű szövegben tartalmazza. Kivonatolt PIN-kód használata esetén az értéktulajdonság a base64 kódolású sós kivonatot tartalmazza.
`type`	húr	A PIN-kód típusa. Lehetséges érték: `numeric` (alapértelmezett).
`length`	egész szám	A PIN-kód hossza. Az alapértelmezett hossz 6, a minimum 4, a maximum pedig 16.
`salt`	húr	A kivonatolt PIN-kód sója. A só előre fel van függve a kivonatszámítás során. Kódolás: UTF-8.
`alg`	húr	A kivonatolt PIN-kód kivonatolási algoritmusa. Támogatott algoritmus: `sha256`.
`iterations`	egész szám	A kivonatolási iterációk száma. Lehetséges érték: `1`.

Sikeres válasz

Ha sikeres, ez a metódus egy válaszkódot (HTTP 201 Created) és egy eseményobjektum-gyűjteményt ad vissza a válasz törzsében. A következő JSON sikeres választ mutat be:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "qrCode": "data:image/png;base64,iVBORw0KggoA<SNIP>"  
}

A válasz a következő tulajdonságokat tartalmazza:

Ingatlan	Típus	Leírás
`requestId`	húr	Automatikusan létrehozott kérésazonosító. A visszahívás ugyanazt a kérést használja, így nyomon követheti a kiállítási kérelmet és annak visszahívásait.
`url`	húr	Egy URL, amely elindítja a hitelesítő alkalmazást, és elindítja a kiállítási folyamatot. Ezt az URL-címet megjelenítheti a felhasználónak, ha nem tudják beolvasni a QR-kódot.
`expiry`	egész szám	Azt jelzi, hogy mikor jár le a válasz.
`qrCode`	húr	Egy QR-kód, amelyet a felhasználó beolvashat a kiállítási folyamat elindításához.

Amikor az alkalmazás megkapja a választ, az alkalmazásnak be kell mutatnia a QR-kódot a felhasználónak. A felhasználó megvizsgálja a QR-kódot, amely megnyitja a hitelesítő alkalmazást, és elindítja a kiállítási folyamatot.

Hibaválasz

Ha a kérés hibás, a rendszer hibaüzenetet ad vissza, amelyet az alkalmazásnak megfelelően kell kezelnie.

Visszahívási események

A visszahívási végpont akkor lesz meghívva, ha egy felhasználó megvizsgálja a QR-kódot, használja a hitelesítő alkalmazás mélyhivatkozását, vagy befejezi a kiállítási folyamatot.

Ingatlan	Típus	Leírás
`requestId`	húr	Megfeleltetve az eredeti kéréshez, amikor a hasznos adatok fel lett adva az Ellenőrizhető hitelesítő adatok szolgáltatásba.
`requestStatus`	húr	A kéréshez visszaadott állapot. Lehetséges értékek: `request_retrieved`: A felhasználó megvizsgálta a QR-kódot, vagy kiválasztotta a kiállítási folyamatot elindító hivatkozást. `issuance_successful`: Az ellenőrizhető hitelesítő adatok kiállítása sikeres volt. `issuance_error`: Hiba történt a kiállítás során. A részletekért tekintse meg a tulajdonságot `error` .
`state`	húr	Az eredeti hasznos adatban átadott állapotértéket adja vissza.
`error`	hiba	Ha a `code` tulajdonság értéke, `issuance_error`ez a tulajdonság információkat tartalmaz a hibáról.
`error.code`	húr	A visszatérési hibakód.
`error.message`	húr	A hibaüzenet.

Az alábbi példa egy visszahívás hasznos adatát mutatja be, amikor a hitelesítő alkalmazás elindítja a kiállítási kérelmet:

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

Az alábbi példa a visszahívás hasznos adatait mutatja be, miután a felhasználó sikeresen befejezte a kiállítási folyamatot:

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

Visszahívási hibák

Előfordulhat, hogy a visszahívási végpontot hibaüzenettel hívjuk meg. Az alábbi táblázat a hibakódokat sorolja fel:

Üzenet	Definíció
`fetch_contract_error`	Nem sikerült lekérni az ellenőrizhető hitelesítőadat-szerződést. Ez a hiba általában akkor fordul elő, ha az API nem tudja lekérni a request payload RequestIssuance objektumban megadott jegyzékfájlt.
`issuance_service_error`	Az ellenőrizhető hitelesítő adatok szolgáltatás nem tudja érvényesíteni a követelményeket, vagy hiba történt az ellenőrizhető hitelesítő adatokban.
`unspecified_error`	Ez a hiba nem gyakori, de érdemes kivizsgálni.

Az alábbi példa egy visszahívás hasznos adatát mutatja be hiba esetén:

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

Következő lépések

Megtudhatja , hogyan hívhatja meg a Request Service REST API-t.

Megosztás a következőn keresztül: