Share via

Autentikasi dengan BOT Koneksi or API

  • Artikel

Bot Anda berkomunikasi dengan layanan Bot Koneksi or menggunakan HTTP melalui saluran aman (SSL/TLS). Saat bot Anda mengirim permintaan ke layanan Koneksi or, bot tersebut harus menyertakan informasi yang dapat digunakan layanan Koneksi or untuk memverifikasi identitasnya. Demikian juga, ketika layanan Koneksi or mengirim permintaan ke bot Anda, layanan tersebut harus menyertakan informasi yang dapat digunakan bot untuk memverifikasi identitasnya. Artikel ini menjelaskan teknologi dan persyaratan autentikasi untuk autentikasi tingkat layanan yang berlangsung antara bot dan layanan Bot Koneksi or. Jika Anda menulis kode autentikasi Anda sendiri, Anda harus menerapkan prosedur keamanan yang dijelaskan dalam artikel ini untuk memungkinkan bot Anda bertukar pesan dengan layanan Bot Koneksi or.

Penting

Jika Anda menulis kode autentikasi Anda sendiri, sangat penting bagi Anda untuk menerapkan semua prosedur keamanan dengan benar. Dengan menerapkan semua langkah dalam artikel ini, Anda dapat mengurangi risiko penyerang dapat membaca pesan yang dikirim ke bot Anda, mengirim pesan yang meniru bot Anda, dan mencuri kunci rahasia.

Jika Anda menggunakan Bot Framework SDK, Anda tidak perlu menerapkan prosedur keamanan yang dijelaskan dalam artikel ini, karena SDK secara otomatis melakukannya untuk Anda. Cukup konfigurasikan proyek Anda dengan ID Aplikasi dan kata sandi yang Anda peroleh untuk bot Anda selama pendaftaran dan SDK akan menangani sisanya.

Teknologi autentikasi

Empat teknologi autentikasi digunakan untuk membangun kepercayaan antara bot dan bot Koneksi or:

Teknologi Deskripsi
SSL/TLS SSL/TLS digunakan untuk semua koneksi layanan-ke-layanan. X.509v3 sertifikat digunakan untuk menetapkan identitas semua layanan HTTPS. Klien harus selalu memeriksa sertifikat layanan untuk memastikan sertifikat tersebut tepercaya dan valid. (Sertifikat klien TIDAK digunakan sebagai bagian dari skema ini.)
OAuth 2.0 OAuth 2.0 menggunakan layanan masuk akun ID Microsoft Entra untuk menghasilkan token aman yang dapat digunakan bot untuk mengirim pesan. Token ini adalah token layanan-ke-layanan; tidak diperlukan login pengguna.
JSON Web Token (JWT) JSON Web Token digunakan untuk mengodekan token yang dikirim ke dan dari bot. Klien harus sepenuhnya memverifikasi semua token JWT yang mereka terima, sesuai dengan persyaratan yang diuraikan dalam artikel ini.
Metadata OpenID Layanan Bot Koneksi or menerbitkan daftar token valid yang digunakannya untuk menandatangani token JWT sendiri ke metadata OpenID di titik akhir statis yang terkenal.

Artikel ini menjelaskan cara menggunakan teknologi ini melalui HTTPS dan JSON standar. Tidak ada SDK khusus yang diperlukan, meskipun Anda mungkin menemukan bahwa pembantu untuk OpenID dan lainnya berguna.

Mengautentikasi permintaan dari bot Anda ke layanan Bot Koneksi or

Untuk berkomunikasi dengan layanan Bot Koneksi or, Anda harus menentukan token akses di Authorization header setiap permintaan API, menggunakan format ini:

Authorization: Bearer ACCESS_TOKEN

Untuk mendapatkan dan menggunakan token JWT untuk bot Anda:

  1. Bot Anda mengirimkan permintaan HTTP GET ke Layanan Masuk MSA.
  2. Respons dari layanan berisi token JWT yang akan digunakan.
  3. Bot Anda menyertakan token JWT ini di header otorisasi dalam permintaan ke layanan Bot Koneksi or.

Langkah 1: Meminta token akses dari layanan login akun ID Microsoft Entra

Penting

Jika Anda belum melakukannya, Anda harus mendaftarkan bot Anda dengan Bot Framework untuk mendapatkan AppID dan kata sandinya. Anda memerlukan ID Aplikasi dan kata sandi bot untuk meminta token akses.

Identitas bot Anda dapat dikelola di Azure dengan beberapa cara berbeda.

  • Sebagai identitas terkelola yang ditetapkan pengguna, sehingga Anda tidak perlu mengelola kredensial bot sendiri.
  • Sebagai aplikasi penyewa tunggal.
  • Sebagai aplikasi multi-penyewa.

Minta token akses berdasarkan jenis aplikasi bot Anda.

Untuk meminta token akses dari layanan masuk, terbitkan permintaan berikut, ganti MICROSOFT-APP-ID dan MICROSOFT-APP-PASSWORD dengan AppID dan kata sandi bot yang Anda peroleh saat mendaftarkan bot Anda dengan Bot Service.

POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

Langkah 2: Dapatkan token JWT dari respons layanan masuk akun ID Microsoft Entra

Jika aplikasi Anda diotorisasi oleh layanan login, isi respons JSON akan menentukan token akses Anda, jenisnya, dan kedaluwarsanya (dalam detik).

Saat menambahkan token ke Authorization header permintaan, Anda harus menggunakan nilai persis yang ditentukan dalam respons ini—jangan lolos atau mengodekan nilai token. Token akses berlaku hingga kedaluwarsa. Untuk mencegah kedaluwarsa token memengaruhi performa bot, Anda dapat memilih untuk melakukan cache dan secara proaktif menyegarkan token.

Contoh ini menunjukkan respons dari layanan masuk akun ID Microsoft Entra:

HTTP/1.1 200 OK
... (other headers)

{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

Langkah 3: Tentukan token JWT di header Otorisasi permintaan

Saat Anda mengirim permintaan API ke layanan Bot Koneksi or, tentukan token akses di Authorization header permintaan menggunakan format ini:

Authorization: Bearer ACCESS_TOKEN

Semua permintaan yang Anda kirim ke layanan Bot Koneksi or harus menyertakan token akses di Authorization header. Jika token dibentuk dengan benar, tidak kedaluwarsa, dan dihasilkan oleh layanan login akun ID Microsoft Entra, layanan Bot Koneksi or akan mengotorisasi permintaan. Pemeriksaan tambahan dilakukan untuk memastikan bahwa token milik bot yang mengirim permintaan.

Contoh berikut menunjukkan cara menentukan token akses di Authorization header permintaan.

POST https://smba.trafficmanager.net/teams/v3/conversations/12345/activities
Authorization: Bearer eyJhbGciOiJIUzI1Ni...

(JSON-serialized Activity message goes here)

Penting

Hanya tentukan token JWT di Authorization header permintaan yang Anda kirim ke layanan Bot Koneksi or. JANGAN kirim token melalui saluran yang tidak aman dan JANGAN sertakan dalam permintaan HTTP yang Anda kirim ke layanan lain. Token JWT yang Anda peroleh dari layanan login akun ID Microsoft Entra seperti kata sandi dan harus ditangani dengan sangat hati-hati. Siapa pun yang memiliki token dapat menggunakannya untuk melakukan operasi atas nama bot Anda.

Bot ke Koneksi or: contoh komponen JWT

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "https://api.botframework.com",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  appid: "<YOUR MICROSOFT APP ID>",
  ... other fields follow
}

Catatan

Bidang aktual dapat bervariasi dalam praktiknya. Buat dan validasi semua token JWT seperti yang ditentukan di atas.

Mengautentikasi permintaan dari layanan Bot Koneksi or ke bot Anda

Ketika layanan Bot Koneksi or mengirim permintaan ke bot Anda, layanan tersebut menentukan token JWT yang ditandatangani di Authorization header permintaan. Bot Anda dapat mengautentikasi panggilan dari layanan Bot Koneksi or dengan memverifikasi keaslian token JWT yang ditandatangani.

Untuk mengautentikasi panggilan dari layanan Bot Koneksi or:

  1. Bot Anda mendapatkan token JWT dari header otorisasi dalam permintaan yang dikirim dari layanan Bot Koneksi or.
  2. Bot Anda mendapatkan dokumen metadata OpenID untuk layanan Bot Koneksi or.
  3. Bot Anda mendapatkan daftar kunci penandatanganan yang valid dari dokumen.
  4. Bot Anda memverifikasi keaslian token JWT.

Langkah 2: Dapatkan dokumen metadata OpenID

Dokumen metadata OpenID menentukan lokasi dokumen kedua yang mencantumkan kunci penandatanganan layanan Bot Koneksi or yang valid. Untuk mendapatkan dokumen metadata OpenID, terbitkan permintaan ini melalui HTTPS:

GET https://login.botframework.com/v1/.well-known/openidconfiguration

Tip

Ini adalah URL statis yang dapat Anda hardcode ke dalam aplikasi Anda.

Contoh berikut menunjukkan dokumen metadata OpenID yang dikembalikan sebagai respons terhadap GET permintaan. Properti jwks_uri menentukan lokasi dokumen yang berisi kunci penandatanganan layanan Bot Koneksi or yang valid.

{
    "issuer": "https://api.botframework.com",
    "authorization_endpoint": "https://invalid.botframework.com",
    "jwks_uri": "https://login.botframework.com/v1/.well-known/keys",
    "id_token_signing_alg_values_supported": [
      "RS256"
    ],
    "token_endpoint_auth_methods_supported": [
      "private_key_jwt"
    ]
}

Langkah 3: Dapatkan daftar kunci penandatanganan yang valid

Untuk mendapatkan daftar kunci penandatanganan yang valid, terbitkan GET permintaan melalui HTTPS ke URL yang ditentukan oleh jwks_uri properti dalam dokumen metadata OpenID. Misalnya:

GET https://login.botframework.com/v1/.well-known/keys

Isi respons menentukan dokumen dalam format JWK tetapi juga menyertakan properti tambahan untuk setiap kunci: endorsements.

Tip

Daftar kunci stabil dan dapat di-cache, tetapi kunci baru dapat ditambahkan kapan saja. Untuk memastikan bot Anda memiliki salinan dokumen terbaru sebelum kunci ini digunakan, semua instans bot harus me-refresh cache lokal dokumen setidaknya sekali setiap 24 jam.

Properti endorsements dalam setiap kunci berisi satu atau beberapa string dukungan yang dapat Anda gunakan untuk memverifikasi bahwa ID saluran yang ditentukan dalam properti dalam channelIdobjek Aktivitas permintaan masuk autentik. Daftar ID saluran yang memerlukan dukungan dapat dikonfigurasi dalam setiap bot. Secara default, ini akan menjadi daftar semua ID saluran yang diterbitkan, meskipun pengembang bot dapat mengambil alih nilai ID saluran yang dipilih dengan cara apa pun.

Langkah 4: Verifikasi token JWT

Untuk memverifikasi keaslian token yang dikirim oleh layanan Bot Koneksi or, Anda harus mengekstrak token dari Authorization header permintaan, mengurai token, memverifikasi kontennya, dan memverifikasi tanda tangannya.

Pustaka penguraian JWT tersedia untuk banyak platform dan paling menerapkan penguraian yang aman dan andal untuk token JWT, meskipun Anda biasanya harus mengonfigurasi pustaka ini untuk mengharuskan karakteristik tertentu dari token (penerbitnya, audiens, dan sebagainya) berisi nilai yang benar. Saat mengurai token, Anda harus mengonfigurasi pustaka penguraian atau menulis validasi Anda sendiri untuk memastikan token memenuhi persyaratan ini:

  1. Token dikirim di header HTTP Authorization dengan skema "Pembawa".
  2. Token adalah JSON valid yang sesuai dengan standar JWT.
  3. Token berisi klaim "penerbit" dengan nilai https://api.botframework.com.
  4. Token berisi klaim "audiens" dengan nilai yang sama dengan ID Aplikasi Microsoft bot.
  5. Token berada dalam periode validitasnya. Ke condong jam standar industri adalah 5 menit.
  6. Token memiliki tanda tangan kriptografi yang valid, dengan kunci yang tercantum dalam dokumen kunci OpenID yang diambil di Langkah 3, menggunakan algoritma penandatanganan yang ditentukan dalam id_token_signing_alg_values_supported properti dokumen Open ID Metadata yang diambil di Langkah 2.
  7. Token berisi klaim "serviceUrl" dengan nilai yang cocok serviceUrl dengan properti di akar objek Aktivitas permintaan masuk.

Jika dukungan untuk ID saluran diperlukan:

  • Anda harus mengharuskan objek apa pun Activity yang dikirim ke bot Anda dengan ID saluran tersebut disertai dengan token JWT yang ditandatangani dengan dukungan untuk saluran tersebut.
  • Jika dukungan tidak ada, bot Anda harus menolak permintaan dengan mengembalikan kode status HTTP 403 (Terlarang).

Penting

Semua persyaratan ini penting, terutama persyaratan 4 dan 6. Kegagalan untuk menerapkan SEMUA persyaratan verifikasi ini akan membuat bot terbuka terhadap serangan yang dapat menyebabkan bot meluaskan token JWT-nya.

Pelaksana tidak boleh mengekspos cara untuk menonaktifkan validasi token JWT yang dikirim ke bot.

Koneksi or ke Bot: contoh komponen JWT

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOU MICROSOFT APP ID>",
  iss: "https://api.botframework.com",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

Catatan

Bidang aktual dapat bervariasi dalam praktiknya. Buat dan validasi semua token JWT seperti yang ditentukan di atas.

Mengautentikasi permintaan dari Emulator Kerangka Kerja Bot ke bot Anda

Bot Framework Emulator adalah alat desktop yang dapat Anda gunakan untuk menguji fungsionalitas bot Anda. Meskipun Bot Framework Emulator menggunakan teknologi autentikasi yang sama seperti yang dijelaskan di atas, Bot Framework Emulator tidak dapat meniru layanan Bot Koneksi or yang sebenarnya. Sebagai gantinya, ia menggunakan ID Aplikasi Microsoft dan Kata Sandi Aplikasi Microsoft yang Anda tentukan saat menghubungkan Emulator ke bot Anda untuk membuat token yang identik dengan yang dibuat bot. Saat Emulator mengirim permintaan ke bot Anda, Emulator menentukan token JWT di Authorization header permintaan—pada dasarnya, menggunakan kredensial bot sendiri untuk mengautentikasi permintaan.

Jika Anda menerapkan pustaka autentikasi dan ingin menerima permintaan dari Bot Framework Emulator, Anda harus menambahkan jalur verifikasi tambahan ini. Jalur ini secara struktural mirip dengan jalur verifikasi Koneksi or -> Bot, tetapi menggunakan dokumen OpenID MSA alih-alih dokumen OpenID Bot Koneksi or.

Untuk mengautentikasi panggilan dari Emulator Kerangka Kerja Bot:

  1. Bot Anda mendapatkan token JWT dari header otorisasi dalam permintaan yang dikirim dari Emulator Kerangka Kerja Bot.
  2. Bot Anda mendapatkan dokumen metadata OpenID untuk layanan Bot Koneksi or.
  3. Bot Anda mendapatkan daftar kunci penandatanganan yang valid dari dokumen.
  4. Bot Anda memverifikasi keaslian token JWT.

Langkah 2: Dapatkan dokumen metadata MSA OpenID

Dokumen metadata OpenID menentukan lokasi dokumen kedua yang mencantumkan kunci penandatanganan yang valid. Untuk mendapatkan dokumen metadata MSA OpenID, terbitkan permintaan ini melalui HTTPS:

GET https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Contoh berikut menunjukkan dokumen metadata OpenID yang dikembalikan sebagai respons terhadap GET permintaan. Properti jwks_uri menentukan lokasi dokumen yang berisi kunci penandatanganan yang valid.

{
    "authorization_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
    "token_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/token",
    "token_endpoint_auth_methods_supported":["client_secret_post","private_key_jwt"],
    "jwks_uri":"https://login.microsoftonline.com/common/discovery/v2.0/keys",
    ...
}

Langkah 3: Dapatkan daftar kunci penandatanganan yang valid

Untuk mendapatkan daftar kunci penandatanganan yang valid, terbitkan GET permintaan melalui HTTPS ke URL yang ditentukan oleh jwks_uri properti dalam dokumen metadata OpenID. Misalnya:

GET https://login.microsoftonline.com/common/discovery/v2.0/keys
Host: login.microsoftonline.com

Isi respons menentukan dokumen dalam format JWK.

Langkah 4: Verifikasi token JWT

Untuk memverifikasi keaslian token yang dikirim oleh Emulator, Anda harus mengekstrak token dari Authorization header permintaan, mengurai token, memverifikasi kontennya, dan memverifikasi tanda tangannya.

Pustaka penguraian JWT tersedia untuk banyak platform dan paling menerapkan penguraian yang aman dan andal untuk token JWT, meskipun Anda biasanya harus mengonfigurasi pustaka ini untuk mengharuskan karakteristik tertentu dari token (penerbitnya, audiens, dan sebagainya) berisi nilai yang benar. Saat mengurai token, Anda harus mengonfigurasi pustaka penguraian atau menulis validasi Anda sendiri untuk memastikan token memenuhi persyaratan ini:

  1. Token dikirim di header HTTP Authorization dengan skema "Pembawa".
  2. Token adalah JSON valid yang sesuai dengan standar JWT.
  3. Token berisi klaim "penerbit" dengan salah satu nilai yang disorot untuk kasus non-pemerintah. Memeriksa kedua nilai pengeluar sertifikat akan memastikan Anda memeriksa nilai pengeluar sertifikat protokol keamanan v3.1 dan v3.2.
  4. Token berisi klaim "audiens" dengan nilai yang sama dengan ID Aplikasi Microsoft bot.
  5. Emulator, tergantung pada versinya, mengirim AppId melalui klaim appid (versi 1) atau klaim pihak yang berwenang (versi 2).
  6. Token berada dalam periode validitasnya. Ke condong jam standar industri adalah 5 menit.
  7. Token memiliki tanda tangan kriptografi yang valid dengan kunci yang tercantum dalam dokumen kunci OpenID yang diambil di Langkah 3.

Catatan

Persyaratan 5 adalah khusus untuk jalur verifikasi Emulator.

Jika token tidak memenuhi semua persyaratan ini, bot Anda harus mengakhiri permintaan dengan mengembalikan kode status HTTP 403 (Terlarang).

Penting

Semua persyaratan ini penting, terutama persyaratan 4 dan 7. Kegagalan untuk menerapkan SEMUA persyaratan verifikasi ini akan membuat bot terbuka terhadap serangan yang dapat menyebabkan bot meluaskan token JWT-nya.

Emulator ke Bot: contoh komponen JWT

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOUR MICROSOFT APP ID>",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

Catatan

Bidang aktual dapat bervariasi dalam praktiknya. Buat dan validasi semua token JWT seperti yang ditentukan di atas.

Perubahan protokol keamanan

Bot ke autentikasi Koneksi or

URL masuk OAuth

Versi protokol Nilai yang valid
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Cakupan OAuth

Versi protokol Nilai yang valid
v3.1 & v3.2 https://api.botframework.com/.default

Koneksi atau ke autentikasi Bot

Dokumen metadata OpenID

Versi protokol Nilai yang valid
v3.1 & v3.2 https://login.botframework.com/v1/.well-known/openidconfiguration

Penerbit JWT

Versi protokol Nilai yang valid
v3.1 & v3.2 https://api.botframework.com

Autentikasi Emulator ke Bot

URL masuk OAuth

Versi protokol Nilai yang valid
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Cakupan OAuth

Versi protokol Nilai yang valid
v3.1 & v3.2 ID Aplikasi Microsoft bot Anda + /.default

AudiensI JWT

Versi protokol Nilai yang valid
v3.1 & v3.2 ID Aplikasi Microsoft bot Anda

Penerbit JWT

Versi protokol Nilai yang valid
v3.1 1.0 https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/
v3.1 2.0 https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0
v3.2 1.0 https://sts.windows.net/f8cdef31-a31e-4b4a-93e4-5f571e91255a/
v3.2 2.0 https://login.microsoftonline.com/f8cdef31-a31e-4b4a-93e4-5f571e91255a/v2.0

Lihat juga nilai yang disorot untuk kasus non-pemerintah.

Dokumen metadata OpenID

Versi protokol Nilai yang valid
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Sumber daya tambahan