Bagikan melalui

Menambahkan autentikasi ke bot

  • Artikel

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 tetapi hanya ke IdP 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 idP untuk mendapatkan token OAuth untuk bot. Artikel ini mencakup cara:

  • Membuat sumber daya Azure Bot
  • Membuat IdP Microsoft Entra
  • Mendaftarkan Id Id Microsoft Entra 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

Bot Framework JavaScript, C#, dan Python SDK akan terus didukung, namun, Java SDK dihentikan dengan dukungan jangka panjang akhir yang berakhir pada November 2023.

Bot yang ada yang dibangun dengan Java SDK akan terus berfungsi.

Untuk pembuatan bot baru, pertimbangkan untuk menggunakan Microsoft Copilot Studio dan baca tentang memilih solusi salinan yang tepat.

Untuk informasi selengkapnya, lihat Masa depan pembuatan bot.

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 3.8+ untuk 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 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.

Tip

Sumber daya Pendaftaran Bot Aplikasi Web dan Saluran Bot baru tidak dapat dibuat; namun, sumber daya apa pun yang ada yang dikonfigurasi dan 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 Microsoft 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 Buka 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.

Tip

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 Anda gunakan untuk membuat bot.

Penting

Versi Java dari Bot Framework SDK hanya mendukung bot multi-penyewa. 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.
Java application.properties Hanya mendukung bot multi-penyewa.
Python 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 pengguna.
MicrosoftAppPassword Tidak berlaku. Biarkan ini kosong untuk bot identitas terkelola yang ditetapkan pengguna.
MicrosoftAppTenantId ID penyewa identitas terkelola yang ditetapkan 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 bilah App Service untuk aplikasi web bot Anda.
  2. Di Pengaturan, pilih Identitas.
  3. Pada bilah Identitas , pilih tab Pengguna yang ditetapkan dan Tambahkan (+).
  4. Pada bilah 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.

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

Untuk mendapatkan ID aplikasi atau penyewa Anda

Untuk mendapatkan aplikasi bot atau ID penyewa 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 butuhkan untuk beberapa 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 masuk dengan aman pengguna dengan 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 titik akhir ID Microsoft Entra, yang merupakan evolusi platform Microsoft 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 IdP Microsoft Entra

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.

Tip

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 ID Microsoft Entra 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 (penyewa). 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 orang lain yang mungkin perlu Anda buat untuk aplikasi ini, seperti bot login.
    3. Untuk Kedaluwarsa, pilih durasi waktu setelah rahasia akan kedaluwarsa.
    4. Pilih Tambahkan.
    5. Sebelum meninggalkan Sertifikat & rahasia, rekam rahasianya. 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 ini.

      Catatan

      Setiap izin yang ditandai sebagai PERSETUJUAN ADMIN DIPERLUKAN akan mengharuskan pengguna dan admin penyewa untuk masuk, jadi untuk bot Anda cenderung menjauh dari ini.

      • openid
      • profil
      • Mail.Read
      • Mail.Send
      • 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 Id Id Microsoft Entra dengan bot

Langkah selanjutnya adalah mendaftarkan penyedia identitas Anda dengan 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 rekam untuk IdP Microsoft Entra Anda.

      Tip

      Jika Anda ingin menggunakan sertifikat, Anda dapat memilih AAD v2 dengan penyedia Sertifikat . Anda harus memberi Bot Service Token Store (appid: 5b404cf4-a79d-4cfe-b866-24bf8e1a4921) izin untuk mendapatkan sertifikat.

    5. URL Pertukaran Token. 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 penyewa yang 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 pendaftaran aplikasi. Untuk tujuan pengujian, Anda cukup memasukkan: openid profile.

      Catatan

      Untuk ID Microsoft Entra, bidang Cakupan mengambil daftar nilai yang peka huruf besar/kecil dan dipisahkan 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. Kloning dari repositori GitHub sampel yang ingin Anda kerjakan: 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 XML keluar dari 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 Deskripsi
    https://europe.api.botframework.com Untuk bot cloud publik dengan residensi data di Eropa.
    https://unitedstates.api.botframework.com Untuk bot cloud publik dengan residensi data di Amerika Serikat.
    https://india.api.botframework.com Untuk bot cloud publik dengan residensi 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 Deskripsi
    https://api.botframework.azure.us Untuk Amerika Serikat bot cloud pemerintah tanpa residensi data.
    https://api.botframework.com Untuk bot 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 sampel bot diimplementasikan. 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 dimitigasi menggunakan Direct Line dengan autentikasi yang ditingkatkan 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 TokenResponseEvent

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

Bot\AuthBot.cs

AuthBot berasal dari ActivityHandler dan secara eksplisit menangani aktivitas peristiwa respons token. Di sini, kami melanjutkan dialog aktif, yang memungkinkan permintaan OAuth untuk memproses peristiwa 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, alih-alih mengandalkan koneksi ke waktu habis.

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 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

  • Sumber daya tambahan Bot Framework mencakup tautan untuk dukungan tambahan.
  • Repositori Bot Framework SDK memiliki informasi lebih lanjut tentang repositori, sampel, alat, dan spesifikasi yang terkait dengan Bot Builder SDK.