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 mengeluarkan dan memverifikasi info masuk. Artikel ini menunjukkan cara untuk mulai menggunakan Layanan Permintaan REST API.

Token akses API

Aplikasi Anda perlu menyertakan token akses yang valid dengan izin yang diperlukan agar dapat mengakses Layanan Permintaan REST API. Token akses yang dikeluarkan platform identitas Microsoft berisi informasi (cakupan) yang digunakan Layanan Permintaan REST API untuk memvalidasi pemanggil. Token akses memastikan bahwa pemanggil memiliki izin yang tepat untuk melakukan operasi yang mereka minta.

Untuk mendapatkan token akses, aplikasi Anda harus terdaftar pada platform identitas Microsoft, dan disahkan oleh administrator untuk akses ke REST API Layanan Permintaan. Jika Anda belum mendaftarkan aplikasi verifiable-credentials-app, lihat cara mendaftarkan aplikasi lalu buat rahasia aplikasi.

Mendapatkan token akses

Gunakan alur pemberian kredensial klien OAuth 2.0 untuk memperoleh token akses menggunakan platform identitas Microsoft. Gunakan pustaka tepercaya untuk tujuan ini. Dalam tutorial ini, kami menggunakan Microsoft Authentication Library MSAL. MSAL menyederhanakan penambahan autentikasi dan otorisasi ke aplikasi yang dapat memanggil API web yang aman.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials

Dalam kode sebelumnya, berikan parameter berikut:

Parameter Kondisi Deskripsi
Otoritas Diperlukan Penyewa direktori yaitu tempat aplikasi akan dioperasikan sesuai rencana. Misalnya: https://login.microsoftonline.com/{your-tenant}. (Ganti your-tenant dengan nama atau ID penyewa Anda.)
ID Klien Diperlukan ID aplikasi yang ditetapkan ke aplikasi Anda. Anda dapat menemukan informasi ini di portal Microsoft Azure, tempat Anda mendaftarkan aplikasi Anda.
Rahasia klien Diperlukan Rahasia klien yang Anda buat untuk aplikasi Anda.
Cakupan Diperlukan Harus diatur ke 3db474b9-6a0c-4840-96ac-1fceb342124f/.default. Ini akan menghasilkan token akses dengan klaim peranVerifiableCredential.Create.All.

Untuk informasi selengkapnya tentang cara mendapatkan token akses menggunakan identitas aplikasi konsol, lihat salah satu artikel berikut: C#, Python, Node.js, atau Java.

Anda juga dapat mengakses permintaan token dengan sertifikat bukan dengan rahasia klien.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1   //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=12345678-0000-0000-00000000000000000
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

Panggil API

Untuk menerbitkan atau memverifikasi kredensial yang dapat diverifikasi, ikuti langkah-langkah berikut:

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

    Masalah

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

    Verifikasi

    POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest
    
  2. Lampirkan token akses sebagai token pembawa ke header otorisasi dalam permintaan HTTP.

    Authorization: Bearer <token>
    
  3. Atur header Content-Type ke Application/json.

  4. Siapkan dan lampirkan payload permintaan penerbitan atau presentasi ke isi permintaan.

  5. Kirimkan permintaan ke Layanan Permintaan REST API.

API Layanan Permintaan mengembalikan Kode Status HTTP 201 Created pada panggilan yang berhasil. Jika panggilan API mengembalikan kesalahan, harap periksa dokumentasi referensi kesalahan. //TODO

Contoh permintaan penerbitan

Contoh berikut menunjukkan permintaan penerbitan kredensial yang dapat diverifikasi. Untuk informasi tentang payload, lihat Spesifikasi penerbitan 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://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",
    "manifestUrl": "https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/VerifiedCredentialExpert1",
    "pin": {
        "value": "3539",
        "length": 4
    },
    "claims": {
        "given_name": "Megan",
        "family_name": "Bowen"
    }
}

Untuk kode lengkapnya, lihat salah satu sampel kode berikut:

Contoh permintaan presentasi

Contoh berikut menunjukkan permintaan presentasi kredensial yang dapat diverifikasi. Untuk informasi tentang payload, lihat Spesifikasi presentasi REST API Layanan Permintaan.

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/presentationCallback",
    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58",
    "headers": {
      "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS"
    }
  },
  "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiOiJiRWo5MDY...",
  "registration": {
    "clientName": "Veritable Credential Expert Verifier"
  },
  "includeReceipt": true,
  "requestedCredentials": [
    {
      "type": "VerifiedCredentialExpert",
      "purpose": "So we can see that you a veritable credentials expert",
      "acceptedIssuers": [
        "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiO..."
      ],
      "configuration": {
        "validation": {
          "allowRevoked": true,
          "validateLinkedDomain": true
        }
      }
    }
  ]
}

Untuk kode lengkapnya, lihat salah satu sampel kode berikut:

Peristiwa panggilan balik

Payload permintaan berisi titik akhir panggilan balik penerbitan dan presentasi. Titik akhir adalah bagian dari aplikasi web Anda, dan harus tersedia untuk umum melalui protokol HTTPS. API Layanan Permintaan memanggil titik akhir Anda untuk memberi tahu aplikasi Anda tentang peristiwa tertentu. Misalnya, peristiwa tersebut mungkin terjadi saat pengguna memindai kode QR, menggunakan tautan dalam aplikasi pengautentikasi, atau menyelesaikan proses presentasi.

Diagram berikut menjelaskan panggilan yang dilakukan aplikasi Anda ke Layanan Permintaan REST API, dan panggilan balik ke aplikasi Anda.

Diagram yang menjelaskan panggilan ke API dan peristiwa panggilan balik.

Konfigurasikan titik akhir Anda untuk mendengarkan permintaan HTTP POST yang masuk. Cuplikan kode berikut menunjukkan cara menangani permintaan HTTP panggilan balik penerbitan, dan cara memperbarui UI yang sesuai:

Tidak dapat diterapkan. Pilih salah satu bahasa pemrograman lainnya.

Langkah berikutnya

Pelajari lebih lanjut tentang spesifikasi ini: