Menambahkan akses menyeluruh ke bot
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.
Di panel kanan, pilih Tambahkan izin.
Pilih Microsoft API lalu Microsoft Graph.
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
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:
profile
User.ReadBasic.All
User.Read
openid
.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
Perintahlogin
memungkinkan pengguna untuk masuk ke pendaftaran ID Microsoft Entra menggunakanRootBot
. Setelah masuk, SSO mengurus masuk jugaSkillBot
. Pengguna tidak perlu masuk lagi.token
menampilkan token pengguna.logout
mencatat pengguna dariRootBot
.
SkillBot
Perintahskill login
RootBot
memungkinkan untuk masuk keSkillBot
, atas nama pengguna. Pengguna tidak menampilkan kartu masuk, jika sudah masuk, kecuali SSO gagal.skill token
menampilkan token pengguna dariSkillBot
.skill logout
mencatat pengguna dariSkillBot
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.
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 dalam
RootBot
file proyekappsettings.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
danSkillBot
berjalan pada komputer lokal. Emulator berkomunikasi denganRootBot
pada port 3978 danRootBot
berkomunikasi denganSkillBot
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 menggunakanRootBot
, 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 dariSimpleRootBoot
.
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.
- 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;
}