Menambahkan autentikasi pengguna ke topik

Anda dapat mengaktifkan autentikasi pengguna secara langsung dalam percakapan agen. Anda dapat menetapkan properti dasar pengguna, seperti nama dan ID, ke variabel. Anda juga dapat meminta pengguna untuk masuk dalam node autentikasi ke topik, yang mengambil token pengguna, dan kemudian menggunakan token tersebut untuk mengambil informasi pengguna dari sistem back-end.

Catatan

Agen yang dibuat di dalam Copilot Studio dan di Microsoft Teams secara otomatis dikonfigurasi untuk autentikasi Microsoft Entra ID.

Anda juga dapat mengkonfigurasi akses terusan (SSO) sehingga pengguna Anda tidak perlu masuk secara manual. Pelajari selengkapnya di Mengonfigurasi akses terusan dengan Microsoft Entra ID.

Prasyarat

• Ikhtisar variabel
• Konfigurasikan autentikasi pengguna di Copilot Studio

Tambahkan autentikasi pengguna ke topik untuk memungkinkan pelanggan Anda masuk langsung dalam percakapan. Anda kemudian dapat mempersonalisasi percakapan dengan variabel pengguna dan mengakses sistem back-end atas nama pengguna.

Mengonfigurasi autentikasi manual dengan Microsoft Entra ID

Aplikasi web

Anda perlu mengonfigurasi autentikasi pengguna dengan Microsoft Entra ID sebelum dapat menggunakan autentikasi dalam topik Anda.

Ikuti petunjuk dalam Mengonfigurasi autentikasi pengguna dengan Microsoft Entra ID.

Tambahkan autentikasi pengguna dengan topik sistem masuk

Saat Anda membuat agen, Copilot Studio secara otomatis menambahkan topik sistem yang disebut masuk. Untuk menggunakannya, Anda harus mengatur autentikasi agen ke manual dan mengharuskan pengguna untuk masuk. Saat pelanggan memulai percakapan dengan agen, topik masuk akan memicu dan meminta pengguna untuk masuk. Anda dapat menyesuaikan topik masuk sesuai dengan agen Anda.

Penting

Kami menyarankan agar topik masuk hanya digunakan untuk menyediakan metode autentikasi yang disediakan oleh Copilot Studio. Itu tidak boleh dimodifikasi untuk memanggil tindakan atau alur lain, atau metode autentikasi lainnya.

1. Buka agen Anda dan Copilot Studio,pilih Pengaturan di bagian atas halaman, lalu pilih Keamanan.
2. Pilih autentikasi.
3. Pilih Autentikasi secara manual, lalu pilih Wajibkan pengguna untuk masuk.
4. Konfigurasikan semua bidang autentikasi manual, sesuai kebutuhan.
5. Pilih Simpan.

Tambahkan autentikasi pengguna dengan topik kustom

Topik masuk mengautentikasi pengguna di awal percakapan. Untuk mengizinkan pengguna masuk nanti, Anda dapat menambahkan node Autentikasi ke topik kustom apa pun.

Saat pelanggan memasukkan nama pengguna dan kata sandi mereka, mereka mungkin diminta untuk memasukkan kode validasi. Setelah masuk, mereka tidak diminta lagi, meskipun mereka mencapai node Autentikasi lain.

1. Pilih Pengaturan di bagian atas halaman, lalu pilih Keamanan.

2. Pilih ubin Autentikasi.

   Catatan

   Anda harus memilih Autentikasi secara manual untuk menambahkan autentikasi pengguna ke topik kustom.

3. Pilih Autentikasi secara manual, lalu hapus kotak centang Wajibkan pengguna untuk masuk.

4. Konfigurasikan semua bidang autentikasi manual, sesuai kebutuhan.

5. Pilih Simpan.

6. Pilih topik di bagian atas halaman.

7. Pilih Tambahkan node ( ) >Lanjutan>Autentikasi.

8. Uji topik Anda dengan pengguna yang dikonfigurasi dengan penyedia identitas Anda.

Tip

Penting bagi Anda untuk membuat jalur untuk masuk yang berhasil dan kegagalan masuk. Proses masuk mungkin gagal karena berbagai alasan, termasuk kesalahan dengan proses masuk penyedia identitas.

Paket Teams

Jika opsi autentikasi diatur ke autentikasi dengan Microsoft, Anda tidak perlu secara eksplisit menambahkan autentikasi ke topik Anda. Di konfigurasi ini, setiap pengguna di Microsoft Teams secara otomatis masuk melalui kredensial tim mereka dan mereka tidak perlu masuk secara eksplisit dengan kartu otentikasi. Jika pilihan autentikasi Anda diatur ke manual, maka Anda harus menambahkan node Autentikasi (bahkan untuk saluran Teams).

Catatan

Jika opsi autentikasi diatur ke Autentikasi dengan Microsoft, Anda tidak dapat secara eksplisit menambahkan autentikasi ke topik Anda.

Tambahkan otentikasi pengguna ke topik

Node Autentikasi meminta pengguna untuk masuk dengan kartu masuk. Setelah pengguna masuk, mereka tidak diminta lagi, meskipun mereka mencapai node Autentikasi lain.

Setelah pengguna memasukkan nama pengguna dan sandi di perintah (yang di-host oleh penyedia identitas), mereka mungkin diminta memasukkan kode validasi, tergantung pada saluran. Beberapa saluran, seperti Microsoft Teams, tidak memerlukan kode validasi dari pengguna.

Saat agen Anda telah mengonfigurasi SSO , pengguna tidak akan diminta untuk masuk.

Untuk menambahkan node Autentikasi ke topik Anda:

1. Buka halaman topik untuk agen yang akan diedit.

2. Buka topik yang ingin Anda tambahi templat autentikasi.

   Catatan

   Jika agen Anda terhubung ke Dynamics 365 Customer Service, node Autentikasi tidak boleh menjadi bagian dari jalur percakapan yang diikuti agen saat menyapa pengguna untuk pertama kali; jika tidak, kartu masuk akan ditampilkan dua kali. Sebagai gantinya, tambahkan node Autentikasi ke topik lain yang dipicu oleh respons pengguna.

3. Pilih Tambahkan node (+) untuk menambahkan node pesan. Masukkan apa yang harus dikatakan agen untuk menunjukkan bahwa pengalaman masuk akan terjadi.

4. Di bawah node pesan, pilih Tambahkan node (+), pilih Minta tindakan, lalu pilih autentikasi.

   

   Catatan

   Node otentikasi hanya tersedia dalam pemilih tindakan di akhir pohon dialog (sebagai node leaf). Anda tidak dapat menambahkannya di tengah dialog. Setelah ditambahkan, Anda dapat menambahkan node lain di bawahnya.

   Node baru ini otomatis muncul: node otentikasi induk, diikuti node untuk jalur keberhasilan maupun kegagalan.

Penggunaan User.AccessToken tanpa node otentikasi

Variabel User.IsLoggedIn dan variabel User.AccessToken tersedia meskipun Anda tidak menggunakan templat yang disediakan oleh entri menu panggilan tindakan. Jika Anda meneruskan variabel User.AccessToken tanpa terlebih dahulu meminta pengguna melewati node otentikasi, pengguna akan diminta untuk masuk pada langkah tersebut.

Melewatkan variabel User.AccessToken dapat berguna jika anda selalu mengharapkan pengguna untuk masuk, atau jika pengguna anda diarahkan dari topik yang berbeda. Gunakan templat yang diberikan oleh entri panggilan tindakan untuk menangani kasus saat pengguna gagal masuk.

Catatan

Jika pengguna keluar di tengah percakapan, mereka akan diminta untuk masuk lagi jika topik sampai ke node yang menggunakan variabel User.AccessToken.

Jalur sukses

Jalur keberhasilan terkait dengan User.IsLoggedIn = True dan mempertimbangkan kapan pengguna berhasil masuk.

Jika Anda memiliki logika yang menggunakan variabel User.AccessToken (misalnya, untuk menyambung ke sistem back-end dengan menggunakan alur untuk mendapatkan informasi pengguna), tempatkanlah di bawah jalur ini.

Jalur Kegagalan

Jalur kegagalan terkait dengan kondisi selain IsLoggedIn = True. Di sebagian besar kasus, jalur kegagalan terjadi karena pengguna gagal masuk, menggunakan sandi yang salah, atau membatalkan pengalaman masuk.

Tambahkan logika yang Anda inginkan untuk menangani kasus ini. Sebagai contoh, ada pilihan untuk mencoba kembali atau untuk melaporkan ke agen langsung. Sesuaikan tindakan Jalur Kegagalan untuk skenario dan penggunaan tertentu.

Menguji topik

Pastikan anda menguji topik dengan menggunakan pengguna nyata yang dikonfigurasi di penyedia identitas topik Anda. Pastikan jalur keberhasilan masuk dan kegagalan dijalankan. Dengan cara ini, tidak akan bisa mengantisipasi situasi jika pengguna Anda gagal masuk atau terjadi kesalahan pada pengalaman masuk penyedia identitas.

Variabel Otentikasi

Aplikasi web

Saat mengonfigurasi autentikasi pengguna untuk agen, Anda dapat menggunakan variabel autentikasi dalam topik Anda. Tabel berikut membandingkan ketersediaan variabel ini berdasarkan opsi autentikasi yang Anda pilih.

Variabel autentikasi	Tidak ada autentikasi	Autentikasikan dengan Microsoft	Autentikasikan secara manual
User.DisplayName	Tidak tersedia	Tersedia	Tersedia
User.FirstName	Tidak tersedia	Tersedia	Tersedia
User.LastName	Tidak tersedia	Tersedia	Tersedia
User.PrincipalName	Tidak tersedia	Tersedia	Tersedia
User.Email	Tidak tersedia	Tersedia	Tersedia
User.Id	Tidak tersedia	Tersedia	Tersedia
User.IsLoggedIn	Tidak tersedia	Tersedia	Tersedia
User.AccessToken	Tidak tersedia	Tidak tersedia	Tersedia
SignInReason	Tidak tersedia	Tersedia	Tersedia

User.DisplayName

Peringatan

Variabel ini mungkin tidak berisi nilai. Uji dengan pengguna dari penyedia identitas Anda untuk memastikan topik Anda berfungsi dengan benar.

Variabel User.DisplayName berisi nama tampilan yang tersimpan di penyedia identitas. Gunakan variabel ini untuk menyambut atau merujuk kepada pengguna tanpa mereka harus secara eksplisit memberikan namanya kepada agen, sehingga membuat percakapan lebih personal.

Copilot Studio Secara otomatis mengatur nilai User.DisplayName dari klaim name yang disediakan oleh penyedia identitas, selama cakupan profile ditentukan saat autentikasi manual dikonfigurasi. Pelajari selengkapnya di Mengonfigurasi autentikasi pengguna dengan Microsoft Entra ID.

User.Id

Peringatan

Variabel ini mungkin tidak berisi nilai. Uji dengan pengguna dari penyedia identitas Anda untuk memastikan topik Anda berfungsi dengan benar.

Variabel User.Id berisi ID pengguna yang tersimpan di penyedia identitas. Gunakan variabel ini dalam alur Power Automate untuk memanggil API yang mengambil UserID sebagai nilai.

Copilot Studio secara otomatis menetapkan nilai User.DisplayName dari klaim sub yang diberikan oleh penyedia identitas.

User.IsLoggedIn

User.IsLoggedIn adalah variabel Boolean yang menyimpan status masuk pengguna. Nilai true menunjukkan pengguna masuk. Anda dapat menggunakan variabel ini untuk membuat logika percabangan dalam topik Anda yang memeriksa proses masuk yang berhasil, atau untuk mengambil informasi pengguna hanya jika pengguna masuk.

User.AccessToken

Peringatan

Pastikan Anda hanya meneruskan variabel User.AccessToken ke sumber tepercaya. Ini berisi informasi otentikasi pengguna, yang jika dibobol dapat membahayakan pengguna.

Variabel User.AccessToken berisi token pengguna, diperoleh setelah pengguna masuk. Anda dapat melewati variabel ini untuk alur Power Automate sehingga mereka dapat terhubung ke API back-end dan mengambil informasi pengguna, atau untuk melakukan tindakan atas nama pengguna.

Jangan gunakan User.AccessToken dalam node pesan atau dalam alur yang tidak Anda percayai.

SignInReason

SignInReason adalah variabel tipe pilihan yang menunjukkan kapan pengguna harus masuk. Ini memiliki dua nilai yang memungkinkan:

• SignInRequired menunjukkan pengguna harus masuk di awal percakapan dengan menggunakan topik Sistem Masuk. Mengharuskan pengguna untuk masuk harus diaktifkan.

• Initializer menunjukkan bahwa ketika pengguna tidak masuk, dan mereka mencapai titik dalam percakapan yang menggunakan variabel autentikasi, mereka diminta untuk masuk.

Paket Teams

Jika Anda mengonfigurasikan agen Anda dengan autentikasi dengan Microsoft atau autentikasi manual, Anda akan memiliki seperangkat variabel autentikasi yang tersedia di topik Anda. Pelajari lebih lanjut dalam Mengonfigurasi autentikasi pengguna di Copilot Studio.

Tabel berikut membandingkan ketersediaan variabel otentikasi dengan pilihan konfigurasi otentikasi:

Variabel autentikasi	Tidak ada autentikasi	Autentikasikan dengan Microsoft	Panduan
User.DisplayName	Tidak tersedia	Tersedia	Tersedia
User.Id	Tidak tersedia	Tersedia	Tersedia
User.IsLoggedIn	Tidak tersedia	Tidak tersedia	Tersedia
User.AccessToken	Tidak tersedia	Tidak tersedia	Tersedia

Variabel UserDisplayName

Variabel User.DisplayName berisi nama tampilan pengguna yang tersimpan di penyedia identitas. Anda dapat menggunakan variabel ini untuk menyambut atau merujuk kepada pelanggan tanpa mereka harus secara eksplisit mengatakannya ke agen, membuatnya lebih personal.

Nilai bidang ini diperoleh dari klaim name Microsoft Entra ID. Untuk penyedia OAuth, nilai ini adalah nilai yang tersimpan dalam klaim name. Copilot Studio secara otomatis mengekstrak bidang ini ke dalam variabel, jadi pastikan bahwa Anda memiliki profile sebagai bagian dari konfigurasi cakupan autentikasi Anda.

Variabel UserID

Variabel User.Id berisi ID pengguna yang tersimpan di penyedia identitas. Alur Power Automate dapat menggunakan nilai ini untuk memanggil API yang mengambil UserID sebagai nilai. Nilai bidang ini diperoleh dari klaim sub Microsoft Entra ID. Untuk penyedia OAuth, nilai ini adalah nilai yang tersimpan dalam klaim sub. Copilot Studio secara otomatis mengekstrak bidang ini ke dalam variabel.

Peringatan

Variabel User.DisplayName dan User.Id mungkin tidak terisi, dan sebaliknya mungkin berupa string kosong tergantung pada konfigurasi pengguna di penyedia identitas. Uji dengan pengguna dari penyedia identifikasi Anda untuk memastikan topik Anda berfungsi dengan benar, meskipun variabel ini kosong.

Variabel IsLoggedIn

Variabel User.IsLoggedIn menunjukkan apakah pengguna masuk (baik sebagai hasil dari proses masuk atau sudah masuk, juga dikenal sebagai jalur sukses masuk) atau tidak masuk (yang akan mengakibatkan Jalur Kegagalan login).

User.IsLoggedIn adalah variabel Boolean yang berisi status masuk pengguna. Anda dapat menggunakan variabel ini untuk membuat logika cabang dalam topik yang memeriksa keberhasilan masuk (misalnya, di templat yang telah disediakan sebagai bagian dari penambahan node autentikasi), atau untuk mengambil informasi pengguna secara oportunistik hanya jika pengguna masuk.

Variabel User.AccessToken

Variabel User.AccessToken berisi token pengguna, diperoleh setelah pengguna masuk. Teruskan variabel ini ke alur Power Automate sehingga mereka dapat terhubung ke API back-end dan mengambil informasi pengguna, atau untuk melakukan tindakan atas nama pengguna.

Peringatan

Pastikan Anda hanya meneruskan variabel User.AccessToken ke sumber tepercaya. Ini berisi informasi otentikasi pengguna, yang jika dibobol dapat membahayakan pengguna.

Jangan gunakan User.AccessToken dalam node pesan atau pada alur yang tidak Anda percayai.

Menguji variabel otentikasi

Secara default, panel Uji bot menggunakan akun pengguna yang masuk saat ini untuk mengisi variabel User.DisplayName dan User.Id. Namun, saat menguji topik yang menggunakan otentikasi, Anda mungkin ingin menggunakan nilai lain untuk variabel ini (atau bahkan nilai kosong).

Contohnya, Anda mungkin ingin menguji cara kerja karakter khusus, atau apa yang terjadi jika variabel kosong.

Tabel berikut berisi daftar perintah untuk mengisi variabel ini. Perintah ini hanya berlaku untuk panel Uji bot; Anda tidak dapat menggunakannya di agen yang diterbitkan yang disebarkan ke saluran.

Masukkan perintah yang diinginkan ke panel Uji bot seperti biasa jika Anda biasa ngobrol dengan agen. Anda akan menerima pesan konfirmasi dari agen jika berhasil. Jika agen tidak menggunakan autentikasi, Anda akan menerima pesan kesalahan.

Jika Anda mengatur ulang panel Uji bot (atau membuat perubahan pada topik yang menyebabkan Uji bot diatur ulang secara otomatis), Anda harus mengirim perintah lagi.

Variabel	Perintah Nilai kustom	Perintah nilai kosong (kosong)
User.DisplayName	/debug set bot.UserDisplayName "Value"	/debug set bot.UserDisplayName ""
User.Id	Tidak tersedia	/debug set bot.UserID ""

Penting

Untuk alasan keamanan, Anda tidak dapat mengisi variabel User.Id dengan nilai kustom (selain nilai kosong atau lowong).