Mengonfigurasi akses menyeluruh dengan Microsoft Entra ID

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

Misalnya, copilot dihosting di intranet perusahaan atau di aplikasi yang sudah masuk pengguna.

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 copilot Anda.

3. Konfigurasikan autentikasi untuk Copilot Studio mengaktifkan SSO.

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

Prasyarat

• Mengaktifkan autentikasi pengguna akhir dengan Microsoft Entra ID
• Menambahkan topik autentikasi ke kopilot 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 Microsoft 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 copilot 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 penyerahan ke Dynamics 365 layanan pelanggan.

Penting

SSO saat ini tidak didukung jika copilot telah:

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

Namun, SSO didukung untuk copilot 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 kopilot Anda
• Pendaftaran aplikasi kanvas, yang memungkinkan SSO untuk halaman web kustom Anda

Kami tidak menyarankan untuk menggunakan kembali pendaftaran aplikasi yang sama untuk copilot 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 kopilot Anda

1. Dalam Copilot Studio, buka copilot 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: '692e92c7-xxxx-4060-76d3-b381798f4d9c',
               authority: 'https://login.microsoftonline.com/7ef988bf-xxxx-51af-01ab-2d7fd011db47'     
           },
   

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

   (async function main() {
   
       var theURL = "https://1c0.0.environment.api.powerplatform.com/powervirtualagents/bots/5a099fd/directline/token?api-version=2022-03-01-preview"
   

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.

Uji copilot Anda menggunakan halaman web Anda

1. Buka halaman web Anda di browser Anda.

2. Pilih Masuk.

   

   Catatan

   Jika browser Anda memblokir popup atau Anda menggunakan jendela penjelajahan penyamaran atau pribadi, Anda akan diminta untuk masuk. Jika tidak, login selesai menggunakan kode validasi.

   Tab browser baru terbuka.

3. Beralih ke tab baru dan salin kode validasi.

4. Beralih kembali ke tab dengan copilot Anda, dan tempelkan kode validasi ke percakapan copilot.

Konten terkait

• Pendaftaran Aplikasi Azure

Klasik

Gambaran teknis

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

1. Pengguna copilot memasukkan frasa yang memicu topik login. Topik masuk dirancang untuk membuat pengguna masuk dan menggunakan token (variabel ) yangUser.AccessToken diautentikasi pengguna.

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

3. Kanvas kustom copilot mencegat prompt masuk dan meminta token atas nama (OBO) dari Microsoft Entra ID. Kanvas mengirimkan token ke kopilot.

4. Setelah menerima token OBO, kopilot 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 copilot 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 copilot dan kanvas kustom Anda.

Membuat pendaftaran aplikasi untuk kanvas kopilot

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 kopilot yang kanvasnya Anda daftarkan dan menyertakan "kanvas" untuk membantu memisahkannya dari pendaftaran aplikasi untuk autentikasi.

   Misalnya, jika copilot Anda disebut "bantuan penjualan Contoso", 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, Administrator Global, Administrator Aplikasi, atau Administrator Aplikasi Cloud harus memberikan persetujuan di seluruh penyewa untuk pendaftaran aplikasi Anda.

   

Menentukan cakupan kustom untuk copilot 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 copilot Anda. Pilih Berikan persetujuan admin untuk <nama> penyewa Anda, lalu Ya.

   Penting

   Untuk menghindari pengguna harus menyetujui setiap aplikasi, Administrator Global, Administrator Aplikasi, atau Administrator Aplikasi Cloud harus 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 Ikhtisar untuk 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 copilot yang ingin Anda aktifkan autentikasinya dengan memilih ikon copilot di menu atas dan memilih copilot yang benar.

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

   

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

   

   

5. Pilih Simpan lalu publikasikan konten copilot.

Konfigurasikan kode HTML kanvas kustom Anda untuk mengaktifkan SSO

Perbarui halaman kanvas kustom tempat copilot 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 kopilot Anda. Ini juga menghasilkan ID unik sebagai variabel Anda userId .

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

   

   <script>
       (async function main() {
   
           // Add your COPILOT 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') {
                                           // copilot 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.