Kérelemszolgáltatás REST API-bemutató specifikációja

Cikk
02/06/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 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>

{
    "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"
      }
    },
    ...
}

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.

{
  "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
        }
      }
    }
  ]
}

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 ( `true` alapértelmezett) vagy `false`. 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 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 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ó.

Képernyőkép a bemutatókérés jóváhagyásáról.

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 küld. Elfogadott bemenetek: 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	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 eredményez.

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. Ezt 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ése elfogad egy hitelesítő adatot, amelyet bármely kiállító állít ki.
`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. A jelző beállítása azt jelenti, hogy `true` a csatolt tartomány érvényesítve lesz, és csak az ellenőrzött tartományok lesznek elfogadva.
`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ékek közül, a contains vagy a startsWith értéket. 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 a jogcím neve az ellenőrizhető hitelesítő adatokban. 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ó sikeres lesz, ha az élőség-ellenőrzés olyan megbízhatósági szintet ér el, amely megegyezik aConfidenceThreshold tulajdonságban megadott megbízhatósági szinttel. Ha a küszöbérték nem teljesül, a teljes bemutató sikertelen lesz.

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/12345678-0000-0000-0000-000000000000/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énik a kéréssel kapcsolatban, a rendszer hibaüzenetet ad vissza, és 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 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	Az állapot akkor lett visszaadva, amikor a kérést a hitelesítő alkalmazás lekérte. Lehetséges értékek: `request_retrieved`: A felhasználó beolvasta a QR-kódot, vagy kiválasztotta a bemutatófolyamatot elindító hivatkozást. `presentation_verified`: Az ellenőrizhető hitelesítő adatok ellenőrzése sikeresen befejeződött. li>`presentation_error`: Hiba történt a bemutatóban.
`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: Az ellenőrizhető hitelesítő adattípus(ok). A kibocsátó DID A lekért jogcímek. Az ellenőrizhető hitelesítőadat-kiállító tartománya. Az ellenőrizhető hitelesítőadat-kiállító tartományérvényesítési állapota.
`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 a visszahívás hasznos adatait 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.