Megosztás a következőn keresztül:


A Kérelemszolgáltatás REST API meghívása

A Microsoft Entra ellenőrzött azonosítója tartalmazza a Kérelemszolgáltatás REST API-ját. Ez az API lehetővé teszi a hitelesítő adatok kiállítását és ellenőrzését. Ez a cikk bemutatja, hogyan kezdheti el használni a Request Service REST API-t.

API hozzáférési jogkivonat

Az alkalmazásnak tartalmaznia kell egy érvényes hozzáférési jogkivonatot a szükséges engedélyekkel, hogy hozzáférhessen a Kérelemszolgáltatás REST API-hoz. A Microsoft identitásplatform által kibocsátott hozzáférési jogkivonatok olyan információkat (hatóköröket) tartalmaznak, amelyeket a Kérelemszolgáltatás REST API a hívó ellenőrzésére használ. A hozzáférési jogkivonat biztosítja, hogy a hívó megfelelő engedélyekkel rendelkezik a kért művelet végrehajtásához.

A hozzáférési jogkivonat megszerzéséhez az alkalmazást regisztrálni kell a Microsoft identitásplatformján, és a rendszergazdának engedélyeznie kell a Request Service REST API elérését. Ha még nem regisztrálta a ellenőrizhető hitelesítési adatok alkalmazást, tekintse meg a útmutatót az alkalmazás regisztrálására, majd hozzon létre egy alkalmazástitkos kulcsot.

Hozzáférési jogkivonat lekérése

Az OAuth 2.0 ügyfél-hitelesítési adatfolyamot használva szerezze be a hozzáférési tokent a Microsoft identitásplatform használatával. Ehhez használjon megbízható kódtárat. Ebben az oktatóanyagban a Microsoft Authentication Library (MSAL) használatát használjuk. Az MSAL leegyszerűsíti a hitelesítés és az engedélyezés hozzáadását egy olyan alkalmazáshoz, amely biztonságos webes API-t hívhat meg.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials

Az előző kódban adja meg a következő paramétereket:

Paraméter Feltétel Leírás
Hatóság Szükséges Az a címtárbérlő, amellyel az alkalmazás működni fog. Például: https://login.microsoftonline.com/{your-tenant}. (Cserélje le your-tenant a bérlőazonosítóra vagy -névre.)
Ügyfélazonosító Szükséges Az alkalmazáshoz rendelt alkalmazásazonosító. Ezeket az információkat az Azure Portalon találja, ahol regisztrálta az alkalmazást.
Titkos ügyfélkód Szükséges Az alkalmazáshoz létrehozott ügyfélkód.
Hatókörök Szükséges A értéknek 3db474b9-6a0c-4840-96ac-1fceb342124f/.defaultkell lennie. Ez a beállítás létrehoz egy hozzáférési jogkivonatot, amiben VerifiableCredential.Create.All jogcím található.

A hozzáférési jogkivonat konzolalkalmazás identitásának használatával történő beszerzéséről az alábbi cikkek egyikében talál további információt:

A token kérést tanúsítvánnyal is elérheti ügyféltitok helyett.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1   //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

Az API meghívása

Ellenőrizhető hitelesítő adatok kiállítása vagy ellenőrzése:

  1. HTTP POST-kérés létrehozása a Kérelemszolgáltatás REST API-jának. A bérlőazonosítóra már nincs szükség az URL-címben, mert jogcímként szerepel a hozzáférési jogkivonatban.

    probléma

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

    Ellenőrizze

    POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
    
  2. Csatolja a hozzáférési jogkivonatot tulajdonosi jogkivonatként egy HTTP-kérés engedélyezési fejlécéhez.

    Authorization: Bearer <token>
    
  3. Állítsa a Content-Type fejlécet Application/jsonértékre.

  4. Készítse elő és csatolja a kiállítási vagy bemutatási kérelem rakományát a kérés törzséhez.

  5. Küldje el a kérést a Request Service REST API-nak.

A Request Service API egy HTTP-állapotkódot ad vissza, 201 Created egy sikeres hívás esetén. Ha az API-hívás hibát ad vissza, ellenőrizze a hibahivatkozás dokumentációját.

Kiállítási kérelem példa

Az alábbi példa egy ellenőrizhető hitelesítőadat-kiállítási kérést mutat be. Az adatterheléssel kapcsolatos információkért lásd a Kérelemszolgáltatás REST API kiállítási specifikációját .

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

{...JSON payload...}

Kiállítási kérelem a idTokenHint igazolási folyamat használatával:

{
    "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",
    "manifestUrl": "https://verifiedid.did.msidentity.com/v1.0/00001111-aaaa-2222-bbbb-3333cccc4444/verifiableCredentials/contracts/VerifiedCredentialExpert1",
    "pin": {
        "value": "3539",
        "length": 4
    },
    "claims": {
        "given_name": "Megan",
        "family_name": "Bowen"
    }
}

A teljes kódért tekintse meg az alábbi kódminták egyikét:

Példa bemutatókérésre

Az alábbi példa egy ellenőrizhető hitelesítőadat-bemutató kérést mutat be. A terheléssel kapcsolatos információkért lásd a Kérelemszolgáltatás REST API specifikációját.

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

{...JSON payload...}

Bemutatási kérelem egy meghatározott típusú és kiállítójú hitelesítő adatra:

{
  "authority": "did:web:verifiedid.contoso.com",
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "includeReceipt": true,
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:web:verifiedid.contoso.com"
      ],
      "configuration": {
        "validation": {
          "allowRevoked": true,
          "validateLinkedDomain": true
        }
      }
    }
  ]
}

A teljes kódért tekintse meg az alábbi kódminták egyikét:

Visszahívási események

A kérés hasznos adatai tartalmazzák a kiállítás és a bemutatás visszahívási végpontot. A végpont a webalkalmazás része, és nyilvánosan elérhetőnek kell lennie a HTTPS protokollon keresztül. A Request Service API meghívja a végpontot, hogy tájékoztassa az alkalmazást bizonyos eseményekről. Ilyen esemény lehet például, ha egy felhasználó megvizsgálja a QR-kódot, használja a hitelesítő alkalmazásra mutató mélyhivatkozást, vagy befejezi a bemutató folyamatát.

Az alábbi ábra bemutatja, milyen hívást indít az alkalmazás a Request Service REST API-hoz, valamint az alkalmazásnak szóló visszahívásokat.

diagram, amely az API hívását és a visszahívási eseményeket mutatja.

Konfigurálja a végpontot a bejövő HTTP POST-kérelmek figyelésére. Az alábbi kódrészlet bemutatja, hogyan kezelhető a kiállítási visszahívási HTTP-kérés, és hogyan frissíthető a felhasználói felület ennek megfelelően:

Nem alkalmazható. Válasszon egyet a többi programozási nyelv közül.

Következő lépések

További információ ezekről a specifikációkról: