This guide explains how to integrate the jtel Portal into Microsoft Teams as a custom application.

The integration supports two configurations:

1. jtel Portal in Microsoft Teams: Open and use the jtel Portal directly inside a Microsoft Teams tab with the standard Portal login.

2. Optional – Microsoft Entra ID SSO: Enable Microsoft authentication for the Portal integrated into Teams.

Microsoft Entra ID configuration is not required for the basic Teams tab integration.

Part 1 – Integrate jtel Portal into Microsoft Teams

1. Prerequisites

Before creating the Teams application, ensure that:

• The jtel Portal is accessible via HTTPS.

• You have permission to upload custom applications to Microsoft Teams.

• You know the jtel Portal URL, including the Reseller and Client identifiers.

Example Portal URL:

https://acd.example.com/CarrierPortal/login/<reseller-uid>/<client-uid>

2. Create the Teams Application

A Microsoft Teams application package requires three files:

• manifest.json – Application configuration.

• Icon-color.png – Color icon (192 × 192 pixels).

• Icon-outline.png – Outline icon (32 × 32 pixels).

2.1 Configure manifest.json

Create a file named manifest.json with the following content:

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
  "manifestVersion": "1.16",
  "id": "<TEAMS-APP-ID>",
  "version": "1.0.0",
  "packageName": "de.jtel.acd.teams",
  "developer": {
    "name": "jtel GmbH",
    "websiteUrl": "https://jtel.de/",
    "privacyUrl": "https://jtel.de/privacy-statement-eu/",
    "termsOfUseUrl": "https://jtel.de/en/legal"
  },
  "name": {
    "short": "jtel ACD",
    "full": "jtel ACD Client Tab"
  },
  "description": {
    "short": "jtel ACD Teams Client",
    "full": "Access the jtel Portal directly within Microsoft Teams."
  },
  "icons": {
    "outline": "Icon-outline.png",
    "color": "Icon-color.png"
  },
  "accentColor": "#333333",
  "staticTabs": [
    {
      "entityId": "jtelACD",
      "name": "jtel ACD",
      "contentUrl": "https://acd.example.com/CarrierPortal/login/<reseller-uid>/<client-uid>",
      "websiteUrl": "https://acd.example.com/CarrierPortal/login/<reseller-uid>/<client-uid>",
      "scopes": ["personal"]
    }
  ],
  "validDomains": [
    "acd.example.com"
  ]
}

Replace the following placeholders:

2.2 Create the Application Package

1. Place manifest.json, Icon-color.png, and Icon-outline.png in the same folder.

2. Compress the three files into a ZIP archive.

The ZIP file must contain the three files directly at its root, without an additional parent folder.

ZIP Example:

jtelACDTeamsTab.zip

3. Upload the Application to Microsoft Teams

1. Open the Microsoft Teams admin center.

2. Navigate to Teams apps → Manage apps.

3. Click Upload new app under Actions.

4. Upload the ZIP package.

5. Verify that the application appears as jtel ACD.

Optional – Install and Pin the Application

An administrator can configure the application to be installed and pinned for selected users or for the organization.

Depending on the Microsoft Teams configuration, this is managed through app setup policies or app-centric management.

4. Test the Teams Integration

1. Open Microsoft Teams.

2. Find and open the jtel ACD application.

3. Verify that the jtel Portal is displayed inside the Teams tab.

4. Log in using your normal jtel Portal credentials.

The jtel Portal should now be accessible directly inside Microsoft Teams.

Note: If you want to enable Microsoft Entra ID login for the integrated Portal, continue with Part 2.

Part 2 – Optional: Microsoft Entra ID SSO

This section explains how to enable Microsoft Entra ID Single Sign-On (SSO) for the jtel Portal integrated into Microsoft Teams.

This configuration is optional and can be skipped if users should continue using the standard jtel Portal login.

5. Configure Microsoft Entra ID

First, configure Microsoft Entra ID login for the jtel Portal as described in:

Microsoft Entra ID Login Configuration

Ensure that Microsoft login works in the browser before proceeding.

5.1 Configure the Access Token Version

1. Open the Microsoft Entra admin center.

2. Navigate to Entra ID → App registrations.

3. Select the application used for the jtel Portal.

4. Under Manage, select Manifest.

5. Locate requestedAccessTokenVersion inside the api object.

6. Change its value from null (or 1) to 2 and Save the changes.:

"api": {
  "requestedAccessTokenVersion": 2
}

Important: Modify only the requestedAccessTokenVersion property in the existing api object. Do not remove other properties or permissions.

The setting belongs to the Microsoft Entra application manifest, not the Microsoft Teams manifest.json file.

5.2 Expose an API

1. Open the Microsoft Entra application registration used for the jtel Portal.

2. Navigate to Expose an API.

3. Next to Application ID URI, click Set.

4. Configure the following Application ID URI: api://<portal-domain>/<APPLICATION-CLIENT-ID> Example: api://acd.example.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

5. Save the URI.

6. Click Add a scope and configure:

The resulting scope has the format: api://<portal-domain>/<APPLICATION-CLIENT-ID>/access_as_user

Important:

• <APPLICATION-CLIENT-ID> is the Application (client) ID, not the Directory (tenant) ID.

• The Application ID URI must match the webApplicationInfo.resource value in the Teams application manifest.

• The Portal domain must match the domain hosting the Teams tab.

• If Microsoft Entra ID rejects the custom Application ID URI, verify that requestedAccessTokenVersion is set to 2.

5.3 Authorize Client Applications

Navigate to Expose an API → Authorized client applications.

Click Add a client application and configure the following client IDs.

For each application:

1. Enter the corresponding Client ID.

2. Select the access_as_user scope.

3. Click Add application.

6. Update the Teams Application Manifest

Open the manifest.json file created in Part 1.

Add the following two properties:

"permissions": [
  "identity"
],
"webApplicationInfo": {
  "id": "<APPLICATION-CLIENT-ID>",
  "resource": "api://acd.example.com/<APPLICATION-CLIENT-ID>"
}

Replace <APPLICATION-CLIENT-ID> with the Application (client) ID from Microsoft Entra ID and acd.example.com with the jtel Portal domain.

6.1 Complete manifest.json Example with SSO

The following example shows the Teams application manifest with Microsoft Entra ID SSO configuration:

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
  "manifestVersion": "1.16",
  "id": "<TEAMS-APP-ID>",
  "version": "1.0.1",
  "packageName": "de.jtel.acd.teams",
  "developer": {
    "name": "jtel GmbH",
    "websiteUrl": "https://jtel.de/",
    "privacyUrl": "https://jtel.de/privacy-statement-eu/",
    "termsOfUseUrl": "https://jtel.de/en/legal"
  },
  "name": {
    "short": "jtel ACD",
    "full": "jtel ACD Client Tab"
  },
  "description": {
    "short": "jtel ACD Teams Client",
    "full": "Access the jtel Portal directly within Microsoft Teams."
  },
  "icons": {
    "outline": "Icon-outline.png",
    "color": "Icon-color.png"
  },
  "accentColor": "#333333",
  "staticTabs": [
    {
      "entityId": "jtelACD",
      "name": "jtel ACD",
      "contentUrl": "https://acd.example.com/CarrierPortal/login/<reseller-uid>/<client-uid>",
      "websiteUrl": "https://acd.example.com/CarrierPortal/login/<reseller-uid>/<client-uid>",
      "scopes": ["personal"]
    }
  ],
  "permissions": [
    "identity"
  ],
  "webApplicationInfo": {
    "id": "<APPLICATION-CLIENT-ID>",
    "resource": "api://acd.example.com/<APPLICATION-CLIENT-ID>"
  },
  "validDomains": [
    "acd.example.com"
  ]
}

Important:

• <TEAMS-APP-ID> is the unique ID of the Microsoft Teams application.

• <APPLICATION-CLIENT-ID> is the Application (client) ID from Microsoft Entra ID.

• These are two different identifiers.

• webApplicationInfo.resource must exactly match the Application ID URI configured under Expose an API.

• The Portal URL in contentUrl remains unchanged when enabling SSO.

If updating an existing Teams application, keep its Teams App ID unchanged and increase the manifest version, for example from 1.0.0 to 1.0.1.

Create a new ZIP package and upload it as a new version of the existing Teams application.

7. Test Microsoft Entra ID Login in Teams

1. Open Microsoft Teams.

2. Open the jtel ACD application.

3. Verify that the jtel Portal loads correctly.

4. Click the Microsoft Entra ID login button if authentication is not started automatically.

5. Verify that Microsoft Entra ID authentication succeeds inside Teams.

6. After successful authentication, verify that the correct jtel Portal user account is opened.

If multiple jtel Portal users have the same email address configured, a user selection page may appear after authentication.

Note: Changes to the Microsoft Entra ID configuration or Teams application manifest may not take effect immediately. If authentication fails despite matching configuration, reload Microsoft Teams and allow time for changes to propagate before making additional changes.

8. Updating the Teams Application

To update the existing Teams application:

1. Modify manifest.json or the application icons if necessary.

2. Keep the existing Teams App ID unchanged.

3. Increase the version number, for example from 1.0.1 to 1.0.2.

4. Create a new ZIP package.

5. Open Teams admin center → Teams apps → Manage apps.

6. Select the existing jtel application and upload the new version.

Changes may not be visible immediately in all Teams clients.

9. Troubleshooting