Memanggil Rest API Layanan Permintaan

ID Terverifikasi Microsoft Entra menyertakan REST API Layanan Permintaan. API ini memungkinkan Anda mengeluarkan dan memverifikasi info masuk. Artikel ini menunjukkan cara untuk mulai menggunakan Layanan Permintaan REST API.

Token akses API

Aplikasi Anda perlu menyertakan token akses yang valid dengan izin yang diperlukan agar dapat mengakses Layanan Permintaan REST API. Token akses yang dikeluarkan platform identitas Microsoft berisi informasi (cakupan) yang digunakan Layanan Permintaan REST API untuk memvalidasi pemanggil. Token akses memastikan bahwa pemanggil memiliki izin yang tepat untuk melakukan operasi yang mereka minta.

Untuk mendapatkan token akses, aplikasi Anda harus didaftarkan ke platform identitas Microsoft dan diotorisasi oleh administrator untuk akses ke REQUEST Service REST API. Jika Anda belum mendaftarkan aplikasi verifiable-credentials-app, lihat cara mendaftarkan aplikasi lalu buat rahasia aplikasi.

Mendapatkan token akses

Gunakan alur pemberian kredensial klien OAuth 2.0 untuk memperoleh token akses menggunakan platform identitas Microsoft. Gunakan pustaka tepercaya untuk tujuan ini. Dalam tutorial ini, kami menggunakan Microsoft Authentication Library (MSAL). MSAL menyederhanakan penambahan autentikasi dan otorisasi ke aplikasi yang dapat memanggil API web yang aman.

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=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials

Dalam kode sebelumnya, berikan parameter berikut:

Parameter Kondisi Deskripsi
Otoritas Wajib Penyewa direktori yaitu tempat aplikasi akan dioperasikan sesuai rencana. Sebagai contoh: https://login.microsoftonline.com/{your-tenant}. (Ganti your-tenant dengan nama atau ID penyewa Anda.)
ID klien Wajib ID aplikasi yang ditetapkan ke aplikasi Anda. Anda dapat menemukan informasi ini di portal Microsoft Azure, tempat Anda mendaftarkan aplikasi Anda.
Rahasia Klien Wajib Rahasia klien yang Anda buat untuk aplikasi Anda.
Cakupan Wajib Harus diatur ke 3db474b9-6a0c-4840-96ac-1fceb342124f/.default. Pengaturan ini menghasilkan token akses dengan klaim peran .VerifiableCredential.Create.All

Untuk informasi selengkapnya tentang cara mendapatkan token akses dengan menggunakan identitas aplikasi konsol, lihat salah satu artikel berikut ini:

Anda juga dapat mengakses permintaan token dengan sertifikat alih-alih rahasia klien.

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=12345678-0000-0000-00000000000000000
&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

Panggil API

Untuk menerbitkan atau memverifikasi kredensial yang dapat diverifikasi:

  1. Buat permintaan HTTP POST ke Permintaan Layanan REST API. ID penyewa tidak diperlukan lagi di URL karena ada sebagai klaim dalam token akses.

    Masalah

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

    Verifikasi

    POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
    
  2. Lampirkan token akses sebagai token pembawa ke header otorisasi dalam permintaan HTTP.

    Authorization: Bearer <token>
    
  3. Atur header Content-Type ke Application/json.

  4. Siapkan dan lampirkan payload permintaan penerbitan atau presentasi ke isi permintaan.

  5. Kirimkan permintaan ke Layanan Permintaan REST API.

API Layanan Permintaan mengembalikan Kode Status HTTP 201 Created pada panggilan yang berhasil. Jika panggilan API mengembalikan kesalahan, periksa dokumentasi referensi kesalahan.

Contoh permintaan penerbitan

Contoh berikut menunjukkan permintaan penerbitan kredensial yang dapat diverifikasi. Untuk informasi tentang payload, lihat Spesifikasi penerbitan REST API Layanan Permintaan.

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

{...JSON payload...}

Permintaan penerbitan menggunakan idTokenHint alur pengesahan:

{
    "includeQRCode": false,
    "callback": {
        "url": "https://contoso.com/api/issuer/issuanceCallback",
        "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
        "headers": {
            "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
        }
    },
    "authority": "did:web:verifiedid.contoso.com",
    "registration": {
        "clientName": "Verifiable Credential Expert Sample"
    },
    "type": "VerifiedCredentialExpert",
    "manifestUrl": "https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/VerifiedCredentialExpert1",
    "pin": {
        "value": "3539",
        "length": 4
    },
    "claims": {
        "given_name": "Megan",
        "family_name": "Bowen"
    }
}

Untuk kode lengkapnya, lihat salah satu sampel kode berikut:

Contoh permintaan presentasi

Contoh berikut menunjukkan permintaan presentasi kredensial yang dapat diverifikasi. Untuk informasi tentang payload, lihat Spesifikasi presentasi REST API Layanan Permintaan.

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

{...JSON payload...}

Permintaan presentasi untuk kredensial dengan jenis dan pengeluar sertifikat tertentu:

{
  "includeQRCode": true,
  "callback": {
    "url": "https://contoso.com/api/verifier/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "authority": "did:web:verifiedid.contoso.com",
  "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
        }
      }
    }
  ]
}

Untuk kode lengkapnya, lihat salah satu sampel kode berikut:

Peristiwa panggilan balik

Payload permintaan berisi titik akhir panggilan balik penerbitan dan presentasi. Titik akhir adalah bagian dari aplikasi web Anda dan harus tersedia untuk umum melalui protokol HTTPS. API Layanan Permintaan memanggil titik akhir Anda untuk memberi tahu aplikasi Anda tentang peristiwa tertentu. Misalnya, peristiwa seperti itu mungkin ketika pengguna memindai kode QR, menggunakan tautan mendalam ke aplikasi pengautentikasi, atau menyelesaikan proses presentasi.

Diagram berikut menjelaskan panggilan yang dilakukan aplikasi Anda ke REQUEST Service REST API dan panggilan balik ke aplikasi Anda.

Diagram that shows the call to the API and the callback events.

Konfigurasikan titik akhir Anda untuk mendengarkan permintaan HTTP POST yang masuk. Cuplikan kode berikut menunjukkan cara menangani permintaan HTTP panggilan balik penerbitan dan cara memperbarui UI yang sesuai:

Tidak berlaku. Pilih salah satu bahasa pemrograman lainnya.

Langkah berikutnya

Pelajari lebih lanjut tentang spesifikasi ini: