可以通过添加模式对话框来增强智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 的声明式代理中的自适应卡片响应。 这些弹出对话框可以托管自定义 HTML/JavaScript,也可以在专注的交互式体验中显示基于 iframe 的小组件(如网页、YouTube 视频或 Microsoft Stream 内容)。
本文介绍如何使用 Action.OpenUrlDialog 自适应卡架构版本 1.5) 中提供的 (从自适应卡模板启动模式对话框,以及如何配置用户身份验证。
注意
该 OpenUrlDialog 操作目前处于预览状态。
先决条件
若要使用 Action.OpenUrlDialog,需要满足以下先决条件:
- 自适应卡架构版本 1.5
- API 插件清单版本 2.3
- Microsoft用于身份验证方案的 TeamsJS 库 ()
定义自适应卡片模板
要使用模式对话框操作:
下面的示例显示了 的架构 Action.OpenUrlDialog。
"actions": [
{
"type": "Action.OpenUrlDialog",
"title": "OpenDialogWithDimension",
"url": "${url}",
"dialogHeight": "large",
"dialogWidth": "600px",
"dialogTitle": "task module"
}
]
有关架构参考信息,请参阅 Action.OpenUrlDialog。
配置对话框大小
使用 dialogHeight 和 dialogWidth 属性设置对话框的高度和宽度。 这些值会根据用户的屏幕分辨率和窗口的大小动态调整。
可以指定:
- 预定义大小 -
small、medium或large。 - 自定义像素值 - 例如
400px, .600px
提示
使用像素值进行精确控制。 预定义大小与可用屏幕空间相关。
下图显示了从代理返回的自适应卡按钮调用的对话框示例。
配置身份验证
若要允许从对话框内安全访问 API,请使用以下方法之一配置身份验证:
- 注册 Windows 预览体验计划的
- OAuth 2.0 (预览版)
Microsoft Entra ID 设置
若要使用 Entra ID 身份验证进行 API 身份验证,请使用以下方法之一:
- 使用 Microsoft 作为标识提供程序配置基于 Entra ID、OAuth 2.0 或基于 API 密钥的身份验证。
- 使用其他标识提供者并在 Entra ID 中注册您的应用。
配置基于 SSO 的身份验证
配置单一登录 (SSO) ,允许用户访问 API,而无需多次登录。
若要启用 SSO:
- 更新 Microsoft Entra ID 应用程序。
- 配置应用程序 ID URI。
- 配置范围和同意设置。
- 对受信任的客户端应用程序进行预授权,以避免重复的同意提示。
- 实现令牌检索和验证逻辑。
- 使用 TeamsJS 库中的方法
getAuthToken()检索访问令牌。 - 在授权标头中将令牌发送到服务器。
- 在服务器端验证令牌。
- 使用 TeamsJS 库中的方法
- 更新应用清单。
- 将 webApplicationInfo 属性添加到应用清单以启用 SSO。
- 将对话框内容的域添加到应用清单的“validDomains ”属性中。
更新 Microsoft Entra ID 应用程序
若要配置范围并授权受信任的客户端应用程序,请按如下所示更新 Microsoft Entra ID 应用程序:
将 API URI 添加到应用清单的 identifierUris 属性。 使用以下 URI 格式:“api://fully-qualified-domain-name.com/{AppID}”,如以下示例所示。
"identifierUris": [ "api://b4ab3a28-16da-4a19-a07a-51ab0f3553db", "api://4-213-70-45.ngrok-free.app/b4ab3a28-16da-4a19-a07a-51ab0f3553db", "api://auth-58bfdecc-2870-4cda-99b4-1d30383b952b/b4ab3a28-16da-4a19-a07a-51ab0f3553db" ],定义 API 的范围以及谁可以同意该范围。 在 Microsoft Entra 管理中心的“此 API 定义的范围”部分中,选择“+ 添加范围”。
- 输入作用域名称。 此字段为必填字段。
- 选择可以同意此作用域的用户。 默认选项为 “仅限管理员”。
- 输入管理员同意显示名称。 此字段为必填字段。
- 输入管理员同意的说明。 此字段为必填字段。
- 输入 用户同意显示名称。
- 输入用户同意描述的说明。
- 在 State 字段中,为 state 选择 Enabled 选项。
- 选择 “添加范围”。
为要预授权的应用程序创建授权的客户端 ID。 这允许应用用户访问你配置的应用范围 (权限) ,而无需额外的同意。 由于应用用户没有机会拒绝同意,因此请仅预授权您信任的客户端应用程序。
在 Microsoft Entra 管理中心的“授权的客户端应用程序”部分中,选择“+ 添加客户端应用程序”。
输入要授权的应用程序的 Microsoft 365 客户端 ID。
实现令牌检索和验证逻辑
添加代码以处理访问令牌,在授权标头中将令牌发送到应用的服务器代码,并在收到访问令牌时进行验证。
若要获取当前应用用户的应用访问权限,客户端代码必须调用 Teams 以获取访问令牌。 更新客户端代码以用于 getAuthToken() 启动验证过程,如以下示例所示。
// Get auth token
// Ask Teams to get us a token from AAD
function getClientSideToken() {
return new Promise((resolve, reject) => {
display("1. Get auth token from Microsoft Teams");
microsoftTeams.authentication.getAuthToken().then((result) => {
display(result);
resolve(result);
}).catch((error) => {
reject("Error getting token: " + error);
});
});
}
当 Teams 收到访问令牌时,它会缓存要根据需要重复使用的令牌。 在调用时使用getAuthToken()令牌,而无需再次调用 Microsoft Entra ID,直到令牌过期。
用户同意对话框
当你呼叫getAuthToken()并且用户级权限需要用户同意时,登录用户会看到一个 Microsoft Entra 对话框,用户必须给予一次初始许可。
用户同意后,他们可以访问对话框网页。 以下几点适用于用户同意:
- 如果管理员代表租户授予同意,则无需提示应用用户同意。 这意味着应用用户看不到“同意”对话框,可以无缝访问应用。
- 如果 Microsoft Entra 应用注册在你在 Teams 中请求身份验证的同一租户中,则无法要求应用用户同意,而是会立即向应用用户授予访问令牌。 仅当 Microsoft Entra 应用在其他租户中注册时,应用用户才同意这些权限。
- 由于用户必须提供 API 访问许可,并且每个用户只需同意一次,因此对话框不需要其他许可。
更新应用清单
在应用清单文件中配置 webApplicationInfo 属性以启用 SSO。 这有助于代理用户无缝访问您的代理。 下表列出了 webApplicationInfo 属性的属性。
| 属性 | 说明 |
|---|---|
| id | 输入在 Microsoft Entra ID 中创建的应用 ID (GUID) 。 |
| 资源 | 输入应用的子域 URI 和创建范围时在 Microsoft Entra ID 中创建的应用程序 ID URI。 |
"webApplicationInfo": {
"id": "7c7c79df-bf9d-43b7-a464-1cb9995eb3b2",
"resource": "api://67ec-4-213-76-42.ngrok-free.app/7c7c79df-bf9d-43b7-a464-1cb9995eb3b2"
}
在应用清单的 validDomains 属性的对话框中指定要呈现的 URL 的域,如以下示例所示。
"validDomains": [
"contoso.com",
"mysite.someplace.com",
"othersite.someplace.com"
]
OAuth 2.0 安装程序 (预览)
对于将 OAuth 2.0 与 Microsoft Entra ID 或其他标识提供者配合使用的代理,请使用 authentication.authenticate() TeamsJS 库中的函数启动身份验证流。
若要为 API 插件对话框启用 OAuth 2.0 授权,请执行以下操作:
- 将应用配置为使用 Microsoft Entra ID 作为标识提供者。
- 更改代码以启动身份验证流并处理令牌。
将应用配置为使用 Microsoft Entra ID 作为标识提供程序
若要将应用配置为使用 Microsoft Entra ID,请执行以下操作:
- 在 Azure 门户中,转到应用注册。
- 在 “身份验证”下的 “重定向 URI ”部分中,将重定向 URL 添加到身份验证终结点。 使用以下格式的重定向 URL:
https://<hostname>/auth/simple-start.
启动身份验证流并处理令牌
大多数标识提供者不允许将内容放置在 iframe 中。 这意味着需要一个页面来托管 Copilot 在弹出窗口中显示的标识提供程序。
authentication.authenticate()选择自适应卡片按钮时,使用 TeamsJS 库的功能启动此页面。
注意
传递到 authenticate() 的 URL 是身份验证流的起始页。 它应该与你在 Azure 门户中注册的内容匹配。
身份验证流必须从您域中的页面开始。 请务必在清单的 validDomains 属性中列出此域。
import { authentication } from "@microsoft/teams-js";
authentication.authenticate({
url: window.location.origin + "/auth/simple-start",
width: 600,
height: 535
})
.then((result) => {
console.log("Login succeeded: " + result);
let data = localStorage.getItem(result);
localStorage.removeItem(result);
let tokenResult = JSON.parse(data);
showIdTokenAndClaims(tokenResult.idToken);
getUserProfile(tokenResult.accessToken);
})
.catch((reason) => {
console.log("Login failed: " + reason);
handleAuthError(reason);
});
弹出页面将重定向到身份提供程序,以便用户可以登录。 代理调用 Microsoft Entra 授权服务并传入用户和应用信息,以便用户可以向 Entra ID 进行身份验证。 然后,Entra ID 调用您提供的回调页面。
app.getContext().then((context) => {
// Generate random state string and store it, so we can verify it in the callback
let state = _guid(); // _guid() is a helper function in the sample
localStorage.setItem("simple.state", state);
localStorage.removeItem("simple.error");
// Go to the Azure AD authorization endpoint
let queryParams = {
client_id: "{{appId}}",
response_type: "id_token token",
response_mode: "fragment",
scope: "https://graph.microsoft.com/User.Read openid",
redirect_uri: window.location.origin + "/auth/simple-end",
nonce: _guid(),
state: state,
// The context object is populated by Teams; the loginHint attribute
// is used as hinting information
login_hint: context.user.loginHint,
};
let authorizeEndpoint = `https://login.microsoftonline.com/${context.user.tenant.id}/oauth2/v2.0/authorize?${toQueryString(queryParams)}`;
window.location.assign(authorizeEndpoint);
});
根据 Entra ID 返回的信息确定身份验证请求的成功或失败,并调用 authentication.notifySuccess() 或 authentication.notifyFailure()。 如果登录成功,则用户有权访问服务资源。