Kérelemszolgáltatás REST API-kiállítási 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 kiállítási kérelemhez. 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-kiállítási kérése a következő HTTP-módszert támogatja:

A Kérelemszolgáltatás REST API-kiállítási 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.

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

A következő HTTP-kérés bemutatja a Kérelemszolgáltatás REST API-jának való kérést:

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

{
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "Aaaabbbb11112222",
        "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.

A kiállítási kérelem hasznos adatai

A kiállítási kérelem hasznos adatai információkat tartalmaznak az ellenőrizhető hitelesítő adatok kiállítási kéréséről. Az alábbi példa egy pin-kódfolyamat felhasználói jogcímekkel , például utónévvel és vezetéknévvel történő használatával mutatja be a kiállítási kérelmet. A kérés eredménye egy QR-kódot ad vissza egy hivatkozással a kiállítási folyamat elindításához.

{
  "authority": "did:web:verifiedid.contoso.com",
  "callback": {
    "url": "https://contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "pin": {
    "value": "3539",
    "length": 4
  },
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "expirationDate": "2024-12-31T23:59:59.000Z"
}

Az adatcsomag a következő tulajdonságokat tartalmazza:

Jelenleg négy jogcímigazolási típust küldhet a hasznos adatok között. Microsoft Entra Ellenőrzött azonosító négy módon szúr be jogcímeket egy ellenőrizhető hitelesítő adatokba, és ezeket az információkat a kiállító DID-jével igazolja. A következő négy típust különböztetjük meg:

• Azonosító jogkivonata
• Azonosító jogkivonatokra vonatkozó tippek
• Ellenőrizhető hitelesítő adatok ellenőrizhető bemutatón keresztül
• Önigazolt jogcímek

Az ellenőrizhető hitelesítő adatok testreszabásával kapcsolatos bemeneti típusokkal kapcsolatos részletes információkat talál.

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:

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:

Rögzítés típusa

A pin típus meghatároz egy PIN-kódot, amely a kiállítás részeként jeleníthető meg. pin nem kötelező, és ha ezt használja, mindig sávon kívül kell elküldeni. HA KIVONATOS PIN-kódot használ, meg kell határoznia a , saltés alg a iterationstulajdonságokat. pin a következő tulajdonságokat tartalmazza:

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": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e",  
    "expiry": 1622227690,  
    "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 kiállítási folyamatot.

Hibaválasz

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

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 kiállítási folyamatot.

Az alábbi példa egy visszahívás hasznos adatát mutatja be, amikor a hitelesítő alkalmazás elindítja a kiállítási kérelmet:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"request_retrieved",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
} 

Az alábbi példa a visszahívás hasznos adatait mutatja be, miután a felhasználó sikeresen befejezte a kiállítási folyamatot:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus":"issuance_successful",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c"
} 

Visszahívási hibák

Előfordulhat, hogy a visszahívási végpontot hibaüzenettel hívjuk meg. Az alábbi táblázat a hibakódokat sorolja fel:

Az alábbi példa egy visszahívás hasznos adatát mutatja be hiba esetén:

{  
    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",  
    "requestStatus": "issuance_error",  
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",  
    "error": { 
      "code":"IssuanceFlowFailed", 
      "message":"issuance_service_error”, 
    } 
} 

Következő lépések

Megtudhatja , hogyan hívhatja meg a Request Service REST API-t.