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 distinguishes between login methods when integrating with the Teams application:

  • Azure Entra ID (AAD) Single Sign-On on the login page;
  • Teams integration login.

These two login methods require 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"
  }
]

Teams Application Integration Overview​

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 documentation: App manifest schema.

manifest.json Configuration Instructions​

1. staticTabs.contentUrl and validDomains (Required)​

This configuration defines the embedded page address in Teams and the allowed domains. Please replace 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/, configure as follows:

  • 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;
  • In "Authorized client applications", add the following two IDs:
    • 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 you need to customize the customer's brand icon, you can replace the corresponding image files.

5. developer (Optional)​

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

Customers can modify the developer name and related links according to their company information.

6. localizationInfo (Optional)​

To support multiple languages, you can specify language pack files 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" }
  ]
}

Uploading the Application to Teams​

In Teams, select Upload a custom app or Submit an app to your org:

  • Upload a custom app: Only visible to individuals, suitable for testing and debugging;
  • Submit an app to your org: Requires admin approval. Once approved, it can be accessed under the "Built for your org" section.

It is recommended to test first in the Teams Web client, where you can view log information via the browser console (F12).

Frequently Asked Questions (Q&A)​

Question: "Refused to frame" error occurs after integration​

Reason: For security, the product disables embedding pages from external sites by default.

Solution: In the Docker environment variables for the frontend image startup, configure the following item:

Key:

SML_CONTENT_SECURITY_POLICY

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 means allowing embedding of the product from Teams pages.

Reference Documents: