向自适应卡片模板添加对话框 (预览)

可以通过添加模式对话框来增强智能 智能 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:

  1. 更新 Microsoft Entra ID 应用程序。
    • 配置应用程序 ID URI。
    • 配置范围和同意设置。
    • 对受信任的客户端应用程序进行预授权,以避免重复的同意提示。
  2. 实现令牌检索和验证逻辑。
    • 使用 TeamsJS 库中的方法 getAuthToken() 检索访问令牌。
    • 在授权标头中将令牌发送到服务器。
    • 在服务器端验证令牌。
  3. 更新应用清单。
    • 将 webApplicationInfo 属性添加到应用清单以启用 SSO。
    • 将对话框内容的域添加到应用清单的“validDomains ”属性中。

更新 Microsoft Entra ID 应用程序

若要配置范围并授权受信任的客户端应用程序,请按如下所示更新 Microsoft Entra ID 应用程序:

  1. 将 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"
    ],
    
  2. 定义 API 的范围以及谁可以同意该范围。 在 Microsoft Entra 管理中心的“此 API 定义的范围”部分中,选择“+ 添加范围”。

    用于添加范围的字段的屏幕截图

    1. 输入作用域名称。 此字段为必填字段。
    2. 选择可以同意此作用域的用户。 默认选项为 “仅限管理员”。
    3. 输入管理员同意显示名称。 此字段为必填字段。
    4. 输入管理员同意的说明。 此字段为必填字段。
    5. 输入 用户同意显示名称。
    6. 输入用户同意描述的说明。
    7. 在 State 字段中,为 state 选择 Enabled 选项。
    8. 选择 “添加范围”。
  3. 为要预授权的应用程序创建授权的客户端 ID。 这允许应用用户访问你配置的应用范围 (权限) ,而无需额外的同意。 由于应用用户没有机会拒绝同意,因此请仅预授权您信任的客户端应用程序。

    1. 在 Microsoft Entra 管理中心的“授权的客户端应用程序”部分中,选择“+ 添加客户端应用程序”。

      突出显示“添加客户端应用程序”按钮的屏幕截图

    2. 输入要授权的应用程序的 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()。 如果登录成功,则用户有权访问服务资源。