Menambahkan akses menyeluruh ke bot

Artikel
10/27/2023

BERLAKU UNTUK: SDK v4

Artikel ini memperlihatkan cara menggunakan fitur akses menyeluruh (SSO) di bot. Untuk melakukannya, fitur ini menggunakan bot konsumen —juga dikenal sebagai bot akar atau induk —untuk berinteraksi dengan keterampilan atau bot turunan . Artikel ini menggunakan istilah bot root dan bot keterampilan.

Jika Anda menyertakan dukungan SSO, pengguna dapat masuk ke bot root menggunakan penyedia identitas dan tidak perlu masuk lagi saat kontrol diteruskan ke keterampilan.

Bot akar dan keterampilan adalah bot terpisah, berjalan di server yang berpotensi berbeda, masing-masing dengan memori dan status terpisahnya sendiri. Untuk informasi selengkapnya tentang keterampilan, lihat Gambaran umum keterampilan dan Menerapkan keterampilan. Untuk informasi selengkapnya tentang autentikasi pengguna, lihat Dasar-dasar autentikasi Bot Framework, Autentikasi pengguna, dan Menambahkan autentikasi ke bot.

Penting

Saat Anda menggunakan autentikasi Azure AI Bot Service dengan Web Chat, ada beberapa pertimbangan keamanan penting yang harus Anda ingat. Untuk informasi selengkapnya, lihat bagian pertimbangan keamanan di artikel autentikasi REST.

Prasyarat

Pengetahuan tentang dasar-dasar Bot, Mengelola status, dan Tentang akses menyeluruh.
Pengetahuan tentang pustaka dialog dan cara menerapkan alur percakapan berurutan dan menggunakan kembali dialog
Pengetahuan tentang pengembangan Azure dan OAuth 2.0.
Visual Studio 2019 atau yang lebih baru untuk .NET.
SSO dengan keterampilan konsumen dan keterampilan sederhana di C#.

Tentang sampel

Artikel ini mereferensikan dua bot: RootBot dan SkillBot. RootBot meneruskan aktivitas ke SkillBot. Mereka memodelkan skenario keterampilan khas ini:

Bot root memanggil satu atau beberapa bot keterampilan.
Bot akar dan keterampilan menerapkan autentikasi dasar yang dijelaskan dalam artikel Tambahkan autentikasi ke bot .
Pengguna masuk ke bot root.
Karena SSO dan sudah masuk ke bot root, mereka masuk ke bot keterampilan tanpa memerlukan interaksi pengguna lagi.

Untuk gambaran umum tentang cara Bot Framework menangani autentikasi, lihat Autentikasi pengguna. Untuk informasi latar belakang SSO, lihat Akses menyeluruh.

RootBot mendukung SSO. Ini berkomunikasi dengan SkillBot atas nama pengguna, tanpa pengguna diharuskan untuk mengautentikasi lagi ke dalam _SkillBot.

Untuk setiap proyek dalam sampel, Anda memerlukan hal berikut:

Aplikasi ID Microsoft Entra untuk mendaftarkan sumber daya bot di Azure.
Aplikasi IdP Microsoft Entra untuk autentikasi.

Catatan

Saat ini, hanya IdP Microsoft Entra yang didukung.

Membuat sumber daya Azure RootBot

Buat sumber daya bot Azure di portal Azure untuk RootBot. Ikuti langkah-langkah yang dijelaskan dalam Membuat sumber daya bot Azure.
Salin dan simpan ID aplikasi pendaftaran bot dan rahasia klien.

Membuat identitas ID Microsoft Entra untuk RootBot

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

Buat aplikasi identitas untuk RootBot yang menggunakan ID Microsoft Entra untuk mengautentikasi pengguna. Ikuti langkah-langkah yang dijelaskan dalam Membuat IdP Microsoft Entra ID.
Di panel kiri, pilih Manifes.
Atur accessTokenAcceptedVersion ke 2.
Pilih Simpan.
Di panel kiri, pilih Ekspos API.
Di panel kanan, pilih Tambahkan cakupan.
Di ujung kanan Tambahkan bagian cakupan , pilih Simpan dan lanjutkan.
Di jendela yang ditampilkan, di bawah Siapa dapat menyetujui?, pilih Admin dan pengguna.
Masukkan informasi yang diperlukan yang tersisa.
Pilih Tambahkan cakupan.
Salin dan simpan nilai cakupan.

Membuat pengaturan koneksi OAuth untuk RootBot

Buat koneksi ID Microsoft Entra di RootBot pendaftaran bot dan masukkan nilai seperti yang dijelaskan dalam ID Microsoft Entra dan nilai yang dijelaskan di bawah ini.
Biarkan URL Pertukaran Token kosong.
Dalam kotak Cakupan , masukkan nilai cakupan yang RootBot Anda simpan di langkah sebelumnya.

Catatan

Cakupan berisi URL yang awalnya masuk pengguna ke bot akar, sementara URL pertukaran token dibiarkan kosong.

Sebagai contoh, mari kita asumsikan bahwa appid bot root adalah rootAppId dan appid bot keterampilan adalah skillAppId. Cakupan bot akar akan terlihat seperti api://rootAppId/customScope, yang digunakan untuk masuk ke pengguna. Cakupan bot akar ini kemudian ditukar dengan api://skillAppId/customscope selama SSO.
Salin dan simpan nama koneksi.

Membuat sumber daya Azure SkillBot

Buat sumber daya bot Azure di portal Azure untuk SkillBot. Ikuti langkah-langkah yang dijelaskan dalam Membuat sumber daya bot Azure.
Salin dan simpan ID aplikasi pendaftaran bot dan rahasia klien.

Membuat identitas ID Microsoft Entra untuk SkillBot

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

Buat aplikasi identitas untuk SkillBot yang menggunakan ID Microsoft Entra untuk mengautentikasi bot. Ikuti langkah-langkah yang dijelaskan dalam Membuat IdP Microsoft Entra ID.
Di panel kiri, pilih Manifes.
Atur accessTokenAcceptedVersion ke 2.
Pilih Simpan.
Di panel kiri, pilih Ekspos API.
Di panel kanan, pilih Tambahkan cakupan.
Di bagian Paling kanan Tambahkan cakupan , pilih Simpan dan lanjutkan.
Di jendela yang ditampilkan, di bawah Siapa dapat menyetujui? pilih Admin dan pengguna.
Masukkan informasi yang diperlukan yang tersisa.
Pilih Tambahkan cakupan.
Salin dan simpan nilai cakupan.
Pilih Tambahkan aplikasi klien. Di bagian paling kanan, dalam kotak ID Klien, masukkan ID aplikasi identitas RootBot yang Anda simpan sebelumnya. Pastikan Anda menggunakan identitas RootBot dan bukan ID aplikasi pendaftaran.

Catatan

Untuk aplikasi klien, Azure AI Bot Service tidak mendukung sing-on tunggal dengan idP Microsoft Entra ID B2C.
Di bawah Cakupan resmi, centang kotak menurut nilai cakupan.
Pilih Tambahkan aplikasi.
Di panel navigasi di sebelah kiri, pilih Izin API. Ini adalah praktik terbaik untuk secara eksplisit mengatur izin API untuk aplikasi.
1. Di panel kanan, pilih Tambahkan izin.
2. Pilih Microsoft API lalu Microsoft Graph.
3. Pilih Izin yang didelegasikan dan pastikan izin yang Anda butuhkan dipilih. Sampel ini memerlukan izin yang tercantum di bawah ini.
  
  Catatan
  
  Setiap izin yang ditandai sebagai PERSETUJUAN ADMIN DIPERLUKAN akan mengharuskan pengguna dan admin penyewa untuk masuk.
  - Openid
  - Profil
  - User.Read
  - User.ReadBasic.All
4. Pilih Tambahkan izin.

Membuat pengaturan koneksi OAuth untuk SkillBot

Buat koneksi ID Microsoft Entra di SkillBot pendaftaran bot dan masukkan nilai seperti yang dijelaskan dalam ID Microsoft Entra dan nilai yang dijelaskan di bawah ini.
Dalam kotak URL Token Exchange, masukkan nilai cakupan yang SkillBot Anda simpan di langkah-langkah sebelumnya.
Dalam kotak Cakupan, masukkan nilai berikut yang dipisahkan oleh spasi kosong: profileUser.ReadBasic.AllUser.Readopenid.
Salin dan simpan ke file nama koneksi.

Menguji koneksi

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

Untuk informasi selengkapnya, lihat gambaran umum Microsoft Entra ID untuk pengembang (v1.0) dan 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).

Menyiapkan kode sampel

Anda harus memperbarui appsettings.json file di kedua sampel seperti yang dijelaskan di bawah ini.

Kloning SSO dengan sampel Konsumen dan Keterampilan Keterampilan Sederhana dari repositori GitHub.

SkillBot Buka file proyekappsettings.json. Tetapkan nilai berikut dari file yang disimpan:

{
    "MicrosoftAppId": "<SkillBot registration app ID>",
    "MicrosoftAppPassword": "<SkillBot registration password>",
    "ConnectionName": "<SkillBot connection name>",
    "AllowedCallers": [ "<RootBot registration app ID>" ]
}

RootBot Buka file proyekappsettings.json. Tetapkan nilai berikut dari file yang disimpan:

{
    "MicrosoftAppId": "<RootBot registration app ID>",
    "MicrosoftAppPassword": "<RootBot registration password>",
    "ConnectionName": "<RootBot connection name>",
    "SkillHostEndpoint": "http://localhost:3978/api/skills/",
    "BotFrameworkSkills": [
            {
            "Id": "SkillBot",
            "AppId": "<SkillBot registration app ID>",
            "SkillEndpoint": "http://localhost:39783/api/messages"
            }
        ]
}

Menguji sampel

Gunakan yang berikut ini untuk pengujian:

RootBot Perintah
- login memungkinkan pengguna untuk masuk ke pendaftaran ID Microsoft Entra menggunakan RootBot. Setelah masuk, SSO mengurus masuk juga SkillBot . Pengguna tidak perlu masuk lagi.
- token menampilkan token pengguna.
- logout mencatat pengguna dari RootBot.
SkillBot Perintah
- skill loginRootBot memungkinkan untuk masuk ke SkillBot, atas nama pengguna. Pengguna tidak menampilkan kartu masuk, jika sudah masuk, kecuali SSO gagal.
- skill token menampilkan token pengguna dari SkillBot.
- skill logout mencatat pengguna dari SkillBot

Catatan

Pertama kali pengguna mencoba SSO pada keterampilan, mereka mungkin disajikan dengan kartu OAuth untuk masuk. Ini karena mereka belum memberikan persetujuan untuk aplikasi ID Microsoft Entra keterampilan. Untuk menghindari hal ini, mereka dapat memberikan persetujuan admin untuk izin grafik apa pun yang diminta oleh aplikasi ID Microsoft Entra.

Emulator
Obrolan Web

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

Anda harus mengonfigurasi Emulator agar login sampel bot berfungsi. Gunakan langkah-langkah di bawah ini: seperti yang ditunjukkan dalam Mengonfigurasi Emulator untuk autentikasi.

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

Di Visual Studio, buka SSOWithSkills.sln solusi dan konfigurasikan untuk memulai penelusuran kesalahan dengan beberapa proses.
Mulai penelusuran kesalahan secara lokal di komputer Anda. Perhatikan bahwa dalamRootBot file proyek appsettings.json Anda memiliki pengaturan berikut:
```
"SkillHostEndpoint": "http://localhost:3978/api/skills/"
"SkillEndpoint": "http://localhost:39783/api/messages"
```
Catatan

Pengaturan ini menyiratkan bahwa, dengan keduanya RootBot dan SkillBot berjalan pada komputer lokal. Emulator berkomunikasi dengan RootBot pada port 3978 dan RootBot berkomunikasi dengan SkillBot di port 39783. Segera setelah Anda mulai men-debug, dua jendela browser default terbuka. Satu di port 3978 dan yang lain pada port 39783.
Mulai Emulator.
Saat Anda tersambung ke bot, masukkan ID aplikasi pendaftaran dan kata sandi Anda RootBot .
Ketik hi untuk memulai percakapan.
Masukkan login. RootBot akan menampilkan kartu autentikasi Masuk ke AAD.
Pilih Masuk. Dialog pop-up Konfirmasi URL Terbuka ditampilkan.
Pilih Konfirmasi. Anda akan masuk dan RootBot token ditampilkan.
Masukkan token untuk menampilkan token lagi.

Sekarang Anda siap untuk berkomunikasi dengan SkillBot. Setelah anda masuk menggunakan RootBot, Anda tidak perlu memberikan kredensial anda lagi sampai anda keluar. Ini menunjukkan bahwa SSO berfungsi.
Masukkan login keterampilan di kotak Emulator. Anda tidak akan diminta untuk masuk lagi. Sebagai gantinya, token SkillBot ditampilkan.
Masukkan token keterampilan untuk menampilkan token lagi.
Sekarang Anda dapat memasukkan logout keterampilan untuk keluar dari SkillBot. Kemudian masukkan keluar untuk keluar dari SimpleRootBoot.

Sebarkan bot akar dan bot keterampilan ke Azure. Untuk informasi selengkapnya, lihat Tutorial: Menyediakan bot di Azure dan Tutorial: Menerbitkan bot dasar.
Di editor kode Anda, misalnya Visual Studio, ganti alamat localhost dalam RootBot file proyek appsetting.js dengan Microsoft Entra IDdresses aktual seperti yang ditunjukkan di bawah ini.
```
"SkillHostEndpoint": "https://<your root bot deployed name>.azurewebsites.net/api/skills"
"SkillEndpoint": "https://<your skill bot deployed name>.azurewebsites.net/api/messages"
```
Di browser Anda, buka portal Microsoft Azure.
Buka pendaftaran bot root Anda. Di panel kiri, pilih Uji di Web Chat. Jendela dialog dengan bot akar Anda ditampilkan dengan pesan salam bot.
Mulai percakapan dengan bot dengan memasukkan hai misalnya. Bot akan menggemakan pesan Anda kembali.
Masukkan login. RootBot akan menampilkan kartu autentikasi Masuk ke AAD.
Pilih Masuk. Halaman web dengan kode validasi ditampilkan.
Untuk menyelesaikan masuk, salin kode dan masukkan di kotak input. Token RootBot ditampilkan.
Masukkan token untuk menampilkan token lagi.

Sekarang Anda siap untuk berkomunikasi dengan SkillBot. Setelah masuk RootBot, Anda tidak perlu memberikan kredensial lagi hingga Anda keluar. Ini menunjukkan bahwa SSO berfungsi.
Masukkan login keterampilan. Token SkillBot ditampilkan.
Masukkan token keterampilan untuk menampilkan token lagi. Ini memberi tahu Anda bahwa Anda berkomunikasi dengan SkillBot tanpa perlu masuk lagi. SSO sedang beraksi!
Sekarang Anda dapat memasukkan logout keterampilan untuk keluar dari SkillBot. Kemudian masukkan keluar untuk keluar dari SimpleRootBoot.

Informasi Tambahan

Diagram urutan waktu berikut berlaku untuk sampel yang digunakan dalam artikel dan menunjukkan interaksi antara berbagai komponen yang terlibat. ABS adalah singkatan dari Azure AI Bot Service.

Sequence diagram illustrating the skill token flow.

Pertama kali, pengguna memasukkan login perintah untuk RootBot.
RootBot mengirimkan OAuthCard yang meminta pengguna untuk masuk.
Pengguna memasukkan kredensial autentikasi yang dikirim ke ABS (Azure AI Bot Service).
ABS mengirim token autentikasi, yang dihasilkan berdasarkan kredensial pengguna, ke RootBot.
RootBot menampilkan token akar untuk dilihat pengguna.
Pengguna memasukkan skill login perintah untuk SkillBot.
SkillBot mengirimkan OAuthCard ke RootBot.
RootBot meminta token yang dapat ditukar dari ABS.
SSO mengirimkan token keterampilan SkillBotke RootBot.
RootBot menampilkan token keterampilan untuk dilihat pengguna. Perhatikan bahwa token keterampilan dihasilkan tanpa pengguna harus masuk ke SKillBot. Ini karena SSO.

Contoh berikut menunjukkan bagaimana pertukaran token terjadi. Kode ini berasal dari file TokenExchangeSkillHandler.cs .

private async Task<bool> InterceptOAuthCards(ClaimsIdentity claimsIdentity, Activity activity)
{
    var oauthCardAttachment = activity.Attachments?.FirstOrDefault(a => a?.ContentType == OAuthCard.ContentType);
    if (oauthCardAttachment != null)
    {
        var targetSkill = GetCallingSkill(claimsIdentity);
        if (targetSkill != null)
        {
            var oauthCard = ((JObject)oauthCardAttachment.Content).ToObject<OAuthCard>();

            if (!string.IsNullOrWhiteSpace(oauthCard?.TokenExchangeResource?.Uri))
            {
                using (var context = new TurnContext(_adapter, activity))
                {
                    context.TurnState.Add<IIdentity>("BotIdentity", claimsIdentity);

                    // AAD token exchange
                    try
                    {
                        var result = await _tokenExchangeProvider.ExchangeTokenAsync(
                            context,
                            _connectionName,
                            activity.Recipient.Id,
                            new TokenExchangeRequest() { Uri = oauthCard.TokenExchangeResource.Uri }).ConfigureAwait(false);

                        if (!string.IsNullOrEmpty(result?.Token))
                        {
                            // If token above is null, then SSO has failed and hence we return false.
                            // If not, send an invoke to the skill with the token. 
                            return await SendTokenExchangeInvokeToSkill(activity, oauthCard.TokenExchangeResource.Id, result.Token, oauthCard.ConnectionName, targetSkill, default).ConfigureAwait(false);
                        }
                    }
                    catch
                    {
                        // Show oauth card if token exchange fails.
                        return false;
                    }

                    return false;
                }
            }
        }
    }
    return false;
}

Bagikan melalui