Skip to main content

Product Teams Integration Guide

This document is intended to guide users in integrating the SERVICEME NEXT product into the Microsoft Teams application, enabling unified access and collaborative use within the Teams environment.

Prerequisites​

For security and compliance reasons, SERVICEME NEXT requires distinguishing between login methods when integrating with the Teams application:

  • Azure Entra ID (AAD) single sign-on on the login page;
  • Teams integrated login.

The above two login methods must use different Azure Entra applications (App Registration).

Before integration, please ensure that the Teams-related information has been configured on the product's environment variable (env) management page.

Configuration Instructions​

1. Add Teams configuration information in SSO_LOGIN_CONFIG​

The Teams configuration information must be consistent with the content of webApplicationInfo in the manifest.json file.

[
  {
    "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. Add login handler configuration in SSO_LOGIN_SECRET​

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

Overview of Teams Application Integration​

The essence of Teams integration is to package the application's definition files (manifest.json and related resources) into a ZIP file and upload it to the Teams platform.

Official Teams reference documentation: App manifest schema.

manifest.json Configuration Instructions​

1. staticTabs.contentUrl and validDomains (required)​

This configuration defines the embedded page URL in Teams and the allowed domains for access. Please replace them according to the customer's deployment environment.

"staticTabs": [
  {
    "entityId": "entry",
    "name": "SERVICEME",
    "contentUrl": "https://customer deployment path/login-teams-redirect",
    "scopes": ["personal"]
  }
],
"validDomains": [
  "customer deployment domain"
]

For example, if the deployment path is https://customer.domain.com/next/, it should be configured as:

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

2. webApplicationInfo (required)​

This item is used to configure Teams single sign-on (SSO).
id and resource must correspond to the Client ID and Application ID URI of the Azure Entra application.

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

Configuration requirements:

  • The Application ID URL must include the domain name of the product deployment;
  • The following two IDs must be added under “Authorized client applications”:
    • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346
    • 1fec8e78-bce4-4aaf-ab1b-5451cc387264

Related references:

3. name (optional)​

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

4. icons (optional)​

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

If customer brand icons need to be customized, the corresponding image files can be replaced.

5. developer (optional)​

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

Customers may modify the developer name and related links according to their enterprise information.

6. localizationInfo (optional)​

If multilingual support is required, the language pack files can be specified through the localizationInfo field.

"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" }
  ]
}

Upload the Application to Teams​

In Teams, choose Upload a custom app or Submit an app to your organization:

  • Upload a custom app: visible only to individuals, suitable for testing and debugging;
  • Submit an app to your organization: requires administrator approval, and after approval, it can be accessed in the “Built for your org” section.

It is recommended to prioritize testing on the Teams Web client, where log information can be viewed through the browser console (F12).

Frequently Asked Questions (Q&A)​

Question: After integration, the error “Refused to frame” appears​

Cause: To ensure security, the product disables embedding pages in external sites by default.

Solution: Configure the following item in the Docker environment variables when starting the frontend image:

Key name:

SML_CONTENT_SECURITY_POLICY

Key value:

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;

Where:

  • frame-ancestors 'self' https://teams.microsoft.com indicates that embedding the product from Teams pages is allowed.

Reference documents: