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:

A Kérelemszolgáltatás REST API-bemutató kéréséhez a következő HTTP-fejlécek szükségesek:

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.

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.

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:

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:

RequestCredential típus

A RequestCredential megadott adatok a felhasználó által igényelt hitelesítő adatokkal kapcsolatosak. RequestCredential a következő tulajdonságokat tartalmazza:

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:

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.

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.

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:

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.

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.