Mengonfigurasi akses menyeluruh dengan Microsoft Entra ID
Artikel
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:
Buat pendaftaran aplikasi di Microsoft Entra ID untuk kanvas kustom Anda.
Tentukan cakupan kustom untuk agen Anda.
Konfigurasikan autentikasi untuk Copilot Studio mengaktifkan SSO.
Konfigurasikan kode HTML kanvas kustom Anda untuk mengaktifkan SSO.
1 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.
Ikuti petunjuk untuk membuat pendaftaran aplikasi autentikasi lagi, untuk membuat pendaftaran aplikasi kedua, yang berfungsi sebagai pendaftaran aplikasi kanvas Anda.
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.
Di portal Microsoft Azure pada bilah pendaftaran aplikasi autentikasi Anda, buka Mengekspos API.
Di bawah Cakupan, pilih ikon Salin ke clipboard .
Dalam Copilot Studio, di menu navigasi di bawah Pengaturan, pilih Keamanan, lalu pilih ubin Autentikasi .
Untuk URL pertukaran token (diperlukan untuk SSO), tempelkan cakupan yang Anda salin sebelumnya.
Pilih Simpan.
Mengonfigurasi pendaftaran aplikasi kanvas Anda
Setelah Anda membuat pendaftaran aplikasi kanvas, buka Autentikasi, lalu pilih Tambahkan platform.
Di bawah Konfigurasi platform, pilih Tambahkan platform, lalu pilih Web.
Di bawah URI pengalihan, masukkan URL untuk halaman web Anda; misalnya,. http://contoso.com/index.html
Di bagian Aliran hibah dan hibrida implisit, aktifkan token Akses (digunakan untuk alur implisit) dan token ID (digunakan untuk alur implisit dan hibrida).
Pilih mengkonfigurasi.
Temukan URL titik akhir token agen Anda
Masuk Copilot Studio, buka agen Anda, lalu pilih Saluran.
Pilih Aplikasi seluler.
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 =
Buka halaman Gambaran Umum di portal Microsoft Azure dan salin ID Aplikasi (klien) dan ID Direktori (penyewa) dari pendaftaran aplikasi kanvas Anda.
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'
},
Atur theURL variabel ke URL titik akhir token yang Anda salin sebelumnya. Contoh:
(async function main() {
var theURL = "https://<token endpoint URL>"
Edit nilai untuk userId menyertakan awalan khusus. Contoh:
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.
Ilustrasi berikut menunjukkan bagaimana pengguna masuk tanpa melihat perintah masuk (SSO) di: Copilot Studio
Pengguna agen memasukkan frasa yang memicu topik masuk. Topik masuk dirancang untuk membuat pengguna masuk dan menggunakan token (variabel )User.AccessToken penggunayang diautentikasi.
Copilot Studio mengirimkan perintah masuk untuk mengizinkan pengguna masuk dengan penyedia identitas yang dikonfigurasi.
Kanvas kustom agen mencegat perintah masuk dan meminta token atas nama (OBO) dari Microsoft Entra ID. Kanvas mengirim token ke agen.
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:
Buka Pendaftaran aplikasi, baik dengan memilih ikon atau mencari di bilah pencarian atas.
Pilih pendaftaran baru.
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.
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).
Biarkan bagian URI pengalihan kosong untuk saat ini, saat Anda memasukkan informasi tersebut di langkah berikutnya. Pilih Daftarkan.
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
Dengan pendaftaran terbuka, buka Autentikasi, lalu pilih Tambahkan platform.
Pada bilah Konfigurasikan platform , pilih Web.
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 .
Pilih Konfigurasi untuk mengonfirmasi perubahan Anda.
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.
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.
Buka Mengekspos API dan pilih Tambahkan cakupan.
Masukkan nama untuk cakupan, beserta informasi tampilan yang harus ditampilkan kepada pengguna saat mereka masuk ke layar SSO. Pilih Tambahkan cakupan.
Pilih Tambahkan aplikasi klien.
Masukkan ID Aplikasi (klien) dari halaman Ikhtisaruntuk pendaftaran aplikasi kanvas ke bidang ID Klien. Pilih kotak centang untuk cakupan terdaftar yang Anda buat.
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.
Masuk ke. Copilot Studio
Konfirmasikan bahwa Anda telah memilih agen yang ingin Anda aktifkan autentikasinya dengan memilih ikon agen di menu atas dan memilih agen yang benar.
Di menu navigasi, di bawah Pengaturan, pilih Keamanan. Kemudian pilih kartu Autentikasi .
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.
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.
Konfigurasikan Microsoft Authentication Library (MSAL) dengan menambahkan kode berikut ke dalam <tag skrip> di bagian kepala Anda. <>
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>
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>
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 .
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.