Spesifikasi penerbitan REST API Layanan Permintaan
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>
{
"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.
{
"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"
}
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 penerbitan ini. Nilai yang mungkin adalah true atau false (default). 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 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. Misalnya: 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 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 waktu penerbitan. 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 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 | Jenis | 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 | Jenis | Deskripsi |
---|---|---|
url |
string | URI ke titik akhir panggilan balik aplikasi Anda. URI harus menunjuk ke titik akhir yang dapat dijangkau di internet jika tidak, layanan melemparkan kesalahan URL panggilan balik yang tidak dapat dibaca. Format yang diterima IPv4, IPv6, atau nama host DNS yang dapat diselesaikan. Untuk mengeraskan jaringan Anda, lihat FAQ. |
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 melemparkan 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 | Jenis | 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 | Jenis | 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 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 dikembalikan. Aplikasi harus menangani respons dengan tepat.
Peristiwa panggilan balik
Titik akhir panggilan balik dipanggil saat pengguna memindai kode QR, menggunakan tautan langsung aplikasi pengautentikasi, atau menyelesaikan proses penerbitan.
Properti | Jenis | 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:
|
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”,
}
}