跳到主要内容

产品 Teams 集成指南

本文档旨在指导用户将 SERVICEME NEXT 产品集成至 Microsoft Teams 应用中，以实现 Teams 环境下的统一访问与协同使用。

前置要求​

出于安全合规考虑，SERVICEME NEXT 在集成 Teams 应用时，需区分登录方式：

  • 登录页的 Azure Entra ID（AAD）单点登录；
  • Teams 集成登录。

上述两种登录需使用 不同的 Azure Entra 应用（App Registration）。

在集成前，请确保已在产品的 环境变量（env）管理页面 中完成 Teams 相关信息配置。

配置说明​

1. 在 SSO_LOGIN_CONFIG 中添加 Teams 配置信息​

Teams 配置信息需与 manifest.json 文件中 webApplicationInfo 的内容保持一致。

[
  {
    "code": "azure",
    "type": "Azure",
    "config": {
      "AZURE_AD_APP_ID": "api://35a1057c-69a3-4042-a0fa-xxxxxxxxxxxx",
      "AZURE_AD_TENANTID": "9ea41729-4be8-4b02-a8d3-xxxxxxxxxxxx",
      "AZURE_AD_SCOPE": "api://35a1057c-69a3-4042-a0fa-xxxxxxxxxxxx/default",
      "AZURE_CLIENT_ID": "35a1057c-69a3-4042-a0fa-xxxxxxxxxxxx"
    }
  },
  {
    "code": "teams",
    "type": "Azure",
    "hide": true,
    "config": {
      "AZURE_AD_APP_ID": "api://xxxx.serviceme.com/312732ff-fad9-47e7-b247-xxxxxxxxxxxx",
      "AZURE_AD_TENANTID": "9ea41729-4be8-4b02-a8d3-xxxxxxxxxxxx",
      "AZURE_AD_SCOPE": "api://xxxx.serviceme.com/312732ff-fad9-47e7-b247-xxxxxxxxxxxx/default",
      "AZURE_CLIENT_ID": "312732ff-fad9-47e7-b247-xxxxxxxxxxxx"
    }
  }
]

2. 在 SSO_LOGIN_SECRET 中添加登录处理配置​

[
  {
    "code": "azure",
    "handler": "serviceme.foundation.services.auth.sso.azure.AzureUserInfoProvider"
  },
  {
    "code": "teams",
    "handler": "serviceme.foundation.services.auth.sso.azure.AzureUserInfoProvider"
  }
]

Teams 应用集成概述​

Teams 集成的本质是将应用的定义文件（manifest.json 及相关资源）打包成一个 ZIP 文件 上传至 Teams 平台。

Teams 官方参考文档：App manifest schema。

manifest.json 配置说明​

1. staticTabs.contentUrl 与 validDomains（必填）​

此配置定义 Teams 内嵌页面地址与允许访问的域名。请根据客户部署环境进行替换。

"staticTabs": [
  {
    "entityId": "entry",
    "name": "SERVICEME",
    "contentUrl": "https://客户部署路径/login-teams-redirect",
    "scopes": ["personal"]
  }
],
"validDomains": [
  "客户部署域名"
]

例如部署路径为 https://customer.domain.com/next/，则应配置为：

  • contentUrl: https://customer.domain.com/next/login-teams-redirect
  • validDomains: customer.domain.com

2. webApplicationInfo（必填）​

此项用于配置 Teams 的单点登录（SSO）。
id 与 resource 需对应 Azure Entra 应用的 Client ID 与 应用程序 ID URI。

"webApplicationInfo": {
  "id": "312732ff-fad9-47e7-b247-xxxxxxxxxxxx",
  "resource": "api://dev.next.serviceme.com/312732ff-fad9-47e7-b247-xxxxxxxxxxxx"
}

配置要求：

  • 应用程序 ID URL 中需包含产品部署的域名；
  • 在 “授权客户端应用程序” 中需添加以下两个 ID：
    • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346
    • 1fec8e78-bce4-4aaf-ab1b-5451cc387264

相关参考：

3. name（可选）​

"name": {
  "short": "SERVICEME",
  "full": "SERVICEME NEXT for Teams"
}

4. icons（可选）​

"icons": {
  "outline": "icon-outline.png",
  "color": "icon-color.png"
}

如需定制客户品牌图标，可替换相应图片文件。

5. developer（可选）​

"developer": {
  "name": "Medalsoft",
  "mpnId": "14659343",
  "websiteUrl": "https://www.medalsoft.com/",
  "privacyUrl": "https://www.serviceme.com/",
  "termsOfUseUrl": "https://www.serviceme.com/"
}

客户可根据企业信息修改开发者名称与相关链接。

6. localizationInfo（可选）​

如需支持多语言，可通过 localizationInfo 字段指定语言包文件。

"localizationInfo": {
  "defaultLanguageTag": "en",
  "additionalLanguages": [
    { "languageTag": "en", "file": "locale-en.json" },
    { "languageTag": "zh-cn", "file": "locale-zh-cn.json" },
    { "languageTag": "ja-jp", "file": "locale-ja-jp.json" }
  ]
}

上传应用至 Teams​

在 Teams 中选择 上传自定义应用 或 向组织提交应用：

  • 上传自定义应用：仅个人可见，适用于测试与调试；
  • 向组织提交应用：需管理员审批，审批通过后可在 “专为组织构建” 栏目中访问。

建议优先在 Teams Web 端 进行测试，可通过浏览器控制台（F12）查看日志信息。

常见问题（Q&A）​

问题：集成后出现 “页面拒绝服务（Refused to frame）” 报错​

原因：为保证安全，产品默认禁用外部站点嵌入页面。

解决方法：在前端镜像启动的 Docker 环境变量中，配置以下项：

键名：

SML_CONTENT_SECURITY_POLICY

键值：

default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' https://*.microsoftonline.com ws: wss: blob:; media-src 'self' blob:; object-src 'none'; child-src 'self'; frame-ancestors 'self' https://teams.microsoft.com;

其中：

  • frame-ancestors 'self' https://teams.microsoft.com 表示允许来自 Teams 页面嵌入产品。

参考文档：