Skip to main content

Product Teams Integration Guide

This document aims to guide users on integrating the SERVICEME NEXT product into the Microsoft Teams application to achieve unified access and collaborative use within the Teams environment.

Prerequisites​

For security and compliance reasons, SERVICEME NEXT distinguishes login methods when integrating with Teams applications:

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

These two login methods must use different Azure Entra applications (App Registrations).

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

Configuration Instructions​

1. Add Teams configuration information in SSO_LOGIN_CONFIG​

The Teams configuration information must be consistent with the webApplicationInfo content 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 within 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:

  • 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).
The id and resource must correspond to the Azure Entra application's Client ID and Application ID URI.

"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 product deployment domain;
  • The following two IDs must be added in "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 you need to customize customer brand icons, you can replace the corresponding image files.

5. developer (Optional)​

"developer": {
  "name": "Medalsoft (SoftwareOne subsidiary)",
  "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 corporate 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, choose Upload a custom app or Submit an app to your organization:

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

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

Frequently Asked Questions (Q&A)​

Issue: "Refused to frame" error after integration​

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

Solution: Configure the following environment variable in the Docker environment where the frontend mirror is running:

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;

Among them:

  • frame-ancestors 'self' https://teams.microsoft.com means allowing embedding from Teams pages.

Reference documents: