Bagikan melalui

Menambahkan autentikasi ke bot

BERLAKU UNTUK: SDK v4

Azure AI Bot Service v4 SDK memfasilitasi pengembangan bot yang dapat mengakses sumber daya online yang memerlukan autentikasi pengguna. Bot Anda tidak perlu mengelola token autentikasi karena Azure melakukannya untuk Anda menggunakan OAuth 2.0 untuk menghasilkan token berdasarkan info masuk setiap pengguna. Bot Anda menggunakan token yang dihasilkan oleh Azure untuk mengakses sumber daya tersebut. Dengan cara ini, pengguna tidak perlu memberikan ID dan kata sandi ke bot untuk mengakses sumber daya yang aman, melainkan hanya kepada penyedia identitas tepercaya.

Untuk gambaran umum tentang bagaimana Kerangka Kerja Bot menangani autentikasi semacam ini, lihat Autentikasi pengguna.

Artikel ini mereferensikan dua sampel. Satu menunjukkan cara mendapatkan token autentikasi. Yang lain lebih kompleks dan menunjukkan cara mengakses Microsoft Graph atas nama pengguna. Dalam kedua kasus, Anda dapat menggunakan Azure AD v1 atau v2 sebagai penyedia identitas untuk mendapatkan token OAuth untuk bot. Artikel ini mencakup cara:

  • Membuat sumber daya Azure Bot
  • Membuat penyedia identitas Microsoft Entra ID
  • Mendaftarkan penyedia identitas Microsoft Entra ID dengan bot
  • Menyiapkan kode bot

Setelah menyelesaikan artikel ini, Anda akan memiliki bot yang dapat merespons beberapa tugas sederhana. Dalam contoh Microsoft Graph, Anda dapat mengirim email, menampilkan siapa Anda, dan memeriksa email terbaru. Anda tidak perlu menerbitkan bot untuk menguji fitur OAuth; namun, bot akan memerlukan ID dan kata sandi aplikasi Azure yang valid.

Catatan

Untuk membangun agen dengan layanan, orkestrasi, dan pengetahuan AI pilihan Anda, pertimbangkan untuk menggunakan SDK Agen Microsoft 365. Agen SDK memiliki dukungan untuk C#, JavaScript, atau Python. Anda dapat mempelajari lebih lanjut tentang Agen SDK di aka.ms/agents. Jika Anda mencari platform agen berbasis SaaS, pertimbangkan Microsoft Copilot Studio. Jika Anda memiliki bot yang sudah ada yang dibangun dengan Bot Framework SDK, Anda dapat memperbarui bot Anda ke SDK Agen. Anda dapat meninjau perubahan inti dan pembaruan utama pada Panduan migrasi Bot Framework SDK ke Agen SDK. Tiket dukungan untuk Bot Framework SDK tidak akan lagi dilayankan per 31 Desember 2025.

Pertimbangan Web Chat dan Direct Line

Penting

Anda perlu menggunakan Direct Line dengan autentikasi yang ditingkatkan yang diaktifkan untuk mengurangi risiko keamanan saat menyambungkan ke bot menggunakan kontrol Web Chat. Untuk informasi selengkapnya, lihat Autentikasi yang disempurnakan Direct Line.

Prasyarat

  • Pengetahuan tentang dasar-dasar bot, mengelola status, pustaka dialog, dan cara menerapkan alur percakapan berurutan, dan cara menggunakan kembali dialog.

  • Pengetahuan tentang pengembangan Azure dan OAuth 2.0.

  • Visual Studio 2017 atau yang lebih baru untuk .NET.

  • Node.js untuk JavaScript.

  • Python versi 3.8 atau lebih baru dari Python.

  • Salah satu sampel yang tercantum di bawah ini.

    Sampel Versi BotBuilder Menunjukkan
    Autentikasi dalam C# atau JavaScript atau Java atau Python v4 Dukungan OAuthCard
    Autentikasi untuk Microsoft Graph di C# atau JavaScript atau Java atau Python v4 Dukungan Microsoft Graph API dengan OAuth 2.0
    Autentikasi untuk Microsoft Teams di C# atau JavaScript atau Java atau Python v4 Dukungan Microsoft Graph API dengan OAuth 2.0

    Untuk menjalankan sampel yang dirujuk dalam artikel ini, Anda memerlukan:

    • Aplikasi ID Microsoft Entra untuk mendaftarkan sumber daya bot di Azure. Aplikasi ini memungkinkan bot untuk mengakses sumber daya aman eksternal, seperti Microsoft Graph. Ini juga memungkinkan pengguna untuk berkomunikasi dengan bot melalui beberapa saluran seperti Web Chat.
    • Aplikasi ID Microsoft Entra terpisah untuk berfungsi sebagai penyedia identitas. Aplikasi ini menyediakan kredensial yang diperlukan untuk membuat koneksi OAuth antara bot dan sumber daya yang aman. Perhatikan bahwa artikel ini menggunakan Direktori Aktif sebagai Penyedia Identitas. Banyak penyedia lain juga didukung.

Penting

Setiap kali Anda mendaftarkan bot di Azure, bot akan diberi aplikasi ID Microsoft Entra. Namun, aplikasi ini mengamankan akses dari saluran ke bot. Anda memerlukan aplikasi ID Microsoft Entra tambahan untuk setiap sumber daya aman eksternal yang Anda inginkan untuk diakses bot atas nama pengguna.

Buat sumber daya

Buat sumber daya Azure Bot, yang akan memungkinkan Anda mendaftarkan bot Anda dengan Azure AI Bot Service.

Tips

Sumber daya Aplikasi Web Bot dan Pendaftaran Saluran Bot baru tidak dapat dibuat; namun, sumber daya yang sudah ada dan dikonfigurasi serta disebarkan akan terus berfungsi. Bot yang dibuat dari templat VSIX atau Yeoman dari SDK versi 4.14.1.2 atau yang lebih baru berisi templat ARM yang akan menghasilkan sumber daya Azure Bot.

  1. Buka portal Azure.

  2. Di panel kanan, pilih Buat sumber daya.

  3. Dalam kotak pencarian masukkan bot, lalu tekan Enter.

  4. Pilih kartu Azure Bot .

    Pilih sumber daya bot Azure

  5. Pilih Buat.

  6. Masukkan nilai di bidang yang diperlukan dan tinjau serta perbarui pengaturan.

    1. Berikan informasi di bawah Detail proyek. Pilih apakah bot Anda akan memiliki residensi data global atau lokal. Saat ini, fitur residensi data lokal tersedia untuk sumber daya di wilayah "westeurope" dan "centralindia". Untuk informasi selengkapnya, lihat Regionalisasi di Azure AI Bot Service.

      Pengaturan detail proyek untuk sumber daya Azure Bot

    2. Berikan informasi di bawah ID Aplikasi Microsoft. Pilih bagaimana identitas bot Anda akan dikelola di Azure dan apakah akan membuat identitas baru atau menggunakan identitas yang sudah ada.

      Pengaturan ID aplikasi Microsoft untuk sumber daya Azure Bot

  7. Pilih Tinjau + buat.

  8. Jika validasi lolos, pilih Buat.

  9. Setelah penyebaran selesai, pilih Pergi ke sumber daya. Anda akan melihat bot dan sumber daya terkait yang tercantum dalam grup sumber daya yang Anda pilih.

  10. Jika Anda belum memiliki Bot Framework SDK, pilih Unduh dari GitHub untuk mempelajari cara menggunakan paket untuk bahasa pilihan Anda.

    Membuat bot di SDK

Anda sekarang siap untuk membangun bot Anda dengan Bot Framework SDK.

Tips

Saat Azure membuat sumber daya Azure Bot penyewa tunggal atau multi-penyewa baru dengan ID aplikasi baru, Azure Bot juga menghasilkan kata sandi.

Informasi Identitas Bot

Ikuti langkah-langkah ini untuk menambahkan informasi identitas ke file konfigurasi bot Anda. File berbeda tergantung pada bahasa pemrograman yang digunakan untuk membuat bot.

Penting

  • Versi Java dari Bot Framework SDK hanya mendukung bot multi-tenant.
  • Versi C#, JavaScript, dan Python mendukung ketiga jenis aplikasi untuk mengelola identitas bot.
Bahasa Nama file Catatan
C# appsettings.json Mendukung ketiga jenis aplikasi untuk mengelola identitas bot Anda.
JavaScript .env Mendukung ketiga jenis aplikasi untuk mengelola identitas bot Anda.
Jawa application.properties Hanya mendukung bot multi-penyewaan.
Phyton config.py Mendukung ketiga jenis aplikasi untuk mengelola identitas bot Anda.

Informasi identitas yang perlu Anda tambahkan tergantung pada jenis aplikasi bot. Berikan nilai berikut dalam file konfigurasi Anda.

Tersedia untuk bot C#, JavaScript, dan Python.

Properti Nilai
MicrosoftAppType UserAssignedMSI
MicrosoftAppId ID klien identitas terkelola yang ditetapkan oleh pengguna.
MicrosoftAppPassword Tidak berlaku. Biarkan ini kosong untuk bot dengan identitas terkelola yang ditetapkan pengguna.
MicrosoftAppTenantId ID penyewa untuk identitas terkelola yang ditetapkan oleh pengguna.

Untuk memperbarui layanan aplikasi Anda

Jika Anda memiliki sumber daya App Service (aplikasi web) yang sudah ada untuk bot dan bot Anda adalah aplikasi identitas terkelola yang ditetapkan pengguna, Anda mungkin perlu memperbarui layanan aplikasi bot Anda:

  1. Buka halaman App Service untuk aplikasi web bot Anda.
  2. Di Pengaturan, pilih Identitas.
  3. Pada bilah Identitas, pilih tab Pengguna yang Ditugaskan dan Tambahkan (+).
  4. Pada jendela Tambahkan identitas terkelola yang ditetapkan pengguna:

    1. Pilih langganan Anda.

    2. Untuk Identitas terkelola yang ditetapkan pengguna, pilih identitas terkelola untuk bot Anda. Jika identitas terkelola dibuat secara otomatis untuk Anda, identitas tersebut akan memiliki nama yang sama dengan bot Anda.

    3. Pilih Tambahkan untuk menggunakan identitas ini untuk bot Anda.

      Panel Identitas App Service dengan identitas terkelola untuk bot yang dipilih.

Untuk memperoleh ID aplikasi atau penyewa Anda

Untuk mendapatkan ID aplikasi bot atau ID penyewa/tenant Anda:

  1. Buka bilah sumber daya Azure Bot untuk bot Anda.
  2. Buka bilah Konfigurasi bot. Dari bilah ini, Anda dapat menyalin ID Aplikasi Microsoft atau ID Penyewa Aplikasi bot.

Untuk menghasilkan kata sandi baru

Bot penyewa tunggal dan multi-penyewa memiliki rahasia aplikasi atau kata sandi yang Anda perlukan untuk berbagai operasi. Azure AI Bot Service menyembunyikan rahasia bot Anda. Namun, pemilik sumber daya App Service bot dapat menghasilkan kata sandi baru:

  1. Buka bilah sumber daya Azure Bot untuk bot Anda.
  2. Buka bilah Konfigurasi bot.
  3. Pilih Kelola, di samping ID Aplikasi Microsoft, untuk masuk ke bilah Sertifikat + rahasia untuk layanan aplikasi.
  4. Ikuti instruksi pada bilah untuk membuat rahasia klien baru dan mencatat nilai di tempat yang aman.

Layanan identitas ID Microsoft Entra

ID Microsoft Entra adalah layanan identitas cloud yang memungkinkan Anda membangun aplikasi yang memasukkan pengguna dengan aman menggunakan protokol standar industri seperti OAuth 2.0.

Anda dapat menggunakan salah satu dari dua layanan identitas ini:

  1. Platform pengembang MICROSOFT Entra ID (v1.0). Juga dikenal sebagai titik akhir Azure AD v1, yang memungkinkan Anda membangun aplikasi yang memungkinkan pengguna masuk dengan aman menggunakan akun kerja atau sekolah Microsoft. Untuk informasi selengkapnya, lihat gambaran umum ID Microsoft Entra untuk pengembang (v1.0).
  2. Platform Identitas Microsoft (v2.0). Juga dikenal sebagai endpoint Microsoft Entra ID, yang merupakan evolusi dari platform Azure AD (v1.0). Ini memungkinkan Anda untuk membangun aplikasi yang masuk ke semua penyedia identitas Microsoft dan mendapatkan token untuk memanggil API Microsoft, seperti Microsoft Graph, atau API lain yang telah dibangun pengembang. Untuk informasi selengkapnya, lihat gambaran umum platform identitas Microsoft (v2.0).

Untuk informasi tentang perbedaan antara titik akhir v1 dan v2, lihat Mengapa pembaruan ke platform identitas Microsoft (v2.0)?. Untuk informasi lengkapnya, lihat platform identitas Microsoft (sebelumnya ID Microsoft Entra untuk pengembang).

Membuat penyedia identitas Microsoft Entra ID

Bagian ini menunjukkan cara membuat IdP Microsoft Entra ID yang menggunakan OAuth 2.0 untuk mengautentikasi bot. Anda dapat menggunakan titik akhir Azure AD v1 atau Microsoft Entra ID.

Tips

Anda harus membuat dan mendaftarkan aplikasi ID Microsoft Entra di penyewa tempat Anda dapat menyetujui untuk mendelegasikan izin yang diminta oleh aplikasi.

  1. Buka panel Microsoft Entra ID di portal Azure. Jika Anda tidak berada di penyewa yang benar, pilih Alihkan direktori untuk beralih ke penyewa yang benar. (Untuk informasi tentang cara membuat penyewa, lihat Akses portal dan buat penyewa.)

  2. Buka panel Pendaftaran aplikasi.

  3. Di panel Pendaftaran aplikasi, pilih Pendaftaran baru.

  4. Isi bidang yang diperlukan dan buat pendaftaran aplikasi.

    1. Beri nama aplikasi.

    2. Pilih Jenis akun yang didukung untuk aplikasi Anda. (Salah satu opsi ini akan berfungsi dengan sampel ini.)

    3. Untuk URI Pengalihan, pilih Web dan atur URL ke salah satu URL pengalihan OAuth yang didukung.

    4. Pilih Daftarkan.

      • Setelah dibuat, Azure menampilkan halaman Gambaran Umum untuk aplikasi.
      • Catat nilai ID Aplikasi (klien). Anda akan menggunakan nilai ini nanti sebagai ID klien saat membuat string koneksi dan mendaftarkan penyedia ID Microsoft Entra dengan pendaftaran bot.
      • Catat nilai ID Direktori (tenant). Anda akan menggunakan nilai ini untuk mendaftarkan aplikasi penyedia ini dengan bot Anda.

  5. Di panel navigasi, pilih Sertifikat & rahasia untuk membuat rahasia untuk aplikasi Anda.

    1. Di bawah Rahasia klien, pilih Rahasia klien baru.
    2. Tambahkan deskripsi untuk mengidentifikasi rahasia ini dari rahasia-rahasia lain yang mungkin perlu Anda buat untuk aplikasi ini, seperti bot login.
    3. Untuk Kedaluwarsa, pilih periode waktu setelah mana informasi tersebut akan kedaluwarsa.
    4. Pilih Tambahkan.
    5. Sebelum meninggalkan Sertifikat & Rahasia, catat rahasia tersebut. Anda akan menggunakan nilai ini nanti sebagai rahasia klien saat mendaftarkan aplikasi ID Microsoft Entra dengan bot Anda.

  6. Di panel navigasi, pilih izin API untuk membuka panel izin API. Ini adalah praktik terbaik untuk secara eksplisit mengatur izin API untuk aplikasi.

    1. Pilih Tambahkan izin untuk menampilkan panel Minta izin API.

    2. Untuk sampel ini, pilih Microsoft API dan Microsoft Graph.

    3. Pilih Izin yang didelegasikan dan pastikan izin yang Anda butuhkan dipilih. Sampel ini memerlukan izin-izin ini.

      Catatan

      Setiap izin yang ditandai sebagai PERSETUJUAN ADMIN DIPERLUKAN akan mengharuskan pengguna dan admin penyewa untuk masuk. Oleh karena itu, bot Anda sebaiknya menghindari izin-izin ini.

      • openid
      • profil
      • Mail.Read
      • Surat.Kirim
      • User.Read
      • User.ReadBasic.All

    4. Pilih Tambahkan izin. (Pertama kali pengguna mengakses aplikasi ini melalui bot, mereka harus memberikan persetujuan.)

Anda sekarang memiliki aplikasi ID Microsoft Entra yang dikonfigurasi.

Catatan

Anda akan menetapkan ID Aplikasi (klien) dan rahasia Klien, saat membuat string koneksi dan mendaftarkan penyedia identitas dengan pendaftaran bot. Lihat bagian berikutnya.

Mendaftarkan penyedia identitas Microsoft Entra ID dengan bot

Langkah selanjutnya adalah mendaftarkan penyedia identitas Anda pada bot Anda.

  1. Buka halaman sumber daya Azure Bot bot Anda di portal Azure.

  2. Pilih pengaturan.

  3. Di bawah Pengaturan Koneksi OAuth di dekat bagian bawah halaman, pilih Tambahkan Pengaturan.

  4. Isi formulir sebagai berikut:

    1. Nama. Masukkan nama untuk koneksi Anda. Anda akan menggunakannya dalam kode bot Anda.

    2. Penyedia Layanan. Pilih ID Microsoft Entra untuk menampilkan bidang khusus ID Microsoft Entra.

    3. Id klien. Masukkan ID aplikasi (klien) yang Anda rekam untuk penyedia identitas ID Microsoft Entra Anda.

    4. Rahasia klien. Masukkan rahasia yang Anda catat untuk penyedia identitas Microsoft Entra ID Anda.

      Tips

      Jika Anda ingin menggunakan sertifikat, Anda dapat memilih AAD v2 dengan penyedia Sertifikat . Anda harus memberi Bot Service Token Store (appid: 00001111-aaaa-2222-bbbb-3333cccc4444) izin untuk mendapatkan sertifikat.

    5. Pertukaran Token URL. Biarkan kosong karena hanya digunakan untuk SSO di ID Microsoft Entra.

    6. ID Penyewa. Masukkan ID direktori (penyewa) yang Anda rekam sebelumnya untuk aplikasi ID Microsoft Entra atau umum bergantung pada jenis akun yang didukung yang dipilih saat Anda membuat aplikasi Azure DD. Untuk memutuskan nilai mana yang akan ditetapkan, ikuti kriteria berikut:

      • Saat membuat aplikasi ID Microsoft Entra, jika Anda memilih Akun hanya di direktori organisasi ini (hanya Microsoft - Penyewa tunggal), masukkan ID penyewa yang Anda rekam sebelumnya untuk aplikasi ID Microsoft Entra.
      • Namun, jika Anda memilih Akun di direktori organisasi apa pun (Direktori ID Microsoft Entra apa pun - Akun Microsoft multi penyewa dan pribadi misalnya Xbox, Outlook.com) atau Akun di direktori organisasi apa pun (direktori ID Microsoft Entra - Multi penyewa), masukkan common alih-alih ID penyewa. Jika tidak, aplikasi ID Microsoft Entra akan memverifikasi melalui penyewa yang ID-nya dipilih dan mengecualikan akun Microsoft pribadi.

      Ini akan menjadi entitas terkait dengan pengguna yang dapat diautentikasi. Untuk informasi selengkapnya, lihat Penyewaan di MICROSOFT Entra ID.

    7. Untuk Cakupan, masukkan nama izin yang Anda pilih dari registrasi aplikasi. Untuk tujuan pengujian, Anda cukup memasukkan: openid profile.

      Catatan

      Untuk Entra ID Microsoft, bidang Cakupan memerlukan daftar nilai yang peka huruf besar/kecil dan dipisahkan oleh spasi.

  5. Pilih Simpan.

Catatan

Nilai-nilai ini memungkinkan aplikasi Anda mengakses data Office 365 melalui Microsoft Graph API. Selain itu, URL Pertukaran Token harus dibiarkan kosong karena digunakan untuk SSO di ID Microsoft Entra saja.

Uji sambungan Anda

  1. Pilih pada entri koneksi untuk membuka koneksi yang Anda buat.
  2. Pilih Uji Koneksi di bagian atas panel Pengaturan Koneksi Penyedia Layanan.
  3. Pertama kali, ini harus membuka tab browser baru yang mencantumkan izin yang diminta aplikasi Anda dan meminta Anda untuk menerima.
  4. Pilih Terima.
  5. Ini kemudian akan mengalihkan Anda ke halaman Uji Koneksi ke <nama koneksi Anda Berhasil>.

Anda sekarang dapat menggunakan nama koneksi ini dalam kode bot Anda untuk mengambil token pengguna.

Menyiapkan kode bot

Anda akan memerlukan ID aplikasi dan kata sandi bot Anda untuk menyelesaikan proses ini.

  1. Klon dari repositori GitHub sampel yang ingin Anda gunakan: Autentikasi Bot atau Autentikasi Bot untuk Microsoft Graph.

  2. Perbarui appsettings.json:

    • Atur ConnectionName ke nama pengaturan koneksi OAuth yang Anda tambahkan ke bot Anda.

    • Atur MicrosoftAppId dan MicrosoftAppPassword ke ID aplikasi dan rahasia aplikasi bot Anda.

      Bergantung pada karakter dalam rahasia bot Anda, Anda mungkin perlu melakukan escape XML pada kata sandi. Misalnya, setiap ampersands (&) perlu dikodekan sebagai &amp;.

    {
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",
  "ConnectionName": ""
}

    Untuk menggunakan OAuth di bot dengan residensi data di cloud publik, Anda harus menambahkan konfigurasi berikut di appsetting Anda

    "OAuthUrl": "<Regional-OAuth-Uri>",
"ToChannelFromBotOAuthScope": "https://api.botframework.com",
"ToChannelFromBotLoginUrlTemplate": "https://api.botframework.com",
"PublicAzureChannel": "https://api.botframework.com",
"ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.com/v1/.well-known/openidconfiguration",
"ToBotFromEmulatorOpenIdMetadataUrl": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
"ToBotFromChannelTokenIssuer": "https://api.botframework.com",
"ToChannelFromBotLoginUrl": "https://login.microsoftonline.com/botframework.com",

    Di mana <Regional-OAuth-Url> adalah salah satu URI berikut:

    URI (Uniform Resource Identifier) Deskripsi
    https://europe.api.botframework.com Untuk bot cloud publik dengan penyimpanan data di Eropa.
    https://unitedstates.api.botframework.com Untuk bot cloud publik dengan lokasi data di Amerika Serikat.
    https://india.api.botframework.com Untuk bot cloud publik dengan penempatan data di India.

  3. Perbarui Startup.cs:

    Untuk menggunakan OAuth di cloud Azure non-publik, seperti cloud pemerintah, Anda harus menambahkan kode berikut dalam file Startup.cs .

    string uri = "<uri-to-use>";
MicrosoftAppCredentials.TrustServiceUrl(uri);
OAuthClientConfig.OAuthEndpoint = uri;

    Jika <uri yang digunakan> adalah salah satu URI berikut:

    URI (Uniform Resource Identifier) Deskripsi
    https://api.botframework.azure.us Untuk bot cloud pemerintah Amerika Serikat tanpa ketentuan residensi data.
    https://api.botframework.com Untuk bot dalam cloud publik tanpa residensi data. Ini adalah URI default dan tidak memerlukan perubahan pada Startup.cs.

Untuk mendapatkan nilai ID aplikasi Microsoft dan kata sandi aplikasi Microsoft, lihat Mendapatkan kata sandi pendaftaran.

Catatan

Sekarang Anda dapat menerbitkan kode bot ini ke langganan Azure Anda (pilih kanan pada proyek dan pilih Terbitkan), tetapi artikel ini tidak diperlukan. Anda perlu menyiapkan konfigurasi penerbitan yang menggunakan aplikasi dan paket hosting yang Anda gunakan saat mengkonifikasi bot di portal Azure.

Menguji bot menggunakan Emulator

Jika Anda belum melakukannya, instal Bot Framework Emulator. Lihat juga Debug dengan Emulator.

Agar sampel log masuk bot berfungsi, Anda harus mengonfigurasi Emulator seperti yang ditunjukkan di Mengonfigurasi Emulator untuk autentikasi.

Pengujian

Setelah mengonfigurasi mekanisme autentikasi, Anda dapat melakukan pengujian sampel bot yang sebenarnya.

Catatan

Anda mungkin diminta untuk memasukkan kode ajaib, karena cara pengimplementasian contoh bot. Kode ajaib ini adalah bagian dari RFC#7636 dan ada untuk menambahkan elemen keamanan tambahan. Dengan menghapus kode ajaib, ada peningkatan risiko keamanan. Ini dapat diredam dengan menggunakan Direct Line dengan autentikasi yang ditingkatkan telah diaktifkan. Untuk informasi selengkapnya, lihat Autentikasi Bot Framework yang Disempurnakan.

  1. Jalankan sampel bot secara lokal di komputer Anda.
  2. Mulai Emulator.
  3. Anda harus memberikan ID aplikasi dan kata sandi bot saat tersambung ke bot.
    • Anda mendapatkan ID aplikasi dan kata sandi dari pendaftaran aplikasi Azure. Ini adalah nilai yang sama dengan yang Anda tetapkan ke aplikasi bot di appsettings.json file atau .env . Di Emulator, Anda menetapkan nilai-nilai ini dalam file konfigurasi atau pertama kali Anda terhubung ke bot.
    • Jika Anda perlu XML-escape kata sandi dalam kode bot Anda, Anda juga perlu melakukannya di sini.
  4. Ketik help untuk melihat daftar perintah yang tersedia untuk bot, dan uji fitur autentikasi.
  5. Setelah masuk, Anda tidak perlu memberikan kredensial lagi hingga Anda keluar.
  6. Untuk keluar, dan batalkan autentikasi Anda, ketik logout.

Catatan

Autentikasi bot memerlukan penggunaan layanan Konektor Bot. Layanan mengakses informasi dari sumber daya Azure Bot Anda.

Contoh autentikasi

Dalam sampel autentikasi Bot, dialog dirancang untuk mengambil token pengguna setelah pengguna masuk.

Sampel percakapan dengan bot sampel autentikasi.

Contoh Autentikasi untuk Microsoft Graph

Dalam sampel Autentikasi Bot untuk Microsoft Graph, dialog dirancang untuk menerima serangkaian perintah terbatas setelah pengguna masuk.

Sampel percakapan dengan bot sampel autentikasi Microsoft Graph.

Informasi Tambahan

Ketika pengguna meminta bot untuk melakukan sesuatu yang mengharuskan bot untuk memasukkan pengguna, bot dapat menggunakan OAuthPrompt untuk memulai pengambilan token untuk koneksi tertentu. OAuthPrompt membuat alur pengambilan token yang terdiri dari:

  1. Memeriksa untuk melihat apakah Azure AI Bot Service sudah memiliki token untuk pengguna dan koneksi saat ini. Jika ada token, token akan dikembalikan.
  2. Jika Azure AI Bot Service tidak memiliki token cache, dibuat OAuthCard yang merupakan tombol masuk yang dapat dipilih pengguna.
  3. Setelah pengguna memilih OAuthCard tombol masuk, Azure AI Bot Service akan mengirim token pengguna secara langsung atau menyajikan kode autentikasi 6 digit kepada pengguna untuk dimasukkan di jendela obrolan.
  4. Jika pengguna disajikan dengan kode autentikasi, bot kemudian menukar kode autentikasi ini dengan token pengguna.

Bagian berikut menjelaskan bagaimana sampel mengimplementasikan beberapa tugas autentikasi umum.

Gunakan perintah OAuth untuk memasukkan pengguna dan mendapatkan token

Diagram arsitektur untuk sampel C#.

Dialog\MainDialog.cs

Tambahkan permintaan OAuth ke MainDialog di konstruktornya. Di sini, nilai untuk nama koneksi diambil dari file appsettings.json .

AddDialog(new OAuthPrompt(
    nameof(OAuthPrompt),
    new OAuthPromptSettings
    {
        ConnectionName = ConnectionName,
        Text = "Please Sign In",
        Title = "Sign In",
        Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
    }));

Dalam langkah dialog, gunakan BeginDialogAsync untuk memulai perintah OAuth, yang meminta pengguna untuk masuk.

  • Jika pengguna sudah masuk, ini akan menghasilkan peristiwa respons token, tanpa meminta pengguna.
  • Jika tidak, ini akan meminta pengguna untuk masuk. Azure AI Bot Service mengirimkan peristiwa respons token setelah pengguna mencoba masuk.
return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

Dalam langkah dialog berikut, periksa keberadaan token dalam hasil dari langkah sebelumnya. Jika tidak null, pengguna berhasil masuk.

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There is an example of this in the next method.
var tokenResponse = (TokenResponse)stepContext.Result;

Tunggu acara TokenResponse

Saat Anda memulai perintah OAuth, ia menunggu peristiwa respons token, dari mana ia akan mengambil token pengguna.

Bot\AuthBot.cs

menangani aktivitas peristiwa respons token. Di sini, kami melanjutkan dialog aktif yang memungkinkan prompt OAuth untuk memproses kejadian dan mengambil token.

protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

Keluarkan pengguna

Praktik terbaik adalah membiarkan pengguna keluar secara eksplisit, daripada mengandalkan koneksi habis waktu.

Dialog\LogoutDialog.cs

private async Task<DialogTurnResult> InterruptAsync(DialogContext innerDc, CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        if (text == "logout")
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(innerDc.Context.Activity.From.Id, ConnectionName, innerDc.Context.Activity.ChannelId, cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

Menambahkan Autentikasi Microsoft Teams

OAuth ditangani secara berbeda di Teams daripada di saluran lain. Sampel Bot Autentikasi Teams (dalam C#, JavaScript, Java, atau Python) menunjukkan cara menerapkan autentikasi dengan benar untuk Teams.

Bacaan lebih lanjut