Spesifikasi penerbitan REST API Layanan Permintaan

Catatan

Kredensial yang dapat Diverifikasi Azure Active Directory sekarang menjadi ID Terverifikasi Microsoft Entra dan bagian dari rangkaian produk Microsoft Entra. Pelajari selengkapnya tentang rangkaian Microsoft Entra solusi identitas dan mulai di pusat admin Microsoft Entra terpadu.

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 REST API Layanan Permintaan.

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 Request Service 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://wwww.contoso.com/vc/callback",
        "state": "Aaaabbbb11112222",
        "headers": {
            "api-key": "an-api-key-can-go-here"
        }
    },
    ...
}

Izin berikut diperlukan untuk memanggil 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": true,
  "callback": {
    "url": "https://www.contoso.com/api/issuer/issuanceCallback",
    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDek...",
  "registration": {
    "clientName": "Verifiable Credential Expert Sample"
  },
  "type": "VerifiedCredentialExpert",
  "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest",
  "claims": {
    "given_name": "Megan",
    "family_name": "Bowen"
  },
  "pin": {
    "value": "3539",
    "length": 4
  }
}

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. Nilai yang mungkin 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. 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. Digunakan untuk alur ID token hint untuk menyertakan kumpulan pernyataan yang dibuat tentang subjek dalam kredensial yang dapat diverifikasi. Untuk alur kode PIN, penting bagi Anda untuk memberikan nama depan dan nama belakang pengguna. Untuk informasi selengkapnya, lihat Nama kredensial yang dapat diverifikasi.
pin PIN Opsional. Nomor PIN untuk memberikan keamanan ekstra selama penerbitan. Untuk alur kode PIN, properti ini diperlukan. Anda membuat kode PIN, dan memberikannya kepada pengguna di aplikasi Anda. Pengguna harus memberikan kode PIN yang Anda buat.

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 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 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 bilangan bulat 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 bilangan bulat 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/12345678-0000-0000-0000-000000000000/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 bilangan bulat 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 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:
  • 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.