Copilot Studio çoklu oturum açmayı (SSO) destekler. SSO, web sitenizdeki aracıların, aracının dağıtıldığı sayfada veya uygulamada oturum açtıklarında müşterilerle oturum açmasına olanak tanır.
Örneğin aracı, kurumsal intranette veya kullanıcının zaten oturum açmış olduğu bir uygulamada barındırılır.
Copilot Studio için SSO'yu yapılandırmanın beş ana adımı vardır:
Aracınız için Microsoft Entra ID kullanarak el ile kimlik doğrulamayı etkinleştirme
Özel tuvaliniz için Microsoft Entra ID içinde bir uygulama kaydı oluşturun.
Microsoft Entra ID'de aracınız için özel bir kapsam tanımlayın.
Özel kapsamı aracı yapılandırmanıza ekleyin.
SSO'yu etkinleştirmek için özel tuval istemci tarafı kodunuzu yapılandırın.
Önkoşullar
Desteklenen kanallar
Aşağıdaki tabloda, SSO'yu destekleyen kanalların ayrıntıları verilmiştir. Ek kanallar için destek önerilerinizi Copilot Studio fikir forumunda sunabilirsiniz.
1 Teams kanalına yayın yaparsanız Microsoft Teams'teki aracılar için Microsoft Entra ID ile çoklu oturum açmayı yapılandırma belgesindeki yapılandırma yönergelerini izlemeniz gerekir. Teams SSO ayarlarının o sayfada açıklandığı gibi yapılandırılmaması, kullanıcılarınızın Teams kanalını kullanırken kimlik doğrulamasının her zaman başarısız olmasına neden olur.
2 Yalnızca canlı sohbet kanalı desteklenir. Daha fazla bilgi için bkz. Dynamics 365 Customer Service'e devri yapılandırma.
Özel web siteniz için bir uygulama kayıtları oluşturma
SSO'yu etkinleştirmek için iki ayrı uygulama kaydı oluşturun:
- Aracınız için Microsoft Entra ID kullanıcı kimlik doğrulamasını etkinleştiren bir kimlik doğrulama uygulaması kaydı
- Özel web sayfanız için SSO'yu etkinleştiren bir tuval uygulaması kaydı
Güvenlik nedenleriyle hem aracı hem de özel web siteniz için aynı uygulama kaydını yeniden kullanmayın.
Kimlik doğrulama uygulaması kaydı oluşturmak için Microsoft Entra ID ile kullanıcı kimlik doğrulamasını yapılandırma bölümündeki talimatları izleyin.
Tuval uygulama kaydı olarak kullanılacak ikinci bir uygulama kaydı oluşturun.
Belirteç değişimi URL'si ekleme
Copilot Studio içindeki Microsoft Entra ID kimlik doğrulama ayarlarını güncellemek için uygulamanızın ve Copilot Studio bilgi paylaşmasına izin verecek token değişim URL'sini ekleyin.
Azure portalında, kimlik doğrulama uygulamanızın kayıt sayfasında Bir API'yi kullanıma sunma bölümüne gidin.
Kapsamlar altında Panoya kopyala simgesini seçin.
Copilot Studio'ta, gezinti menüsünde Ayarlar altında Güvenlik seçeneğini belirleyin ve ardından Kimlik Doğrulaması kutucuğunu seçin.
Belirteç değişimi URL'si (SSO için gereklidir) için daha önce kopyaladığınız kapsamı yapıştırın.
Kaydet'i seçin.
Azure portalında, kimlik doğrulama uygulamanızın kayıt sayfasında Genel Bakış bölümüne gidin.
Uygulama (istemci) Kimliği değerini Temel Bilgiler altında kopyalayın.
Gezinti çubuğunda Yönet>Bir API'yi kullanıma sun öğesini seçin.
Yetkilendirilmiş istemci uygulamaları altında, İstemci uygulaması ekle seçeneğini belirleyin ve ardından kopyalanan istemci kimliğini yapıştırın.
Kaydet'i seçin.
Tuval uygulaması kaydınızı oluşturduktan sonra Kimlik doğrulaması'na gidin ve Platform ekle'yi seçin.
Platform yapılandırmaları altında Platform ekle'yi ve ardından SPA'yı seçin.
Yeniden yönlendirme URI'leri altından web sayfanızın URL'sini girin. Örneğin, http://contoso.com/index.html.
Örtük onay ve karma akışlar bölümünde Erişim belirteçleri (örtük akışlar için kullanılır) ve Kimlik belirteçleri (örtük ve karma akışlar için kullanılır) ayarlarını açın.
Yapılandır'ı seçin.
Aracınızın belirteç uç noktası URL'sini bulun
Copilot Studio içinde, aracınızı açın ve sonra Kanallar'ı seçin.
Mobil uygulama'yı seçin.
Belirteç Uç Noktası'nın altında Kopyala'yı seçin.
Web sayfanızda SSO yapılandırma
Önemli
SharePoint ve Graph Bağlayıcısı veri kaynaklarından AI tarafından oluşturulan yanıtları, SSO özellikli uygulamalardaki kullanıcılar kullanamaz.
Yeniden yönlendirme URL'si için bir web sayfası oluşturmak amacıyla Copilot Studio Örnekler GitHub deposunda sağlanan kodu kullanın. Kodu GitHub deposundan kopyalayın ve aşağıdaki yönergeleri kullanarak değiştirin.
Azure portalda Genel bakış sayfasına gidin ve Uygulama (istemci) kimliğini ve Dizin (kiracı) kimliğinizi, tuval uygulama kaydınızdan kopyalayın.
Microsoft Kimlik Doğrulama Kitaplığını (MSAL) yapılandırmak için:
-
Uygulama (istemci) kimliğinize
clientId atayın.
-
https://login.microsoftonline.com/ öğesine authority atayın ve sonuna Dizin (kiracı) kimliğinizi ekleyin.
Örneğin:
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
},
theURL değişkenini daha önce kopyaladığınız belirteç uç nokta URL'sine ayarlayın. Örneğin:
(async function main() {
var theURL = "https://<token endpoint URL>"
userId değerini özelleştirilmiş bir önek içerecek şekilde düzenleyin. Örneğin:
var userId = clientApplication.account?.accountIdentifier != null ?
("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64)
: (Math.random().toString() + Date.now().toString()).substr(0,64);
Değişikliklerinizi kaydedin.
SSO'nun başarıyla yapılandırıldığını doğrulayın.
Aracınızı test ederken, SSO başarıyla yapılandırılmadıysa oturum açmanız istenir. Oturum açma işlemi size, sohbet penceresine kopyalamanız gereken bir doğrulama kodu sağlar.
Bir oturum açma istemi görürseniz, bu yordamın 1 ile 5 arasındaki adımlarını doğru şekilde tamamladığınızdan emin olun. SSO başarıyla yapılandırılırsa, oturum açmanız istenmez.
Not
GitHub deposundaki kod, kullanıcıların oturum açma düğmesini seçmesini gerektirir. Üretimde, düğme işlevini sayfaya gitme gibi daha uygun bir olayla değiştirmek isteyebilirsiniz.
Teknik genel bakış
Aşağıdaki görsel, Copilot Studio'da kullanıcının oturum açma istemi görmeden nasıl oturum açtığını (SSO) göstermektedir:
Aracı kullanıcısı, oturum açma konusunu tetikleyen bir ifade girer. Oturumu açma konu, kullanıcıyı imzalamaya ve kullanıcının kimliği doğrulanmış belirtecini (User.AccessToken değişkenini) kullanacak şekilde tasarlanmıştır.
Copilot Studio, kullanıcının yapılandırılmış kimlik sağlayıcısıyla oturum açmasına olanak sağlamak için bir oturum açma istemi gönderir.
Aracının özel tuvali oturum açma istemini keser ve Microsoft Entra ID'den bir adına (OBO) belirteci ister. Tuval, belirteci aracıya gönderir.
OBO belirteci alındığında, aracı bir "erişim belirteci" için obo belirtecini alışverişlerde, erişim belirteci değerini kullanarak AuthToken değişkeni doldurur.
IsLoggedIn değişkeni de aynı anda ayarlanır.
Özel tuvaliniz için Microsoft Entra ID içinde bir uygulama kaydı oluşturun
SSO'yu etkinleştirmek için iki ayrı uygulama kaydı gerekir:
Önemli
Aynı uygulama kaydını hem aracınızın kullanıcı kimlik doğrulaması hem de özel tuvaliniz için yeniden kullanamazsınız.
Aracınızın tuvali için bir uygulama kaydı oluşturma
Azure portalında oturum açın.
Simgeyi seçerek veya üst arama çubuğunda arama yaparak Uygulama kayıtlarına gidin.
Yeni kayıt seçeneğini belirleyin.
Kayıt için bir ad girin. Tuvalini kaydettiğiniz aracınızın adını kullanın ve kimlik doğrulaması sırasında uygulama kaydından ayırmak için "tuval" sözcüğünü eklemek yararlı olabilir.
Örneğin, aracınıza "Contoso satış yardımı" adı verilmişse uygulama kaydını "ContosoSalesCanvas" veya benzeri bir adla adlandırabilirsiniz.
Desteklenen hesap türleri altında Herhangi bir kuruluş kiracısındaki hesaplar (Herhangi bir Microsoft Entra ID dizini, Çok müşterili) ve kişisel Microsoft hesapları (ör. Skype, XBOX) seçeneğini belirleyin.
Sonraki adımlarda ilgili bilgileri girdiğinizden, Yönlendirme URI'sı bölümünü şimdilik boş bırakın.
Kaydol'u seçin.
Kayıt tamamlandıktan sonra, Genel Bakış sayfasına açılır.
Bildirim bölümüne gidin.
accessTokenAcceptedVersion değerinin 2 olarak ayarlandığını onaylayın. Böyle değilse 2 olarak değiştirin ve ardından Kaydet'i seçin.
Yeniden yönlendirme URL'si ekleme
Kayıt açıkken Kimlik doğrulaması'na gidin ve Platform ekle'yi seçin.
Platformları yapılandır panelinde Web'i seçin.
URL'leri yeniden yönlendir altında, sohbet tuvalinizin barındığı sayfaya tam URL'yi ekleyin.
Örtük onay bölümü altında Kimlik Belirteçleri ve Erişim Belirteçleri onay kutularını işaretleyin.
Değişikliklerinizi onaylamak için Yapılandır'ı seçin.
API İzinleri'ne gidin.
<Kiracı adınız> için yönetici izni verin'i ve ardından Evet'i seçin.
Önemli
Kullanıcıların her uygulama için onay verme zorunluluğunu önlemek amacıyla, en azından Uygulama Yöneticisi veya Bulut Uygulama Yöneticisi rolüne atanmış biri, uygulama kayıtlarınıza kiracı genelinde onay verebilir.
Aracınız için özel bir kapsam tanımlama
Kimlik doğrulama uygulaması kaydı içinde tuval uygulaması kaydı için bir API ortaya çıkartarak özel bir kapsam tanımlayın.
Kapsamlar, kullanıcı ve yönetici rollerini ve erişim haklarını belirlemenizi sağlar.
Bu adım, kimlik doğrulaması için kimlik doğrulama uygulaması kaydı ile özel tuvaliniz için uygulama kaydı varlıkları arasında bir güven ilişkisi oluşturur.
Kimlik doğrulamasını yapılandırdığınızda oluşturduğunuz uygulama kaydını açın.
API İzinleri'ne gidin ve aracınız için doğru izinlerin eklendiğinden emin olun.
<Kiracı adınız> için yönetici izni verin'i ve ardından Evet'i seçin.
Önemli
Kullanıcıların her uygulama için onay verme zorunluluğunu önlemek amacıyla, en azından Uygulama Yöneticisi veya Bulut Uygulama Yöneticisi rolüne atanmış biri, uygulama kayıtlarınıza kiracı genelinde onay verebilir.
Bir API’yi kullanıma sunma'ya gidin ve Kapsam ekle'yi seçin.
Kapsamın adını ve SSO ekranına geldiklerinde kullanıcıların göreceği görünen bilgileri girin.
Kapsam ekle'yi seçin.
İstemci uygulaması ekle'yi seçin.
Tuval uygulaması kaydı için Genel Bakış sayfasındaki Uygulama (istemci) Kimliği'ni İstemci Kimliği alanına girin. Oluşturduğunuz kapsam için onay kutusunu seçin.
Uygulama ekle'yi seçin.
OBO belirtecinin bot çerçevesi üzerinden istenen erişim belirteciyle değiştirilmesi için Copilot Studio kimlik doğrulaması yapılandırması sayfasındaki Belirteç Değişim URL'sini kullanın.
Copilot Studio, gerçek değişimi gerçekleştirmek için Microsoft Entra ID'yi çağırır.
Copilot Studio'da oturum açın.
Kimlik doğrulamasını etkinleştirmek istediğiniz aracıyı seçtiğinizden emin olmak için, üst menüdeki aracı simgesini seçin ve doğru aracıyı belirleyin.
Gezinti menüsünde, Ayarlar altında Güvenlik'i seçin. Ardından Kimlik Doğrulaması kartını seçin.
Belirteç değişim URL'si alanında aracının kimlik doğrulama uygulama kaydı için Bir API'yi kullanıma sunma sayfasında tam kapsamlı URI'yi girin. URI, api://1234-4567/scope.name biçimindedir.
Kaydet'i seçin ve ardından aracı içeriğini yayımlayın.
Oturum açma kartı isteğine engel olmak ve OBO belirtecini değiştirmek için aracının bulunduğu özel tuval sayfasını güncelleştirin.
<Ana> bölümünüzdeki bir <komut dosyası> etiketine aşağıdaki kodu ekleyerek Microsoft Kimlik Doğrulaması Kitaplığı'nı (MSAL) yapılandırın.
Tuval uygulama kaydı için clientId uygulamasını Uygulama (istemci) Kimliği ile güncelleştirin.
<Directory ID> uygulamasını Dizin (kiracı) kimliği ile değiştirin. Bu kimlikleri (ID'leri), tuval uygulaması kaydı için Genel Bakış sayfasından alırsınız.
<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>
<Gövde> bölümüne aşağıdaki <komut dosyası>'nı ekleyin. Bu komut dosyası, bir yöntem çağırarak resourceUrl uygulamasını alır ve geçerli belirtecinizi OAuth istemi tarafından istenen bir belirteçle değiştirir.
<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>
<Gövde> bölümüne aşağıdaki <komut dosyası>'nı ekleyin.
main yöntemin içinde bu kod, aracının benzersiz tanımlayıcısına sahip olan store uygulamanıza bir koşullu ekler. Bu ayrıca userId değişkeniniz olarak benzersiz bir kimlik oluşturur.
<BOT ID> uygulamasını aracınızın kimliğiyle güncelleyin. Aracınızın kimliğini Copilot Studio'da görmek için, aracınızın Kanallar sayfasına gidin ve Mobil uygulama seçeneğini belirleyin.
<script>
(async function main() {
// Add your BOT 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>
Tam örnek kod
MSAL ve mağaza koşullu komut dosyalarının zaten dahil edildiği tam örnek kodu, Copilot Studio Örnekleri GitHub deposunda bulabilirsiniz.
İlgili içerik