Spesifikasi presentasi REST API Layanan Permintaan

Artikel
02/06/2024

ID Terverifikasi Microsoft Entra menyertakan REST API Layanan Permintaan. API ini memungkinkan Anda untuk menerbitkan dan memverifikasi kredensial. Artikel ini menetapkan Request Service REST API untuk permintaan presentasi. Permintaan presentasi meminta pengguna untuk menunjukkan kredensial yang dapat diverifikasi, lalu memverifikasi kredensial tersebut. Artikel lain menjelaskan cara memanggil Request Service REST API.

Permintaan HTTP

Permintaan presentasi Request Service REST API mendukung metode HTTP berikut:

Metode	Catatan
POST	Dengan payload JSON seperti yang ditentukan dalam artikel ini.

Permintaan presentasi Request Service REST API memerlukan header HTTP berikut:

Metode	Nilai
`Authorization`	Lampirkan token akses sebagai token pembawa ke header otorisasi dalam permintaan HTTP. Contohnya,`Authorization: Bearer <token>`.
`Content-Type`	`Application/json`

Buat permintaan HTTP POST ke Permintaan Layanan REST API. tenantId tidak diperlukan lagi di URL karena ada sebagai klaim di access_token.

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

Permintaan berikut menunjukkan permintaan presentasi ke Request Service REST API:

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

{
    "includeQRCode": true,
    "callback": {
      "url": "https://contoso.com/api/verifier/presentationCallback",
      "state": "11111111-2222-2222-2222-333333333333",
      "headers": {
        "api-key": "an-api-key-can-go-here"
      }
    },
    ...
}

Izin berikut diperlukan untuk menghubungi Request Service REST API. Untuk informasi selengkapnya, lihat Memberikan izin untuk mendapatkan token akses.

Jenis izin	Izin
Aplikasi	3db474b9-6a0c-4840-96ac-1fceb342124f/.default

Payload permintaan presentasi

Payload permintaan presentasi berisi informasi tentang permintaan presentasi kredensial yang dapat diverifikasi. Contoh berikut menunjukkan permintaan presentasi dari penerbit tertentu. Hasil permintaan ini menampilkan kode QR dengan tautan untuk memulai proses presentasi.

{
  "includeQRCode": true,
  "includeReceipt": true,
  "authority": "did:web:verifiedid.contoso.com",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://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:web:verifiedid.contoso.com"
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

Payload berisi properti berikut.

Parameter	Jenis	Deskripsi
`includeQRCode`	Boolean	Opsional. Menentukan apakah kode QR disertakan dalam respons permintaan ini. Berikan kode QR dan minta pengguna memindainya. Memindai kode QR meluncurkan aplikasi pengautentikasi dengan permintaan presentasi ini. Kemungkinan nilainya adalah `true` (default) atau `false`. Saat Anda mengatur nilai ke `false`, gunakan properti pengembalian `url` untuk merender tautan langsung.
`includeReceipt`	Boolean	Opsional. Menentukan apakah tanda terima harus disertakan dalam respons permintaan ini. Nilai yang mungkin adalah `true` atau `false` (default). Tanda terima berisi payload asli yang dikirim dari pengautentikasi ke layanan Kredensial yang Dapat Diverifikasi. Tanda terima berguna untuk pemecahan masalah atau jika Anda memiliki kebutuhan untuk ge detail lengkap payload. Jika tidak, tidak perlu mengatur nilai ini ke `true` secara default. Dalam permintaan `OpenId Connect SIOP`, tanda terima berisi token ID dari permintaan asli.
`authority`	string	Pengidentifikasi terdesentralisasi (DID) penyewa Microsoft Entra pemverifikasi Anda. Untuk informasi selengkapnya, lihat Mengumpulkan detail penyewa untuk menyiapkan aplikasi contoh Anda.
`registration`	RequestRegistration	Memberikan informasi tentang pemverifikasi.
`callback`	Panggilan balik	Wajib. Memungkinkan pengembang memperbarui UI selama proses presentasi kredensial yang dapat diverifikasi. Ketika pengguna menyelesaikan proses, lanjutkan proses setelah hasilnya dikembalikan ke aplikasi.
`requestedCredentials`	collection	Koleksi objek RequestCredential.

Jenis RequestRegistration

Jenis RequestRegistration menyediakan pendaftaran informasi untuk penerbit. Jenis RequestRegistration berisi properti berikut:

Properti	Tipe	Deskripsi
`clientName`	string	Nama tampilan pemverifikasi kredensial yang dapat diverifikasi. Nama ini akan ditampilkan kepada pengguna di aplikasi pengautentikasi.
`purpose`	string	Opsional. String yang ditampilkan untuk memberi tahu pengguna mengapa kredensial yang dapat diverifikasi diminta.
`logoUrl`	URL	Opsional. URL untuk jenis logo pemverifikasi. Ini tidak digunakan oleh aplikasi Authenticator.
`termsOfServiceUrl`	URL	Opsional. URL ke ketentuan layanan untuk pemverifikasi. Ini tidak digunakan oleh aplikasi Authenticator.

Cuplikan layar berikut memperlihatkan properti clientName dan nama tampilan authority (pemverifikasi) dalam permintaan presentasi.

Cuplikan layar yang menunjukkan cara menyetujui permintaan presentasi.

Jenis panggilan balik

Request Service REST API membuat beberapa peristiwa ke titik akhir panggilan balik. Peristiwa ini memungkinkan Anda untuk memperbarui antarmuka pengguna dan melanjutkan proses setelah hasilnya ditampilkan ke aplikasi. Jenis Callback berisi properti berikut:

Properti	Tipe	Deskripsi
`url`	string	URI ke titik akhir panggilan balik aplikasi Anda. URI harus mengarah ke titik akhir yang dapat dijangkau di internet jika tidak, layanan akan memunculkan kesalahan URL panggilan balik yang tidak dapat dibaca. Menerima input IPv4, IPv6, atau nama host yang dapat diselesaikan DNS.
`state`	string	Menghubungkan peristiwa panggilan balik dengan status yang diteruskan dalam payload asli.
`headers`	string	Opsional. Anda dapat menyertakan koleksi header HTTP yang diperlukan oleh bagian penerima pesan POST. Nilai header yang didukung saat ini adalah header `api-key` atau `Authorization`. Header lain mana pun akan memunculkan kesalahan header panggilan balik yang tidak sah.

Jenis RequestCredential

RequestCredential memberikan informasi tentang kredensial yang diminta yang harus diberikan pengguna. RequestCredential berisi properti berikut:

Properti	Tipe	Deskripsi
`type`	string	Jenis kredensial yang dapat diverifikasi. `type` harus cocok dengan jenis yang ditentukan dalam `issuer` manifes kredensial yang dapat diverifikasi (misalnya, `VerifiedCredentialExpert`). Untuk mendapatkan manifes penerbit, lihat Mengumpulkan kredensial dan detail lingkungan untuk menyiapkan aplikasi contoh Anda. Salin URL kredensial masalah, buka di browser web, dan periksa properti id.
`purpose`	string	Opsional. Berikan informasi tentang tujuan meminta kredensial yang dapat diverifikasi ini. Ini tidak digunakan oleh aplikasi Authenticator.
`acceptedIssuers`	koleksi string	Opsional. Kumpulan DID penerbit yang dapat menerbitkan jenis kredensial yang dapat diverifikasi yang dapat disajikan oleh subjek. Untuk mendapatkan DID penerbit Anda, lihat Mengumpulkan kredensial dan detail lingkungan untuk menyiapkan aplikasi contoh Anda, dan salin nilai Pengidentifikasi terdesentralisasi (DID). `acceptedIssuers` Jika koleksi kosong atau tidak ada, maka permintaan presentasi akan menerima jenis kredensial yang dikeluarkan oleh penerbit mana pun.
`configuration.validation`	Configuration.Validation	Pengaturan opsional untuk validasi presentasi.
`constraints`	Kendala	Opsional. Pengumpulan batasan klaim.

Jenis Validasi Konfigurasi

Configuration.Validation menyediakan informasi mengenai info masuk yang disajikan harus divalidasi. Berisi properti berikut:

Properti	Tipe	Deskripsi
`allowRevoked`	Boolean	Opsional. Menentukan apakah info masuk yang dicabut harus diterima. Defaultnya adalah `false` (seharusnya tidak diterima).
`validateLinkedDomain`	Boolean	Opsional. Menentukan apakah domain tertaut harus divalidasi. Defaultnya adalah `false`. Mengatur bendera ini ke `false` berarti bahwa Anda sebagai aplikasi Pihak yang Mengandalkan menerima info masuk dari domain tertaut yang belum diverifikasi. Mengatur bendera ini ke `true` berarti domain tertaut akan divalidasi dan hanya domain terverifikasi yang akan diterima.
`faceCheck`	faceCheck	Opsional. Memungkinkan meminta pemeriksaan liveness selama presentasi.

Jenis batasan

Jenis berisi constraints kumpulan batasan klaim yang harus dipenuhi ketika dompet memilih kredensial kandidat. Ini memungkinkan permintaan kredensial dengan nilai klaim tertentu. Batasan yang ditentukan akan menggunakan logika AND, yaitu jika Anda menentukan tiga batasan, semuanya harus dipenuhi. Untuk setiap batasan dalam koleksi, Anda harus memilih satu operand nilai, berisi atau memulaiWith. Nilai tidak dapat berupa ekspresi reguler. Semua perbandingan tidak peka huruf besar/kecil.

Properti	Tipe	Deskripsi
`claimName`	string	Wajib. Nama klaim untuk batasan. Ini adalah nama klaim dalam kredensial yang dapat diverifikasi. Lihat outputClaim dalam jenis claimMapping.
`values`	koleksi string	Kumpulan nilai yang harus cocok dengan nilai klaim. Jika Anda menentukan beberapa nilai, seperti ["merah", "hijau", "biru"] itu cocok jika nilai klaim dalam kredensial memiliki salah satu nilai dalam koleksi.
`contains`	string	Batasan mengevaluasi ke true jika nilai klaim berisi nilai yang ditentukan.
`startsWith`	string	Batasan mengevaluasi ke true jika nilai klaim dimulai dengan nilai yang ditentukan.

jenis faceCheck

Jenis faceCheck berisi informasi untuk melakukan pemeriksaan keakuratan selama presentasi kredensial. Kredensial yang diminta harus berisi foto pemegang dalam klaim yang dinamai oleh sourcePhotoClaimName. Presentasi akan berhasil jika pemeriksaan liveness mencapai tingkat keyakinan yang sama atau lebih besar dengan apa yang ditentukan dalam properti matchConfidenceThreshold. Jika ambang tidak terpenuhi, seluruh presentasi akan gagal.

Properti	Tipe	Deskripsi
`sourcePhotoClaimName`	string	Wajib. Nama klaim dalam kredensial yang berisi foto. Lihat outputClaim dalam jenis claimMapping.
`matchConfidenceThreshold`	Integer	Opsional. Ambang rahasia untuk pemeriksaan yang berhasil antara foto dan data keakuratan. Harus berupa bilangan bulat antara 50 dan 100. Defaultnya adalah 70.

Respons berhasil

Jika berhasil, metode ini menampilkan kode respons (HTTP 201 Dibuat), dan koleksi objek peristiwa di isi respons. JSON berikut menunjukkan respons yang berhasil:

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "url": "openid-vc://?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/presentationRequests/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "qrCode": "data:image/png;base64,iVBORw0KGgoA<SNIP>"
}

Respons berisi properti berikut:

Properti	Tipe	Deskripsi
`requestId`	string	ID permintaan yang dibuat secara otomatis. Panggilan balik menggunakan permintaan yang sama, memungkinkan Anda melacak permintaan presentasi dan panggilan baliknya.
`url`	string	URL yang meluncurkan aplikasi pengautentikasi dan memulai proses presentasi. Anda dapat memberikan URL ini kepada pengguna jika mereka tidak dapat memindai kode QR.
`expiry`	Integer	Menunjukkan kapan respons akan kedaluwarsa.
`qrCode`	string	Kode QR yang dapat dipindai pengguna untuk memulai alur presentasi.

Saat aplikasi Anda menerima respons, aplikasi perlu memberikan kode QR kepada pengguna. Pengguna memindai kode QR, yang membuka aplikasi pengautentikasi dan memulai proses presentasi.

Respons kesalahan

Jika ada kesalahan dengan permintaan, respons kesalahan dikembalikan, dan harus ditangani dengan tepat oleh aplikasi.

Peristiwa panggilan balik

Titik akhir panggilan balik dipanggil saat pengguna memindai kode QR, menggunakan tautan langsung aplikasi pengautentikasi, atau menyelesaikan proses presentasi.

Properti	Tipe	Deskripsi
`requestId`	string	Dipetakan ke permintaan asli saat payload diposting ke layanan Kredensial yang Dapat Diverifikasi.
`requestStatus`	string	Status ditampilkan saat permintaan diambil oleh aplikasi pengautentikasi. Nilai yang memungkinkan: `request_retrieved`: Pengguna memindai kode QR atau memilih tautan yang memulai alur presentasi. `presentation_verified`: Validasi kredensial yang dapat diverifikasi berhasil diselesaikan. li>`presentation_error`: Ada kesalahan dalam presentasi.
`state`	string	Menampilkan nilai status yang Anda berikan dalam payload asli.
`subject`	string	DID pengguna kredensial yang dapat diverifikasi.
`verifiedCredentialsData`	array	Menampilkan array kredensial yang dapat diverifikasi yang diminta. Untuk setiap kredensial yang dapat diverifikasi, ini menyediakan: Jenis kredensial yang dapat diverifikasi. DID pengeluar sertifikat Klaim diambil. Domain pengeluar sertifikat kredensial yang dapat diverifikasi. Status validasi domain pengeluar sertifikat kredensial yang dapat diverifikasi.
`receipt`	string	Opsional. Tanda terima berisi payload asli yang dikirim dari dompet ke layanan Kredensial yang Dapat Diverifikasi. Tanda terima harus digunakan untuk pemecahan masalah / debug saja. Format tanda terima tidak diperbaiki dan dapat berubah berdasarkan dompet dan versi yang digunakan.

Contoh berikut menunjukkan payload panggilan balik saat aplikasi pengautentikasi memulai permintaan presentasi:

{
    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "requestStatus":"request_retrieved",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58"
}

Contoh berikut menunjukkan payload panggilan balik setelah presentasi kredensial yang dapat diverifikasi berhasil diselesaikan:

{
  "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",
  "requestStatus": "presentation_verified",
  "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
  "subject": "did:web:verifiedid.contoso.com",
  "verifiedCredentialsData": [
    {
      "issuer": "did:web:issuer...",
      "type": [
        "VerifiableCredential",
        "VerifiedCredentialExpert"
      ],
      "claims": {
        "firstName": "Megan",
        "lastName": "Bowen"
      },
      "credentialState": {
        "revocationStatus": "VALID"
      },
      "domainValidation": {
        "url": "https://contoso.com/"
      },
      "issuanceDate": "yyyy-MM-ddTHH:mm:ssZ",
      "expirationDate": "yyyy-MM-ddTHH:mm:ssZ"
    }
  ],
  "receipt": {
    "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>",
    "vp_token": "...",
    "state": "..."
  }
}

Langkah berikutnya

Pelajari cara memanggil REST API Layanan Permintaan.