category
重要事项
在对生成式人工智能进行了大量投资并增强了Microsoft Copilot之间的集成后,Power Virtual Agents的功能和特性现在是Microsoft Copiloth Studio的一部分。
在我们更新文档和培训内容时,一些文章和屏幕截图可能会参考Power Virtual Agents。
Copilot Studio支持单点登录(SSO)。SSO允许您网站上的副驾驶登录客户,如果他们已经登录到部署副驾驶的页面或应用程序。
先决条件
- Enable end-user authentication with Microsoft Entra ID.
- Add an authentication topic to your copilot.
- Use a custom canvas.
注:要使用其他OAuth 2.0提供程序配置SSO,请参阅使用通用OAuth提供程序配置单点登录
例如,副驾驶托管在公司内联网上或用户已登录的应用程序中。
为Copilot Studio配置SSO有四个主要步骤:
- 在Microsoft Entra ID中为您的自定义画布创建应用程序注册。
- 为副驾驶定义一个自定义范围。
- 在Copilot Studio中配置身份验证以启用SSO。
- 配置您的自定义画布HTML代码以启用SSO。
支持的频道
下表详细介绍了当前支持SSO的通道。您可以在Microsoft Copilot Studio创意论坛上建议支持其他频道。
Channel | Supported |
---|---|
Azure Bot Service channels | Not supported |
Custom Website | Supported |
Demo Website | Not supported |
Not supported | |
Microsoft Teams1 | Supported |
Mobile App | Not supported |
Omnichannel for Customer Service2 | Supported |
支持全渠道客户服务2
- 1如果您还启用了Teams频道,则需要按照Configure SSO for Teams频道【Configure SSO for Teams channel 】文档中的配置说明进行操作。未能按照该页面上的指示配置Teams SSO设置会导致您的用户在使用Teams通道时始终无法通过身份验证。
- 2仅支持实时聊天频道。有关更多信息,请参阅配置切换到Dynamics 365客户服务。
重要事项
当副驾驶满足以下任一条件时,SSO目前不受支持:
- 发布到Power Apps门户网站。
- 作为iframe发布到SharePoint网站。
但是,SSO支持作为SPFx组件发布到SharePoint网站的副本。
Web应用程序
为您的自定义网站创建应用程序注册
要启用SSO,您需要创建两个单独的应用程序注册:
- 身份验证应用程序注册,为您的副驾驶启用Microsoft Entra ID用户身份验证
- 画布应用程序注册,为您的自定义网页启用SSO
出于安全原因,我们不建议对副驾驶和自定义网站重复使用相同的应用程序注册。
- 按照“使用Microsoft Entra ID配置用户身份验证”【Configure user authentication with Microsoft Entra ID】中的说明创建身份验证应用程序注册。
- 再次按照相同的说明创建第二个应用程序注册,作为画布应用程序注册。
配置您的canvas应用程序注册
- 创建画布应用程序注册后,转到身份验证,然后选择添加平台。
- 在“平台配置”下,选择“添加平台”,然后选择“Web”。
- 在重定向URI下,输入网页的URL;例如,http://contoso.com/index.html.
配置网页的屏幕截图。
- 在隐式授权和混合流部分,同时启用Access令牌(用于隐式流)和ID令牌(用于显式流和混合流)。
- 选择配置。
查找副驾驶的令牌端点URL
- 在Copilot Studio中,转到“设置”,然后选择“频道”。
- 选择移动应用程序。
- 在“令牌终结点”下,选择“复制”。
在Copilot Studio中复制令牌端点URL的屏幕截图。
在网页中配置SSO
使用Copilot Studio GitHub仓库中提供的代码为重定向URL创建网页。从GitHub仓库中复制代码,并使用以下说明进行修改。
- 转到Azure门户中的概述页面,从画布应用程序注册中复制应用程序(客户端)ID和目录(租户)ID。
Azure门户中应用程序注册概述页面的屏幕截图,突出显示了概述、应用程序ID和目录ID。
- 要配置Microsoft身份验证库(SCL),请执行以下操作:
- 将clientId分配给您的应用程序(客户端)ID。
- 将权限分配给https://login.microsoftonline.com/并将您的目录(租户)ID添加到末尾。
例如:
C
var clientApplication;
(function (){
var msalConfig = {
auth: {
clientId: '692e92c7-xxxx-4060-76d3-b381798f4d9c',
authority: 'https://login.microsoftonline.com/7ef988bf-xxxx-51af-01ab-2d7fd011db47'
},
- 将URL变量设置为您之前复制的令牌端点URL。例如:
C
(async function main() {
var theURL = "https://1c0.0.environment.api.powerplatform.com/powervirtualagents/
bots/5a099fd/directline/token?api-version=2022-03-01-preview"
编辑userId的值以包含自定义前缀。例如:
C
var userId = clientApplication.account?.accountIdentifier != null ?
("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64)
: (Math.random().toString() + Date.now().toString()).substr(0,64);
- 保存您的更改。
使用网页测试副驾驶
- 在浏览器中打开您的网页。
- 选择登录。
使用验证码登录的屏幕截图
注:
如果您的浏览器阻止弹出窗口,或者您正在使用匿名或私人浏览窗口,系统会提示您登录。否则,登录将使用验证码完成。
一个新的浏览器选项卡打开。
- 切换到新选项卡并复制验证代码。
- 切换回副驾驶的选项卡,并将验证代码粘贴到副驾驶对话中。
Related content
经典的
The following illustration shows how a user is signed in without seeing a login prompt (SSO) in Copilot Studio: The copilot user enters a phrase that triggers a sign-in topic. The sign-in topic is designed to sign the user in and use the user's authenticated token ( Copilot Studio sends a login prompt to allow the user to sign in with their configured identity provider. The copilot's custom canvas intercepts the sign-in prompt and requests an on-behalf-of (OBO) token from Microsoft Entra ID. The canvas sends the token to the copilot. On receipt of the OBO token, the copilot exchanges the OBO token for an "access token" and fills in the To enable SSO, you need two separate app registrations: Important You can't reuse the same app registration for both your copilot's user authentication and your custom canvas. Sign in to the Azure portal. Go to App registrations, either by selecting the icon or searching in the top search bar. Select New registration. Enter a name for the registration. It can be helpful to use the name of the copilot whose canvas you're registering and include "canvas" to help separate it from the app registration for authentication. For example, if your copilot is called "Contoso sales help," you might name the app registration as "ContosoSalesCanvas" or something similar. Select the account type under Supported account types. We recommend you select Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant) and personal Microsoft accounts (for example Skype, Xbox). Leave the Redirect URI section blank for now, as you enter that information in the next steps. Select Register. After the registration is completed, it opens to the Overview page. Go to Manifest. Confirm that With the registration open, go to Authentication and then select Add a platform. On the configure platforms blade, select Web. Under Redirect URIs, add the full URL to the page where your chat canvas is hosted. Under the Implicit grant section, select the Id Tokens and Access Tokens checkboxes. Select Configure to confirm your changes. Go to API Permissions. Select Grant admin consent for <your tenant name> and then Yes. Important To avoid users from having to consent to each application, a Global Administrator, Application Administrator, or a Cloud Application Administrator must grant tenant-wide consent to your app registrations. Define a custom scope by exposing an API for the canvas app registration within the authentication app registration. Scopes allow you to determine user and admin roles and access rights. This step creates a trust relationship between the authentication app registration for authentication and the app registration for your custom canvas. Open the app registration that you created when you configured authentication. Go to API Permissions and ensure that the correct permissions are added for your copilot. Select Grant admin consent for <your tenant name> and then Yes. Important To avoid users from having to consent to each application, a Global Administrator, Application Administrator, or a Cloud Application Administrator must grant tenant-wide consent to your app registrations. Go to Expose an API and select Add a scope. Enter a name for the scope, along with the display information that should be shown to users when they come to the SSO screen. Select Add scope. Select Add a client application. Enter the Application (client) ID from the Overview page for the canvas app registration into the Client ID field. Select the checkbox for the listed scope that you created. Select Add application. The Token Exchange URL in the Copilot Studio authentication configuration page is used to exchange the OBO token for the requested access token through the bot framework. Copilot Studio calls into Microsoft Entra ID to perform the actual exchange. Sign in to Copilot Studio. Confirm you've selected the copilot you want to enable authentication for by selecting the copilot icon on the top menu and choosing the correct copilot. In the navigation menu, under Settings, select Security. Then select the Authentication card. Enter the full scope URI from the Expose an API blade for the copilot's authentication app registration in the Token exchange URL field. The URI is in the format of Select Save and then publish the copilot content. Update the custom canvas page where the copilot is located to intercept the login card request and exchange the OBO token. Configure the Microsoft Authentication Library (MSAL) by adding the following code into a <script> tag in your <head> section. Update Insert the following <script> in the <body> section. This script calls a method to retrieve the Insert the following <script> in the <body> section. Within the Update For more information, you can find the full sample code, with the MSAL and store conditional scripts already included at our GitHub repo.
Technical overview
AuthToken
variable).AuthToken
variable using the access token's value. The IsLoggedIn
variable is also set at this time.Create an app registration in Microsoft Entra ID for your custom canvas
Create an app registration for the copilot's canvas
accessTokenAcceptedVersion
is set to 2
. If it isn't, change it to 2
and then select Save.Add the redirect URL
Define a custom scope for your copilot
Configure authentication in Copilot Studio to enable SSO
api://1234-4567/scope.name
.Configure your custom canvas HTML code to enable SSO
clientId
with the Application (client) ID for the canvas app registration. Replace <Directory ID>
with the Directory (tenant) ID. You get these IDs from the Overview page for the canvas app registration.<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>
resourceUrl
and exchange your current token for a token requested by the 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>
main
method, this code adds a conditional to your store
, with your copilot's unique identifier. It also generates a unique ID as your userId
variable.<COPILOT ID>
with your copilot's ID. You can see your copilot's ID by going to the Channels tab for the copilot you're using, and selecting Mobile app on the 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>
Full sample code
- 登录 发表评论
- 7 次浏览
最新内容
- 2 days 15 hours ago
- 2 days 16 hours ago
- 2 days 16 hours ago
- 2 days 16 hours ago
- 2 days 17 hours ago
- 2 days 17 hours ago
- 2 days 17 hours ago
- 2 days 17 hours ago
- 4 days 5 hours ago
- 4 days 6 hours ago