Kérelemszolgáltatás REST API-bemutató specifikációja
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 bemutatókéréshez. A bemutatókérés arra kéri a felhasználót, hogy mutasson be egy ellenőrizhető hitelesítő adatot, majd ellenőrizze a hitelesítő adatokat. Egy másik cikk bemutatja , hogyan hívhatja meg a Kérelemszolgáltatás REST API-t.
HTTP-kérelem
A Kérelemszolgáltatás REST API-bemutató kérése a következő HTTP-metódust támogatja:
Metódus | Jegyzetek |
---|---|
POST | A cikkben megadott JSON hasznos adatokkal. |
A Kérelemszolgáltatás REST API-bemutató kéréséhez a következő HTTP-fejlécek szükségesek:
Metódus | É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. Az tenantId
URL-címben már nincs szükség rá, mivel jogcímként jelenik meg a access_token
.
https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
Az alábbi HTTP-kérés bemutatja a kérelemszolgáltatás REST API-jának való bemutatókérést:
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"
}
},
...
}
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 |
Bemutatókérés hasznos adatai
A bemutatókérés hasznos adatai információkat tartalmaznak az ellenőrizhető hitelesítő adatok bemutatókéréséről. Az alábbi példa egy adott kiállítótól származó bemutatókérést mutat be. A kérés eredménye egy QR-kódot ad vissza egy hivatkozással a bemutató folyamat elindításához.
{
"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
}
}
}
]
}
A hasznos adat a következő tulajdonságokat tartalmazza.
Paraméter | Típus | Leírás |
---|---|---|
includeQRCode |
Logikai | Opcionális. 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 bemutató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. |
includeReceipt |
Logikai | Opcionális. Meghatározza, hogy a kérelem válaszában szerepelnie kell-e nyugtának. A lehetséges értékek a következők true : vagy false (alapértelmezett). A nyugta tartalmazza az eredeti hasznos adatokat, amelyeket a hitelesítőtől a Ellenőrizhető hitelesítő adatok szolgáltatásnak küldtek. A nyugta a hibaelhárításhoz hasznos, vagy ha szüksége van a hasznos adatok teljes részleteire. Máskülönben nincs szükség erre az értékre true alapértelmezés szerint. A kérelemben a OpenId Connect SIOP nyugta tartalmazza az eredeti kérelem azonosító jogkivonatát. |
authority |
húr | A hitelesítő Microsoft Entra-bérlő decentralizált azonosítója (DID). További információ: Bérlői adatok összegyűjtése a mintaalkalmazás beállításához. |
registration |
RequestRegistration | Információt nyújt a hitelesítőről. |
callback |
Visszahívási | Kötelező. Lehetővé teszi a fejlesztő számára, hogy frissítse a felhasználói felületet az ellenőrizhető hitelesítőadat-bemutató folyamat során. Amikor a felhasználó befejezi a folyamatot, folytassa a folyamatot, miután az eredményeket visszaadta az alkalmazásnak. |
requestedCredentials |
gyűjtemény | RequestCredential objektumok gyűjteménye. |
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:
Tulajdonság | Típus | Leírás |
---|---|---|
clientName |
húr | Az ellenőrizhető hitelesítő adatok hitelesítő adatainak megjelenítendő neve. Ez a név megjelenik a felhasználónak a hitelesítő alkalmazásban. |
purpose |
húr | Opcionális. Megjelenik egy sztring, amely tájékoztatja a felhasználót az ellenőrizhető hitelesítő adatok kérésének okáról. |
logoUrl |
URL-cím | Opcionális. A hitelesítő emblémájának URL-címe. Ezt az értéket az Authenticator alkalmazás nem használja. |
termsOfServiceUrl |
URL-cím | Opcionális. A hitelesítő szolgáltatási feltételeinek URL-címe. Ezt az értéket az Authenticator alkalmazás nem használja. |
Az alábbi képernyőképen a clientName
bemutatókérés tulajdonsága authority
és a (hitelesítő) megjelenítendő neve látható.
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:
Tulajdonság | 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, különben a szolgáltatás olvashatatlan visszahívási URL-címet ad vissza. Elfogadott bemenetek: IPv4, IPv6 vagy DNS feloldható állomásnév. A hálózat megerősítéséhez tekintse meg a gyakori kérdéseket. |
state |
húr | Korrelálja a visszahívási eseményt az eredeti hasznos adatban átadott állapottal. |
headers |
húr | Opcionális. 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échibát jelez. |
RequestCredential típus
A RequestCredential
megadott adatok a felhasználó által igényelt hitelesítő adatokkal kapcsolatosak.
RequestCredential
a következő tulajdonságokat tartalmazza:
Tulajdonság | Típus | Leírás |
---|---|---|
type |
húr | Az ellenőrizhető hitelesítőadat-típus. A type típusnak meg kell egyeznie az issuer ellenőrizhető hitelesítőadat-jegyzékben meghatározott típussal (például VerifiedCredentialExpert ). A kiállítói jegyzék lekéréséhez tekintse meg a hitelesítő adatok és a környezet adatainak gyűjtését a mintaalkalmazás beállításához. Másolja ki a probléma hitelesítő URL-címét, nyissa meg egy webböngészőben, és ellenőrizze az azonosító tulajdonságot . |
purpose |
húr | Opcionális. Adjon meg információt az ellenőrizhető hitelesítő adatok kérésének céljáról. Ezeket az adatokat az Authenticator alkalmazás nem használja. |
acceptedIssuers |
sztringgyűjtemény | Opcionális. A kiállítók DID-jeinek gyűjteménye, amelyek kibocsáthatják az alanyok által bemutatható ellenőrizhető hitelesítő adatok típusát. A kiállító DID-jének lekéréséhez tekintse meg a hitelesítő adatok és a környezet adatainak gyűjtését a mintaalkalmazás beállításához, és másolja ki a decentralizált azonosító (DID) értékét. Ha a acceptedIssuers gyűjtemény üres vagy nem található, akkor a bemutatókérés elfogadja a kiállító által kiadott hitelesítő adatokat. |
configuration.validation |
Configuration.Validation | A bemutató érvényesítésének választható beállításai. |
constraints |
Korlátozások | Opcionális. Jogcímkorlátok gyűjteménye. |
Configuration.Validation type
A Configuration.Validation
megadott hitelesítő adatok érvényesítésének módjáról nyújt tájékoztatást. A következő tulajdonságokat tartalmazza:
Tulajdonság | Típus | Leírás |
---|---|---|
allowRevoked |
Logikai | Opcionális. Meghatározza, hogy el kell-e fogadni a visszavont hitelesítő adatokat. Az alapértelmezett érték false (ez nem fogadható el). |
validateLinkedDomain |
Logikai | Opcionális. Meghatározza, hogy a csatolt tartományt ellenőrizni kell-e. Az alapértelmezett szint a false . A jelző beállítása azt jelenti, hogy false Ön függő entitásként fogad hitelesítő adatokat egy nem ellenőrzött csatolt tartományból. Ha ezt a jelölőt true értékre állítja, a rendszer ellenőrzi a csatolt tartományt, és csak az ellenőrzött tartományokat fogadja el. |
faceCheck |
faceCheck | Opcionális. Lehetővé teszi az élőség-ellenőrzés kérését a bemutató során. |
Korlátozások típusa
A constraints
típus olyan jogcímkorlátok gyűjteményét tartalmazza, amelyeknek teljesülniük kell, amikor egy tárca kiválasztja a jelölt hitelesítő adatait. Ez lehetővé teszi egy adott jogcímértékkel rendelkező hitelesítő adatok kérését. A megadott megkötések az AND logikát használják, vagyis ha három kényszert ad meg, mindegyiknek teljesülnie kell. A gyűjtemény minden egyes kényszeréhez ki kell választania egy operandust az értékekből, a tartalmazból vagy a startsWithből. Az értékek nem lehetnek reguláris kifejezések. Minden összehasonlítás érzéketlen a kis- és nagybetűk között.
Tulajdonság | Típus | Leírás |
---|---|---|
claimName |
húr | Kötelező. A kényszer jogcímének neve. Ez az érték az ellenőrizhető hitelesítő adatok jogcímneve. Lásd : outputClaim in claimMapping type. |
values |
sztringgyűjtemény | A jogcímértéknek megfelelő értékek halmaza. Ha több értéket ad meg, például ["piros", "zöld", "kék"] akkor egyezik, ha a hitelesítő adatok jogcímértékének bármelyik értéke szerepel a gyűjteményben. |
contains |
húr | A kényszer igaz értéket ad vissza, ha a jogcím értéke tartalmazza a megadott értéket. |
startsWith |
húr | A kényszer igaz értéket ad vissza, ha a jogcím értéke a megadott értékkel kezdődik. |
faceCheck típus
A faceCheck típus információkat tartalmaz az élőség-ellenőrzés elvégzésére a hitelesítő adatok bemutatása során. A kért hitelesítő adatnak tartalmaznia kell egy fényképet a tulajdonosról a forrásPhotoClaimName nevű jogcímben. A bemutató akkor sikeres, ha az élőség-ellenőrzés aConfidenceThreshold tulajdonságban megadott megbízhatósági szinttel egyenlő vagy annál nagyobb értéket ér el. Ha a küszöbérték nem teljesül, a teljes bemutató meghiúsul.
Tulajdonság | Típus | Leírás |
---|---|---|
sourcePhotoClaimName |
húr | Kötelező. A fényképet tartalmazó hitelesítő adatokban szereplő jogcím neve. Lásd : outputClaim in claimMapping type. |
matchConfidenceThreshold |
egész szám | Opcionális. A fénykép és az élőségi adatok közötti sikeres ellenőrzés bizalmas küszöbértéke. 50 és 100 közötti egész számnak kell lennie. Az alapértelmezett érték 70. |
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": "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>"
}
A válasz a következő tulajdonságokat tartalmazza:
Tulajdonság | 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 bemutató kérését és visszahívásait. |
url |
húr | Egy URL- cím, amely elindítja a hitelesítő alkalmazást, és elindítja a bemutató folyamatát. 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 bemutató folyamatának 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 bemutató folyamatát.
Hibaválasz
Ha hiba történt a kéréssel kapcsolatban, a hibaválaszt ad vissza. Az alkalmazásnak megfelelően kell kezelnie a hibát.
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 bemutató folyamatát.
Tulajdonság | 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 hitelesítő alkalmazás kérésének lekérésekor visszaadott állapot. Lehetséges értékek:
|
state |
húr | Az eredeti hasznos adatban átadott állapotértéket adja vissza. |
subject |
húr | Az ellenőrizhető hitelesítőadat-felhasználó DID. |
verifiedCredentialsData |
array | A kért ellenőrizhető hitelesítő adatok tömbjének visszaadása. Minden ellenőrizhető hitelesítő adathoz a következőt nyújtja: |
receipt |
húr | Opcionális. A nyugta tartalmazza a pénztárca által az Ellenőrizhető hitelesítő adatok szolgáltatásnak küldött eredeti hasznos adatokat. A visszaigazolás csak hibaelhárításhoz/hibakereséshez használható. A nyugta formátuma nem javítható, és a használt tárca és verzió alapján változhat. |
Az alábbi példa egy visszahívás hasznos adatát mutatja be, amikor a hitelesítő alkalmazás elindítja a bemutatókérést:
{
"requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
"requestStatus":"request_retrieved",
"state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58"
}
Az alábbi példa egy visszahívás hasznos adatát mutatja be, miután az ellenőrizhető hitelesítő adatok bemutatója sikeresen befejeződött:
{
"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": "..."
}
}
Következő lépések
Megtudhatja , hogyan hívhatja meg a Request Service REST API-t.