Mengonfigurasi akses menyeluruh dengan Microsoft Entra ID

Copilot Studio mendukung akses menyeluruh (SSO). SSO memungkinkan agen di situs web Anda untuk masuk ke pelanggan jika mereka sudah masuk ke halaman atau aplikasi tempat agen disebarkan.

Misalnya, agen dihosting di intranet perusahaan atau di aplikasi tempat pengguna sudah masuk.

Ada empat langkah utama untuk mengonfigurasi SSO untuk Copilot Studio:

1. Buat pendaftaran aplikasi di Microsoft Entra ID untuk kanvas kustom Anda.

2. Tentukan cakupan kustom untuk agen Anda.

3. Konfigurasikan autentikasi untuk Copilot Studio mengaktifkan SSO.

4. Konfigurasikan kode HTML kanvas kustom Anda untuk mengaktifkan SSO.

Prasyarat

• Mengaktifkan autentikasi pengguna dengan Microsoft Entra ID
• Menambahkan topik autentikasi ke agen Anda
• Menggunakan kanvas kustom

Catatan

Untuk mengonfigurasi SSO menggunakan penyedia 2.0 lainnya OAuth , lihat Mengonfigurasi akses menyeluruh dengan penyedia OAuth generik.

Saluran yang didukung

Tabel berikut merinci saluran yang saat ini mendukung SSO. Anda dapat menyarankan dukungan untuk saluran tambahan di Copilot Studio forum ide.

Saluran	Didukung
Saluran Azure Bot Service	Tidak didukung
Situs Web Kustom	Didukung
Situs Web Demo	Tidak didukung
Facebook	Tidak didukung
Microsoft Teams1	Didukung
Aplikasi Seluler	Tidak didukung
Multisaluran untuk Customer Service2	Didukung

¹ Jika Anda juga mengaktifkan saluran Teams, Anda harus mengikuti instruksi konfigurasi pada Mengonfigurasi akses menyeluruh dengan ID Microsoft Entra untuk agen dalam Microsoft Teams dokumentasi. Gagal mengonfigurasi pengaturan SSO Teams seperti yang diinstruksikan di halaman tersebut menyebabkan pengguna Anda selalu gagal dalam autentikasi saat menggunakan saluran Teams.

² Hanya saluran obrolan langsung yang didukung. Untuk informasi selengkapnya, lihat Mengonfigurasi serah terima ke Dynamics 365 Customer Service.

Penting

SSO saat ini tidak didukung jika agen telah:

• Diterbitkan ke Power Apps portal.
• Diterbitkan ke SharePoint situs web sebagai iframe.

Namun, SSO didukung untuk agen yang telah dipublikasikan ke SharePoint situs web sebagai komponen SPFx.

Aplikasi web

Membuat pendaftaran aplikasi untuk situs web kustom Anda

Untuk mengaktifkan SSO, Anda perlu membuat dua pendaftaran aplikasi terpisah:

• Pendaftaran aplikasi autentikasi, yang memungkinkan Microsoft Entra autentikasi pengguna ID untuk agen Anda
• Pendaftaran aplikasi kanvas, yang memungkinkan SSO untuk halaman web kustom Anda

Kami tidak menyarankan untuk menggunakan kembali pendaftaran aplikasi yang sama untuk agen dan situs web khusus Anda karena alasan keamanan.

1. Ikuti petunjuk dalam Mengonfigurasi autentikasi pengguna dengan Microsoft Entra ID untuk membuat pendaftaran aplikasi autentikasi.

2. Ikuti petunjuk untuk membuat pendaftaran aplikasi autentikasi lagi, untuk membuat pendaftaran aplikasi kedua, yang berfungsi sebagai pendaftaran aplikasi kanvas Anda.

3. Tambahkan ID pendaftaran aplikasi kanvas ke pendaftaran aplikasi autentikasi.

Tambahkan URL pertukaran token

Untuk memperbarui Microsoft Entra pengaturan Copilot Studio autentikasi ID, Anda perlu menambahkan URL pertukaran token untuk mengizinkan aplikasi Anda dan Copilot Studio berbagi informasi.

1. Di portal Microsoft Azure pada bilah pendaftaran aplikasi autentikasi Anda, buka Mengekspos API.

2. Di bawah Cakupan, pilih ikon Salin ke clipboard .

3. Dalam Copilot Studio, di menu navigasi di bawah Pengaturan, pilih Keamanan, lalu pilih ubin Autentikasi .

4. Untuk URL pertukaran token (diperlukan untuk SSO), tempelkan cakupan yang Anda salin sebelumnya.

5. Pilih Simpan.

Mengonfigurasi pendaftaran aplikasi kanvas Anda

1. Setelah Anda membuat pendaftaran aplikasi kanvas, buka Autentikasi, lalu pilih Tambahkan platform.

2. Di bawah Konfigurasi platform, pilih Tambahkan platform, lalu pilih Web.

3. Di bawah URI pengalihan, masukkan URL untuk halaman web Anda; misalnya,. http://contoso.com/index.html

   

4. Di bagian Aliran hibah dan hibrida implisit, aktifkan token Akses (digunakan untuk alur implisit) dan token ID (digunakan untuk alur implisit dan hibrida).

5. Pilih mengkonfigurasi.

Temukan URL titik akhir token agen Anda

1. Masuk Copilot Studio, buka agen Anda, lalu pilih Saluran.

2. Pilih Aplikasi seluler.

3. Di bawah Titik Akhir Token, pilih Salin.

   

Mengonfigurasi SSO di halaman web Anda

Gunakan kode yang disediakan di Copilot Studio repositori GitHub untuk membuat halaman web untuk URL pengalihan. Salin kode dari repositori GitHub dan modifikasi menggunakan petunjuk berikut.

Catatan

Kode di repositori GitHub mengharuskan pengguna memilih tombol login atau login dari situs yang berbeda. Untuk mengaktifkan login otomatis, tambahkan kode berikut di awal aysnc function main():

    (async function main() {
        if (clientApplication.getAccount() == null) {
           await clientApplication.loginPopup(requestObj).then(onSignin).catch(function (error) {console.log(error) });
        }
        // Add your BOT ID below 
        var theURL =

1. Buka halaman Gambaran Umum di portal Microsoft Azure dan salin ID Aplikasi (klien) dan ID Direktori (penyewa) dari pendaftaran aplikasi kanvas Anda.

   

2. Untuk mengonfigurasi Microsoft Authentication Library (MSAL):

   • Tetapkan clientId ke ID Aplikasi (klien) Anda.
   • Tetapkan authority dan https://login.microsoftonline.com/ tambahkan ID Direktori (penyewa) Anda ke akhir.

   Contoh:

   var clientApplication;
       (function (){
       var msalConfig = {
           auth: {
               clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
               authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'     
           },
   

3. Atur theURL variabel ke URL titik akhir token yang Anda salin sebelumnya. Contoh:

   (async function main() {
   
       var theURL = "https://<token endpoint URL>"
   

4. Edit nilai untuk userId menyertakan awalan khusus. Contoh:

   var userId = clientApplication.account?.accountIdentifier != null ? 
           ("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64) 
           : (Math.random().toString() + Date.now().toString()).substr(0,64);
   

5. Simpan perubahan.

6. Pastikan Anda telah berhasil mengonfigurasi SSO.

   Saat menguji agen Anda, jika SSO tidak berhasil dikonfigurasi, Anda akan diminta untuk masuk, yang memberi Anda kode validasi yang harus Anda salin ke jendela obrolan.

   Jika Anda melihat perintah masuk, pastikan Anda telah menyelesaikan langkah 1 hingga 5 dari prosedur ini dengan benar. Jika SSO berhasil dikonfigurasi, Anda tidak diminta untuk masuk.

Konten terkait

• Pendaftaran Aplikasi Azure

Klasik

Gambaran teknis

Ilustrasi berikut menunjukkan bagaimana pengguna masuk tanpa melihat perintah masuk (SSO) di: Copilot Studio

1. Pengguna agen memasukkan frasa yang memicu topik masuk. Topik masuk dirancang untuk membuat pengguna masuk dan menggunakan token (variabel )User.AccessToken penggunayang diautentikasi.

2. Copilot Studio mengirimkan perintah masuk untuk mengizinkan pengguna masuk dengan penyedia identitas yang dikonfigurasi.

3. Kanvas kustom agen mencegat perintah masuk dan meminta token atas nama (OBO) dari Microsoft Entra ID. Kanvas mengirim token ke agen.

4. Setelah menerima token OBO, agen menukar token OBO dengan "token akses" dan mengisi AuthToken variabel menggunakan nilai token akses. Variabel juga IsLoggedIn diatur saat ini.

Membuat pendaftaran aplikasi di Microsoft Entra ID untuk kanvas kustom Anda

Untuk mengaktifkan SSO, Anda memerlukan dua pendaftaran aplikasi terpisah:

• Satu untuk agen Anda untuk mengaktifkan otentikasi pengguna dengan Microsoft Entra ID.
• Satu untuk kanvas kustom Anda untuk mengaktifkan SSO.

Penting

Anda tidak dapat menggunakan kembali pendaftaran aplikasi yang sama untuk autentikasi pengguna agen dan kanvas kustom Anda.

Membuat pendaftaran aplikasi untuk kanvas agen

1. Masuk ke Azure portal.

2. Buka Pendaftaran aplikasi, baik dengan memilih ikon atau mencari di bilah pencarian atas.

   

3. Pilih pendaftaran baru.

   

4. Masukkan nama untuk registrasi. Akan sangat membantu untuk menggunakan nama agen yang kanvasnya Anda daftarkan dan menyertakan "kanvas" untuk membantu memisahkannya dari pendaftaran aplikasi untuk autentikasi.

   Misalnya, jika agen Anda disebut "Contoso sales help", Anda dapat menamai pendaftaran aplikasi sebagai "ContosoSalesCanvas" atau yang serupa.

5. Di bawah Jenis akun yang didukung, pilih Akun di penyewa organisasi apa pun (direktori ID apa pun Microsoft Entra - Multipenyewa) dan akun Microsoft pribadi (misalnya Skype, Xbox).

6. Biarkan bagian URI pengalihan kosong untuk saat ini, saat Anda memasukkan informasi tersebut di langkah berikutnya. Pilih Daftarkan.

   

7. Setelah pendaftaran selesai, itu akan terbuka ke halaman Ikhtisar . Buka Manifestasi. Konfirmasikan bahwa diatur accessTokenAcceptedVersion ke. 2 Jika tidak, ubah menjadi lalu 2 pilih Simpan.

Menambahkan URL pengalihan

1. Dengan pendaftaran terbuka, buka Autentikasi, lalu pilih Tambahkan platform.

   

2. Pada bilah Konfigurasikan platform , pilih Web.

   

3. Di bagian URI pengalihan, tambahkan URL lengkap ke halaman tempat kanvas obrolan Anda dihosting. Di bawah bagian Pemberian implisit , pilih kotak centang Token Id dan Token Akses .

4. Pilih Konfigurasi untuk mengonfirmasi perubahan Anda.

   

5. Buka Izin API. Pilih Berikan persetujuan admin untuk <nama> penyewa Anda, lalu Ya.

   Penting

   Untuk menghindari pengguna harus menyetujui setiap aplikasi, seseorang yang ditetapkan setidaknya peran Administrator Aplikasi atau Administrator Aplikasi Cloud dapat memberikan persetujuan di seluruh penyewa untuk pendaftaran aplikasi Anda.

   

Menentukan cakupan kustom untuk agen Anda

Tentukan cakupan kustom dengan mengekspos API untuk pendaftaran aplikasi Canvas dalam pendaftaran aplikasi autentikasi. Cakupan memungkinkan Anda menentukan peran pengguna dan admin serta hak akses.

Langkah ini membuat hubungan kepercayaan antara pendaftaran aplikasi otentikasi untuk otentikasi dan pendaftaran aplikasi untuk kanvas kustom Anda.

1. Buka pendaftaran aplikasi yang Anda buat saat mengonfigurasi autentikasi.

2. Buka Izin API dan pastikan izin yang benar ditambahkan untuk agen Anda. Pilih Berikan persetujuan admin untuk <nama> penyewa Anda, lalu Ya.

   Penting

   Untuk menghindari pengguna harus menyetujui setiap aplikasi, seseorang yang ditetapkan setidaknya peran Administrator Aplikasi atau Administrator Aplikasi Cloud dapat memberikan persetujuan di seluruh penyewa untuk pendaftaran aplikasi Anda.

3. Buka Mengekspos API dan pilih Tambahkan cakupan.

   

4. Masukkan nama untuk cakupan, beserta informasi tampilan yang harus ditampilkan kepada pengguna saat mereka masuk ke layar SSO. Pilih Tambahkan cakupan.

   

5. Pilih Tambahkan aplikasi klien.

6. Masukkan ID Aplikasi (klien) dari halaman Ikhtisaruntuk pendaftaran aplikasi kanvas ke bidang ID Klien. Pilih kotak centang untuk cakupan terdaftar yang Anda buat.

7. Pilih Tambahkan aplikasi.

Mengonfigurasi autentikasi untuk Copilot Studio mengaktifkan SSO

URL Pertukaran Token di Copilot Studio halaman konfigurasi autentikasi digunakan untuk menukar token OBO dengan token akses yang diminta melalui kerangka kerja bot.

Copilot Studio memanggil ID Microsoft Entra untuk melakukan pertukaran yang sebenarnya.

1. Masuk ke. Copilot Studio

2. Konfirmasikan bahwa Anda telah memilih agen yang ingin Anda aktifkan autentikasinya dengan memilih ikon agen di menu atas dan memilih agen yang benar.

3. Di menu navigasi, di bawah Pengaturan, pilih Keamanan. Kemudian pilih kartu Autentikasi .

   

4. Masukkan URI cakupan penuh dari bilah Mengekspos API untuk pendaftaran aplikasi autentikasi agen di bidang URL pertukaran token. URI dalam format api://1234-4567/scope.name.

   

   

5. Pilih Simpan lalu publikasikan konten agen.

Konfigurasikan kode HTML kanvas kustom Anda untuk mengaktifkan SSO

Perbarui halaman kanvas kustom tempat agen berada untuk mencegat permintaan kartu login dan menukar token OBO.

1. Konfigurasikan Microsoft Authentication Library (MSAL) dengan menambahkan kode berikut ke dalam <tag skrip> di bagian kepala Anda. <>

2. Perbarui clientId dengan ID Aplikasi (klien) untuk pendaftaran aplikasi kanvas. Ganti <Directory ID> dengan ID Direktori (penyewa). Anda mendapatkan ID ini dari halaman Gambaran Umum untuk pendaftaran aplikasi kanvas.

   <head>
    <script>
      var clientApplication;
        (function () {
          var msalConfig = {
              auth: {
                clientId: '<Client ID [CanvasClientId]>',
                authority: 'https://login.microsoftonline.com/<Directory ID>'
              },
              cache: {
                cacheLocation: 'localStorage',
                storeAuthStateInCookie: false
              }
          };
          if (!clientApplication) {
            clientApplication = new Msal.UserAgentApplication(msalConfig);
          }
        } ());
    </script>
   </head>
   

3. Masukkan skrip <berikut> di <bagian isi> . Skrip ini memanggil metode untuk mengambil dan resourceUrl menukar token Anda saat ini dengan token yang diminta oleh OAuth prompt.

   <script>
   function getOAuthCardResourceUri(activity) {
     if (activity &&
          activity.attachments &&
          activity.attachments[0] &&
          activity.attachments[0].contentType === 'application/vnd.microsoft.card.oauth' &&
          activity.attachments[0].content.tokenExchangeResource) {
            // asking for token exchange with Microsoft Entra ID
            return activity.attachments[0].content.tokenExchangeResource.uri;
      }
   }
   
   function exchangeTokenAsync(resourceUri) {
     let user = clientApplication.getAccount();
      if (user) {
        let requestObj = {
          scopes: [resourceUri]
        };
        return clientApplication.acquireTokenSilent(requestObj)
          .then(function (tokenResponse) {
            return tokenResponse.accessToken;
            })
            .catch(function (error) {
              console.log(error);
            });
            }
            else {
            return Promise.resolve(null);
      }
   }
   </script>
   

4. Masukkan skrip <berikut> di <bagian isi> . Dalam metode, main kode ini menambahkan kondisional ke Anda store, dengan pengenal unik agen Anda. Ini juga menghasilkan ID unik sebagai variabel Anda userId .

5. Perbarui <COPILOT ID> dengan ID agen Anda. Anda dapat melihat ID agen Anda dengan membuka tab Saluran untuk agen yang Anda gunakan, dan memilih Aplikasi seluler di Copilot Studio portal.

   <script>
       (async function main() {
   
           // Add your AGENT ID below 
           var BOT_ID = "<BOT ID>";
           var theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
           const {
               token
           } = await fetchJSON(theURL);
   
           var directline = await fetchJSON(regionalChannelSettingsURL).then(res=> res.channelUrlsById.directline); 
   
           const directLine = window.WebChat.createDirectLine({
               domain: `${directline}v3/directline`,
               token
           });
   
           var userID = clientApplication.account?.accountIdentifier != null ?
               ("Your-customized-prefix-max-20-characters" + clientApplication.account.accountIdentifier).substr(0, 64) :
               (Math.random().toString() + Date.now().toString()).substr(0, 64); // Make sure this will not exceed 64 characters 
           const store = WebChat.createStore({}, ({
               dispatch
           }) => next => action => {
               const {
                   type
               } = action;
               if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
                   dispatch({
                       type: 'WEB_CHAT/SEND_EVENT',
                       payload: {
                           name: 'startConversation',
                           type: 'event',
                           value: {
                               text: "hello"
                           }
                       }
                   });
                   return next(action);
               }
               if (action.type === 'DIRECT_LINE/INCOMING_ACTIVITY') {
                   const activity = action.payload.activity;
                   let resourceUri;
                   if (activity.from && activity.from.role === 'bot' &&
                       (resourceUri = getOAuthCardResourceUri(activity))) {
                       exchangeTokenAsync(resourceUri).then(function(token) {
                           if (token) {
                               directLine.postActivity({
                                   type: 'invoke',
                                   name: 'signin/tokenExchange',
                                   value: {
                                       id: activity.attachments[0].content.tokenExchangeResource.id,
                                       connectionName: activity.attachments[0].content.connectionName,
                                       token,
                                   },
                                   "from": {
                                       id: userID,
                                       name: clientApplication.account.name,
                                       role: "user"
                                   }
                               }).subscribe(
                                   id => {
                                       if (id === 'retry') {
                                           // The agent was not able to handle the invoke, so display the oauthCard
                                           return next(action);
                                       }
                                       // else: tokenexchange successful and we do not display the oauthCard
                                   },
                                   error => {
                                       // an error occurred to display the oauthCard
                                       return next(action);
                                   }
                               );
                               return;
                           } else
                               return next(action);
                       });
                   } else
                       return next(action);
               } else
                   return next(action);
           });
   
           const styleOptions = {
   
               // Add styleOptions to customize Web Chat canvas
               hideUploadButton: true
           };
   
           window.WebChat.renderWebChat({
                   directLine: directLine,
                   store,
                   userID: userID,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })().catch(err => console.error("An error occurred: " + err));
   </script>
   

Kode Sampel penuh

Untuk informasi selengkapnya, Anda dapat menemukan kode sampel lengkap, dengan skrip kondisional MSAL dan simpan yang sudah disertakan di repositori GitHub kami.