Spesifikasi presentasi REST API Layanan Permintaan (pratinjau)

Catatan

Kredensial yang dapat Diverifikasi Azure Active Directory sekarang menjadi ID Terverifikasi Microsoft Entra dan bagian dari rangkaian produk Microsoft Entra. Kami akan memperbarui dokumentasi dalam beberapa bulan ke depan saat kami bergerak menuju Ketersediaan Umum (GA). Pelajari selengkapnya tentang rangkaian Microsoft Entra solusi identitas dan mulai di pusat admin Microsoft Entra terpadu.

ID Terverifikasi Microsoft Entra menyertakan Request Service REST API. 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 Request Service 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://www.contoso.com/api/verifier/presentationCallbac",
    "state": "11111111-2222-2222-2222-333333333333",
      "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 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:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "callback": {
    "url": "https://www.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:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ...<SNIP>..."
      ],
      "configuration": {
        "validation": {
          "allowRevoked": false,
          "validateLinkedDomain": false
        }
      }
    }
  ]
}

Payload berisi properti berikut.

Parameter Jenis Deskripsi
includeQRCode Boolean Menentukan apakah kode QR disertakan dalam respons permintaan ini. Berikan kode QR dan minta pengguna untuk memindainya. Memindai kode QR meluncurkan aplikasi pengautentikasi dengan permintaan presentasi ini. Nilai yang mungkin adalah true (default) atau false. Saat Anda mengatur nilai ke false, gunakan properti pengembalian url untuk merender tautan langsung.
includeReceipt Boolean 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) dari penyewa Azure Active Directory 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 koleksi Koleksi objek RequestCredential.

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. Nama ini akan ditampilkan kepada pengguna di aplikasi pengautentikasi.

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 Jenis 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 Jenis 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 Berikan informasi tentang tujuan meminta kredensial yang dapat diverifikasi ini.
acceptedIssuers koleksi string 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) .
configuration.validation Configuration.Validation Pengaturan opsional untuk validasi presentasi.

Jenis Validasi Konfigurasi

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

Properti Jenis Deskripsi
allowRevoked Boolean Menentukan apakah info masuk yang dicabut harus diterima. Defaultnya adalah false (seharusnya tidak diterima).
validateLinkedDomain Boolean Menentukan apakah domain tertaut harus divalidasi. Defaultnya adalah true (harus divalidasi). Mengatur bendera ini ke false berarti Anda akan 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.

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/request/e4ef27ca-eb8c-4b63-823b-3b95140eac11",
    "expiry": 1633017751,
    "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 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 bilangan bulat 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 Jenis Deskripsi
requestId string Dipetakan ke permintaan asli saat payload diposting ke layanan Kredensial yang Dapat Diverifikasi.
code string Kode 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.
state string Menampilkan nilai status yang Anda berikan dalam payload asli.
subject string DID pengguna kredensial yang dapat diverifikasi.
issuers array Menampilkan array kredensial yang dapat diverifikasi yang diminta. Untuk setiap kredensial yang dapat diverifikasi, pengguna 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",
        "code":"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",
      "code": "presentation_verified",
      "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
      "subject": "did:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W<SNIP>…",
      "issuers": [
        {
          "type": [
            "VerifiableCredential",
            "VerifiedCredentialExpert"
          ],
          "claims": {
            "firstName": "Megan",
            "lastName": "Bowen"
          },
          "domain": "https://contoso.com/",
          "verified": "DNS",
          "authority": "did:ion:….."
        }
      ],
      "receipt": {
        "id_token": "eyJraWQiOiJkaWQ6aW<SNIP>"
      }
    } 
    

    Langkah berikutnya

    Pelajari cara memanggil REST API Layanan Permintaan.