Kérelem szolgáltatás REST API-ja specifikációja (előzetes verzió)

Azure Active Directory (Azure AD) Ellenőrizhető hitelesítő adatai között szerepel a Kérelem szolgáltatás REST API-ja. Ez az API lehetővé teszi hitelesítő adatok kiállítását és ellenőrzését. Ez a cikk a szolgáltatás REST API-ja kérelemkéréshez ad meg. A bemutató kérés egy ellenőrizhető hitelesítő adat bemutatására kéri a felhasználót, majd ellenőrizze a hitelesítő adatokat.

HTTP-kérés

A Request szolgáltatás REST API-ja presentation kérés a következő HTTP-metódust támogatja:

Metódus Jegyzetek
POST A cikkben megadott hasznos JSON-adatokkal.

A Request szolgáltatás REST API-ja presentation kérelemhez a következő HTTP-fejlécek szükségesek:

Metódus Érték
Authorization Csatolja a hozzáférési jogkivonatot bearer tokenként az engedélyezési fejléchez egy HTTP-kérésben. Például: Authorization: Bearer <token>.
Content-Type Application/json

Http POST-kérést hoz létre a Kérelem szolgáltatás REST API-ja. Cserélje le {tenantID} a helyére a bérlőazonosítóját vagy a bérlő nevét.

https://beta.did.msidentity.com/v1.0/{tenantID}/verifiablecredentials/request

A következő HTTP-kérés egy bemutató kérést mutat be a kérelem szolgáltatás REST API-ja:

POST https://beta.did.msidentity.com/v1.0/contoso.onmicrosoft.com/verifiablecredentials/request
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 Request (Kérelem) hívásához a következő engedély szolgáltatás REST API-ja. További információkért lásd: Engedélyek megadása hozzáférési jogkivonatok lekért eléréséhez.

Engedély típusa Engedély
Alkalmazás bbb94529-53a3-4be5-a069-7eaf2712b826/.default

Bemutató kérelem hasznos információja

A bemutatási kérelem hasznos adatai az ellenőrizhető hitelesítőadat-bemutatási kérésre vonatkozó információkat tartalmaznak. Az alábbi példa egy adott kiállítótól származó bemutatási kérelmet mutat be. A kérés eredménye egy QR-kódot ad vissza a bemutató folyamatának igénylésére mutató hivatkozással.

{
  "includeQRCode": true,
  "callback": {
    "url": "https://www.contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for VERIFIER CALLBACK API"
    }
  },
  "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiOiJiRWo5MDY...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "presentation": {
    "includeReceipt": true,
    "requestedCredentials": [
      {
        "type": "VerifiedCredentialExpert",
        "purpose": "So we can see that you a veritable credentials expert",
        "acceptedIssuers": [
          "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiO..."
        ]
      }
    ]
  }
}

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

Paraméter Típus Description
includeQRCode Logikai Meghatározza, hogy a kérelem válasza tartalmaz-e QR-kódot. A QR-kód bemutatja és megkéri 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. Lehetséges értékek: true (alapértelmezett) vagy false . Ha értékre van állítva, false a return tulajdonság használatával url renderelhet egy mélyhivatkozást.
authority sztring Az ellenőrző Azure AD-bérlő decentralizált azonosítója (DID). További információ: Bérlői adatok gyűjtése a mintaalkalmazás beállításához.
registration RequestRegistration (Kérelem regisztrációja) Információkat nyújt az ellenőrzőről.
presentation Kérelemreprezentáció Információkat nyújt az ellenőrizhető hitelesítő adatok bemutatására vonatkozó kérésről.
callback Visszahívási Lehetővé teszi, hogy a fejlesztő frissítse a felhasználói felületet az ellenőrizhető hitelesítő adatok bemutatásának folyamata során. Miután a felhasználó befejezte a folyamatot, folytassa a folyamatot, miután az eredmények visszakerültek az alkalmazásba.

RequestRegistration 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 Description
clientName sztring Az ellenőrizhető hitelesítő adat kiállítójának megjelenített neve. Ez a név jelennek meg a felhasználónak a hitelesítő alkalmazásban.

Az alábbi képernyőképen a tulajdonság és a megjelenített neve (az ellenőrző) látható a clientName authority bemutatási kérelemben.

A bemutatóra vonatkozó kérelem jóváhagyását bemutató képernyőkép.

RequestPresentation típusa

A RequestPresentation típus a hitelesítő adatok ellenőrizhető bemutatásához szükséges információkat tartalmaz. RequestPresentation A a következő tulajdonságokat tartalmazza:

Tulajdonság Típus Description
includeReceipt Logikai Meghatározza, hogy a kérelem válaszában szerepelnie kell-e nyugtának. Lehetséges értékek: true vagy false (alapértelmezett). A nyugta tartalmazza a hitelesítő által az Ellenőrizhető hitelesítő adatok szolgáltatásnak küldött eredeti hasznos adatokat. A nyugta hibaelhárításhoz hasznos, és nem lehet alapértelmezetten beállítani. A kérelemben a nyugta tartalmazza az eredeti kérelem OpenId Connect SIOP azonosító jogkivonatát.
requestedCredentials Gyűjtemény RequestCredential objektumok gyűjteménye.

RequestCredential típus

A a felhasználó által kért hitelesítő adatokkal kapcsolatos RequestCredential információkat tartalmaz. RequestCredential A a következő tulajdonságokat tartalmazza:

Tulajdonság Típus Description
type sztring Az ellenőrizhető hitelesítő adatok típusa. A típusnak meg kell egyeznie az ellenőrizhető hitelesítőadat-jegyzékben type issuer megadott típussal (például VerifiedCredentialExpert ). A kiállító jegyzékfájljának lekért információkért lásd: Hitelesítő adatok és környezeti adatok gyűjtése a mintaalkalmazás beállításához. Másolja ki a Probléma hitelesítő adatainak URL-címét, nyissa meg egy webböngészőben, és ellenőrizze az id tulajdonságot.
purpose sztring Adja meg az ellenőrizhető hitelesítő adatok kérésének célját.
acceptedIssuers sztringgyűjtemény Kiállítók DID-inek gyűjteménye, amely kibocsáthatja a személyek által bemutatható ellenőrizhető hitelesítő adatok típusát. A kiállító DID-azonosítójának begyűjtéséhez tekintse meg a hitelesítő adatok és a környezet adatainak gyűjtése a mintaalkalmazás beállításához, és másolja a Decentralizált azonosító (DID) értékét.

Visszahívási típus

A Request szolgáltatás REST API-ja több eseményt hoz létre a visszahívási végponthoz. 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 az alkalmazásnak való visszaadása után. A Callback típus a következő tulajdonságokat tartalmazza:

Tulajdonság Típus Description
url sztring Az alkalmazás visszahívási végpontjának URI-ja.
state sztring Társítja az eredeti hasznos fájlban átadott állapotot.
headers sztring Választható. A POST-üzenet fogadásához szükséges HTTP-fejlécek gyűjteményét is meg lehet adni. A fejlécek csak a vagy bármely, az api-key engedélyezéshez szükséges fejlécet tartalmazhatják.

Sikeres válasz

Ha ez a metódus sikeres, visszaad egy válaszkódot (HTTP 201 Létrehozva), valamint egy eseményobjektum-gyűjteményt a válasz törzsében. Az alábbi JSON a sikeres választ mutatja be:

{  
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid://vc/?request_uri=https://beta.did.msidentity.com/v1.0/87654321-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 korrelációs azonosító. A visszahívás ugyanazt a kérést használja, így nyomon követheti a bemutatóra vonatkozó kérést és a visszahívásokat.
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 akkor mutathatja be a felhasználónak, ha nem tudja beolvasni a QR-kódot.
expiry egész szám Azt jelzi, hogy a válasz mikor jár le.
qrCode sztring Egy QR-kód, amely beolvashatja a felhasználó számára a bemutató folyamatának elkezdődhet.

Amikor az alkalmazás megkapja a választ, az alkalmazásnak be kell bemutatnia a QR-kódot a felhasználónak. A felhasználó beolvassa a QR-kódot, amely megnyitja a hitelesítő alkalmazást, és elindítja a bemutató folyamatát.

Hibaválasz

Hibaválaszok is visszaadhatóak, hogy az alkalmazás megfelelően tudja kezelni őket. Az alábbi JSON egy jogosulatlan hibaüzenetet mutat:

{
    "requestId": "fb888ac646c96083de83b099b2678de0",
    "date": "Wed, 29 Sep 2021 21:49:00 GMT",
    "error": {
        "code": "unauthorized",
        "message": "Failed to authenticate the request."
    }
}

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

Tulajdonság Típus Description
requestId sztring Egy automatikusan létrehozott kérelemazonosító.
date dátum A hiba ideje.
error.code sztring A visszaadott hibakód.
error.message sztring A hibaüzenet.

Visszahívási események

A visszahívási végpontot akkor hívja meg a rendszer, amikor egy felhasználó beolvassa a QR-kódot, a hitelesítő alkalmazás mélyhivatkozását használja, vagy befejezi a bemutató folyamatát.

Tulajdonság Típus Description
requestId sztring Leképezve az eredeti kérelemre, amikor a hasznos adatokat közzétették az Ellenőrizhető hitelesítő adatok szolgáltatásban.
code sztring A hitelesítő alkalmazás által a kérés lekértekor visszaadott kódot. Lehetséges értékek:
  • request_retrieved: A felhasználó megvizsgálta a QR-kódot, vagy kiválasztotta azt a hivatkozást, amely elindítja a bemutató folyamatot.
  • presentation_verified: Az ellenőrizhető hitelesítő adatok érvényesítése sikeresen befejeződött.
state sztring Az eredeti hasznos adatban átadott állapotértéket adja vissza.
subject sztring Az ellenőrizhető hitelesítőadat-felhasználó DID.
issuers array A kért ellenőrizhető hitelesítő adatok tömböt adja vissza. Minden ellenőrizhető hitelesítő adathoz a következőt biztosítja:
  • Az ellenőrizhető hitelesítő adatok típusa.
  • A lekért jogcímek.
  • Az ellenőrizhető hitelesítőadat-kibocsátó tartománya.
  • A hitelesítő adatok kiállítójának ellenőrizhető tartományérvényesítési állapota.
  • receipt sztring Választható. A nyugta tartalmazza a hitelesítő által az Ellenőrizhető hitelesítő adatoknak küldött eredeti hasznos adatokat.

    Az alábbi példa egy visszahívási hasznos adatokat mutat be, amikor a hitelesítő alkalmazás elindítja a bemutatóra vonatkozó kérést:

    {  
        "requestId":"aef2133ba45886ce2c38974339ba1057",  
        "code":"request_retrieved",  
        "state":"Wy0ThUz1gSasAjS1"
    } 
    

    Az alábbi példa egy visszahívás hasznos adatát mutatja be az ellenőrizhető hitelesítő adatok bemutatásának sikeres befejezése után:

    {
      "requestId": "87e1cb24-9096-409f-81cb-9e645f23a4ba",
      "code": "presentation_verified",
      "state": "f3d94e35-ca5f-4b1b-a7d7-a88caa05e322",
      "subject": "did:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>…",
      "issuers": [
        {
          "type": [
            "VerifiableCredential",
            "VerifiedCredentialExpert"
          ],
          "claims": {
            "firstName": "John",
            "lastName": "Doe"
          },
          "domain": "https://contoso.com/",
          "verified": "DNS",
          "issuer": "did:ion:….."
        }
      ],
      "receipt": {
        "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>"
      }
    } 
    

    Következő lépések

    Ismerje meg, hogyan hívható meg a Kérelem szolgáltatás REST API-ja.