Spesifikasi penerbitan REST API Layanan Permintaan

Artikel
12/07/2023

ID Terverifikasi Microsoft Entra menyertakan REST API Layanan Permintaan. API ini memungkinkan Anda untuk menerbitkan dan memverifikasi kredensial. Artikel ini menentukan REST API Layanan Permintaan untuk permintaan penerbitan. Artikel lain menjelaskan cara memanggil Request Service REST API.

Permintaan HTTP

Permintaan penerbitan Request Service REST API mendukung metode HTTP berikut:

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

Permintaan penerbitan Request Service REST API memerlukan header HTTP berikut:

Nama	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.

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

Permintaan HTTP berikut menunjukkan permintaan ke REST API Layanan Permintaan:

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

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

Payload permintaan penerbitan berisi informasi tentang permintaan penerbitan kredensial yang dapat diverifikasi. Contoh berikut menunjukkan permintaan penerbitan dengan menggunakan alur kode PIN dengan klaim pengguna, seperti nama depan dan nama belakang. Hasil dari permintaan ini menampilkan kode QR dengan tautan untuk memulai proses penerbitan.

{
  "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",
  "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"
}

Payload berisi properti berikut:

Parameter	Jenis	Deskripsi
`includeQRCode`	Boolean	Menentukan apakah kode QR disertakan dalam respons permintaan ini. Berikan kode QR dan minta pengguna memindainya. Memindai kode QR meluncurkan aplikasi pengautentikasi dengan permintaan penerbitan ini. Kemungkinan nilainya adalah `true` (default) atau `false`. Saat Anda mengatur nilai ke `false`, gunakan properti pengembalian `url` untuk merender tautan langsung.
`callback`	Panggilan balik	Wajib. Memungkinkan pengembang secara asinkron mendapatkan informasi tentang alur selama proses penerbitan kredensial yang dapat diverifikasi. Misalnya, pengembang mungkin menginginkan panggilan saat pengguna telah memindai kode QR atau jika permintaan penerbitan berhasil atau gagal.
`authority`	string	Pengidentifikasi terdesentralisasi (DID) penerbit. Untuk mengetahui informasi selengkapnya, lihat Mengumpulkan info masuk dan detail lingkungan untuk menyiapkan aplikasi sampel Anda.
`registration`	RequestRegistration	Memberikan informasi tentang penerbit yang dapat ditampilkan di aplikasi pengautentikasi.
`type`	string	Jenis kredensial yang dapat diverifikasi. Harus cocok dengan jenis seperti yang didefinisikan dalam manifes kredensial yang dapat diverifikasi. Sebagai contoh: `VerifiedCredentialExpert`. Untuk informasi selengkapnya, lihat Membuat kartu ahli kredensial terverifikasi di Azure.
`manifest`	string	URL dokumen manifes kredensial yang dapat diverifikasi. Untuk mengetahui informasi selengkapnya, lihat Mengumpulkan info masuk dan detail lingkungan untuk menyiapkan aplikasi sampel Anda.
`claims`	string	Opsional. Hanya dapat digunakan untuk alur pengesahan petunjuk token ID untuk menyertakan kumpulan pernyataan yang dibuat tentang subjek dalam kredensial yang dapat diverifikasi.
`pin`	PIN	Opsional. Kode PIN hanya dapat digunakan dengan alur pengesahan petunjuk token ID. Nomor PIN untuk memberikan keamanan ekstra selama penerbitan. Anda membuat kode PIN, dan memberikannya kepada pengguna di aplikasi Anda. Pengguna harus memberikan kode PIN yang Anda buat.
`expirationDate`	string	Opsional. ExpirationDate hanya dapat digunakan dengan alur pengesahan petunjuk token ID. Jika ditentukan, nilai harus berupa tanggal yang dinyatakan dalam format ISO8601 . Tanggal akan mengambil alih validityInterval dalam definisi aturan kredensial untuk permintaan penerbitan ini. Gunakan pengaturan ini untuk mengontrol secara eksplisit ketika kredensial kedaluwarsa, seperti akhir hari, akhir bulan atau akhir tahun, terlepas dari kapan kredensial dikeluarkan. Harap dicatat bahwa tanggal dinyatakan dalam format UTC. Jika Anda menentukan akhir tahun, dengan waktu yang diatur ke `23:59:59`, yaitu 1 detik hingga tengah malam dalam waktu UTC. Setiap pengguna dalam zona waktu yang berbeda akan mendapatkan tanggal kedaluwarsa yang disajikan dalam zona waktu lokal di Microsoft Authenticator. Ini berarti bahwa jika Anda berada di zona waktu CET, itu akan disajikan sebagai 1 Januari 1 pagi. Kontrak kredensial harus memiliki bendera allowOverrideValidityOnIssuance yang diatur ke true.

Saat ini ada empat jenis pengesahan klaim yang dapat Anda kirim di payload. Microsoft Entra Verified ID menggunakan empat cara untuk memasukkan klaim ke dalam kredensial yang dapat diverifikasi dan membuktikan informasi tersebut dengan DID pengeluar sertifikat. Berikut keempat jenisnya:

Token ID
Petunjuk token ID
Kredensial yang dapat diverifikasi melalui presentasi yang dapat diverifikasi
Klaim yang dibuktikan sendiri

Anda dapat menemukan informasi mendetail tentang jenis input di Menyesuaikan kredensial Anda yang dapat diverifikasi.

Jenis RequestRegistration

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

Properti	Tipe	Deskripsi
`clientName`	string	Nama tampilan penerbit kredensial yang dapat diverifikasi.
`logoUrl`	string	Opsional. URL untuk logo penerbit.
`termsOfServiceUrl`	string	Opsional. URL untuk ketentuan penggunaan kredensial yang dapat diverifikasi yang Anda terbitkan.

Catatan

Saat ini, informasi RequestRegistration tidak diberikan selama penerbitan di aplikasi Microsoft Authenticator. Tetapi, informasi ini dapat digunakan dalam payload.

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 akan mengarah ke titik akhir yang dapat dijangkau di internet, jika tidak, layanan akan memunculkan kesalahan URL panggilan balik yang tidak dapat dibaca. Menerima format 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 valid

Jenis Sematkan

Jenis pin menentukan kode PIN yang dapat ditampilkan sebagai bagian dari penerbitan. pin adalah opsional, dan, jika digunakan, harus selalu dikirim secara out-of-band. Saat menggunakan kode PIN HASH, Anda harus menentukan properti salt, alg, dan iterations. pin berisi properti berikut:

Properti	Tipe	Deskripsi
`value`	string	Berisi nilai PIN dalam teks biasa. Saat Anda menggunakan PIN yang di-hash, properti nilai berisi hash dengan salt, dikodekan base64.
`type`	string	Jenis kode PIN. Kemungkinan nilai: `numeric` (default).
`length`	Integer	Panjang kode PIN. Panjang default adalah 6, minimum adalah 4, dan maksimum adalah 16.
`salt`	string	Salt dari kode PIN yang di-hash. Salt sudah ditambahkan selama perhitungan hash. Pengodean: UTF-8.
`alg`	string	Algoritme hash untuk PIN yang di-hash. Algoritme yang didukung: `sha256`.
`iterations`	Integer	Jumlah iterasi hash. Nilai yang mungkin: `1`.

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": "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>"  
}

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 penerbitan dan panggilan baliknya.
`url`	string	URL yang meluncurkan aplikasi pengautentikasi dan memulai proses penerbitan. 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 penerbitan.

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

Respons kesalahan

Jika ada kesalahan dengan permintaan, respons kesalahan akan 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 penerbitan.

Properti	Tipe	Deskripsi
`requestId`	string	Dipetakan ke permintaan asli saat payload diposting ke layanan Kredensial yang Dapat Diverifikasi.
`requestStatus`	string	Status dikembalikan untuk permintaan. Nilai yang memungkinkan: `request_retrieved`: Pengguna memindai kode QR atau memilih tautan yang memulai alur penerbitan. `issuance_successful`: Penerbitan kredensial yang dapat diverifikasi berhasil. `issuance_error`: Terjadi kesalahan selama penerbitan. Untuk detailnya, lihat properti `error`.
`state`	string	Menampilkan nilai status yang Anda berikan dalam payload asli.
`error`	kesalahan	Ketika nilai properti `code` adalah `issuance_error`, properti ini berisi informasi tentang kesalahan.
`error.code`	string	Kode kesalahan pengembalian.
`error.message`	string	Pesan kesalahan.

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

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

Contoh berikut menunjukkan payload panggilan balik setelah pengguna berhasil menyelesaikan proses penerbitan:

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

Kesalahan panggilan balik

Titik akhir panggilan balik mungkin dipanggil dengan pesan kesalahan. Tabel berikut mencantumkan kode galat:

Pesan	Definisi
`fetch_contract_error`	Tidak dapat mengambil kontrak kredensial yang dapat diverifikasi. Kesalahan ini biasanya terjadi saat API tidak dapat mengambil manifes yang Anda tentukan di payload permintaan objek RequestIssuance.
`issuance_service_error`	Layanan Kredensial yang Dapat Diverifikasi tidak dapat memvalidasi persyaratan, atau ada yang tidak beres dalam Kredensial yang Dapat Diverifikasi.
`unspecified_error`	Kesalahan ini jarang terjadi, tetapi patut diselidiki.

Contoh berikut menunjukkan payload panggilan balik saat terjadi kesalahan:

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

Langkah berikutnya

Pelajari cara memanggil REST API Layanan Permintaan.

Bagikan melalui