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

Megjegyzés

Az Azure Active Directory ellenőrizhető hitelesítő adatai mostantól Microsoft Entra Ellenőrzött azonosító és a Microsoft Entra termékcsalád részét képezik. Tudjon meg többet az Microsoft Entra identitáskezelési megoldásokról, és ismerkedjen meg az egyesített Microsoft Entra Felügyeleti központban.

Microsoft Entra Ellenőrzött azonosító tartalmazza a Request Service REST API-t. Ez az API lehetővé teszi a hitelesítő adatok kiadá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 Request Service REST API-t.

HTTP-kérés

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érelem engedélyezési fejlécéhez. Például: Authorization: Bearer <token>.
Content-Type Application/json

Hozzon létre egy HTTP POST-kérést a Request Service REST API-nak. Ez tenantId már nem szükséges az URL-címben, mivel jogcímként jelenik meg a access_token.

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

A következő HTTP-kérés egy bemutatókérést mutat be a Request Service REST API-nak:

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

{
    "includeQRCode": true,
    "callback": {
    "url": "https://www.contoso.com/api/verifier/presentationCallbac",
    "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ó: Hozzáférési jogkivonatok lekéréséhez szükséges engedélyek megadása.

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őadat-bemutatóra vonatkozó kérelemrő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ának elindításához.

{
  "includeQRCode": true,
  "includeReceipt": true,
  "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://www.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:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>..."
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

A hasznos adat a következő tulajdonságokat tartalmazza.

Paraméter Típus Description
includeQRCode Logikai 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 beolvasása elindítja a hitelesítő alkalmazást ezzel a bemutatókéréssel. A lehetséges értékek ( true alapértelmezett) vagy false. Amikor beállítja az értéket false, a visszatérési url tulajdonság használatával megjeleníthet egy mélyhivatkozást.
includeReceipt Logikai Meghatározza, hogy a kérelem válaszában szerepeljen-e nyugta. A lehetséges értékek a következők: true vagy false (alapértelmezett). A nyugta tartalmazza a hitelesítőtől az Ellenőrizhető hitelesítő adatok szolgáltatásnak küldött eredeti hasznos adatokat. A nyugta 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 sztring A hitelesítő Azure AD 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ő adatok bemutatásának folyamata 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

Ez a RequestRegistration típus a kibocsátóhoz tartozó információregisztrációt biztosítja. A RequestRegistration típus a következő tulajdonságokat tartalmazza:

Tulajdonság Típus Description
clientName sztring Az ellenőrizhető hitelesítő adatok kiállítójának megjelenítendő neve. Ez a név jelenik meg a felhasználónak a hitelesítő alkalmazásban.

Az alábbi képernyőképen látható a clientName tulajdonság és a authority (hitelesítő) megjelenítendő neve a bemutatókérésben.

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

Visszahívás típusa

A Request Service 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ó visszajuttatása után. A Callback típus a következő tulajdonságokat tartalmazza:

Tulajdonság Típus Description
url sztring 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.
state sztring Korrelálja a visszahívási eseményt az eredeti hasznos adatban átadott állapottal.
headers sztring Választható. A POST-üzenet fogadásához szükséges 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 Description
type sztring 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 beszerzéséhez tekintse meg a hitelesítő adatok és a környezet adatainak összegyűjtését a mintaalkalmazás beállításához. Másolja ki a Probléma hitelesítőadat-URL-címét, nyissa meg egy webböngészőben, és ellenőrizze az azonosító tulajdonságát .
purpose sztring Adja meg az ellenőrizhető hitelesítő adatok kérésének célját.
acceptedIssuers sztringgyűjtemény A kiállítók DID-jeinek gyűjteménye, amely kibocsáthatja az alanyok által bemutatható ellenőrizhető hitelesítő adatok típusát. A kiállító DID beszerzéséhez tekintse meg a hitelesítő adatok és a környezet részleteinek összegyű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, akkor a bemutatási kérelem elfogadja a kiállítók által kiadott hitelesítőadat-típust.
configuration.validation Configuration.Validation Nem kötelező beállítások a bemutató érvényesítéséhez.

Configuration.Validation típus

A Configuration.Validation megjelenő hitelesítő adatok érvényesítésének módjáról nyújt információt. A következő tulajdonságokat tartalmazza:

Tulajdonság Típus Description
allowRevoked Logikai Meghatározza, hogy el kell-e fogadni a visszavont hitelesítő adatokat. Az alapértelmezett érték false (nem fogadható el).
validateLinkedDomain Logikai Meghatározza, hogy a csatolt tartományt ellenőrizni kell-e. Az alapértelmezett szint a false. Ha ezt a jelzőt úgy állítja be, hogy false Függő entitás alkalmazásként elfogadja a hitelesítő adatokat egy nem ellenőrzött csatolt tartományból. Ha ezt a jelzőt úgy állítja be, hogy true a rendszer érvényesíti a csatolt tartományt, és csak ellenőrzött tartományokat fogad el.

Sikeres válasz

Ha sikeres, ez a metódus egy válaszkódot (HTTP 201 Létrehozva) és egy eseményobjektum-gyűjteményt ad vissza a válasz törzsében. A következő JSON egy 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/request/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 Description
requestId sztring 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ést és annak visszahívásait.
url sztring 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 tudja beolvasni a QR-kódot.
expiry egész szám Azt jelzi, hogy mikor jár le a válasz.
qrCode sztring 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ási folyamatot.

Hibaválasz

Ha hiba történik a kéréssel kapcsolatban, a rendszer hibaválaszt ad vissza, és az alkalmazásnak megfelelően kell kezelnie.

Visszahívási események

A visszahívási végpontot akkor hívja meg a rendszer, 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 Description
requestId sztring Az eredeti kérésnek feleltetve, amikor a hasznos adat közzé lett adva az Ellenőrizhető hitelesítő adatok szolgáltatásban.
requestStatus sztring A kérés hitelesítő alkalmazás általi lekérésekor visszaadott állapot. Lehetséges értékek:
  • request_retrieved: A felhasználó megvizsgálta a QR-kódot, vagy kiválasztotta a bemutató folyamatát elindító hivatkozást.
  • presentation_verified: Az ellenőrizhető hitelesítő adatok érvényesítése sikeresen befejeződött.
state sztring Az eredeti hasznos adatban megadott állapotértéket adja vissza.
subject sztring Az ellenőrizhető hitelesítőadat-felhasználó DID.
issuers array Ellenőrizhető hitelesítő adatokból álló tömböt ad vissza. Minden ellenőrizhető hitelesítő adathoz a következőt biztosítja:
  • Az ellenőrizhető hitelesítőadat-típus(ok).
  • A kibocsátó DID-fájlja
  • A lekért jogcímek.
  • Az ellenőrizhető hitelesítőadat-kibocsátó tartománya.
  • Az ellenőrizhető hitelesítőadat-kibocsátó tartományérvényesítési állapota.
  • receipt sztring Választható. A nyugta tartalmazza a pénztárca által az Ellenőrizhető hitelesítő adatok szolgáltatásnak küldött eredeti hasznos adatokat. A nyugtát csak hibaelhárításhoz/hibakereséshez kell használni. A nyugta formátuma nem javítható, és a használt pénztárca és verzió alapján változhat.

    Az alábbi példa bemutatja a visszahívás hasznos adatait, 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 bemutatja a visszahívás hasznos adatait, 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:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>…",
      "verifiedCredentialsData": [
        {
          "issuer": "did:ion:issuer",
          "type": [
            "VerifiableCredential",
            "VerifiedCredentialExpert"
          ],
          "claims": {
            "firstName": "Megan",
            "lastName": "Bowen"
          },
          "credentialState": {
            "revocationStatus": "VALID"
          },
          "domainValidation": {
            "url": "https://contoso.com/"
          }
        }
      ],
      "receipt": {
        "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
        "vp_token": "...",
        "state": "..."
      }
    }
    

    Következő lépések

    Ismerje meg , hogyan hívhatja meg a kérelemszolgáltatás REST API-jának meghívását.