Setting up Microsoft Teams integration

Setting up Microsoft Teams integration

Use this guide to set up the Microsoft Teams integration for a Totara site.

To use Totara in Microsoft Teams, you need to create your own Microsoft Teams app, configure the required Microsoft Entra ID settings, configure the Microsoft Teams integration settings in Totara, then upload the generated app manifest to Microsoft Teams.

Before you start

You will need access to

Requirement

Needed for

Requirement

Needed for

Totara Site Administrator access

Configuring the Microsoft Teams integration and downloading the app manifest

Microsoft Teams admin centre access

Allowing third-party or custom apps and uploading the generated app package

Microsoft Entra ID permissions to register applications

Creating the app registration used by Totara and Teams

Azure subscription

Required only if you want to use the conversational bot, messaging extension, or Teams notifications

HTTPS Totara site URL

Required for Teams, SSO, redirects, bot endpoints, privacy URLs, and manifest validation

Privacy policy and terms of use URLs

Recommended for the Teams app listing and Microsoft app configuration

Decide which features you need

The setup steps depend on which Teams features you want to enable.

Feature

Required?

What it provides

Extra setup required

Feature

Required?

What it provides

Extra setup required

Teams app / tabs

Yes

Allows users to access Totara from Microsoft Teams

Microsoft Entra app registration, Totara integration settings, Teams manifest upload

Single sign-on

Optional

Allows users to access Totara in Teams using their Microsoft Entra IDentity

Microsoft Entra authentication settings, API scope, Graph delegated permissions, Totara OAuth 2 configuration

Conversational bot

Optional

Enables bot-based Teams features (notifications, and messaging extension - see below)

Azure Bot resource, bot endpoint, Teams channel

Messaging extension

Optional

Allows users to search or share Totara content from Teams

Conversational bot setup

Teams notifications

Optional

Sends Totara notifications to Microsoft Teams

Conversational bot setup and Teams notifications enabled in Totara message outputs

Goal

Required steps

Goal

Required steps

Basic Teams app only

Steps 1, 2, 4, 5

Teams app with SSO

Steps 1, 2, 2a, 4, 5

Messaging extension / notifications

Steps 1, 2, 3, 4, 5

SSO + bot features

All steps

Sites and domains

Important: Totara must be available over HTTPS. Some Microsoft Teams and Microsoft Entra URLs, including privacy policy, redirect, SSO, and bot URLs, may fail if HTTP is used.

When configuring the Microsoft Teams integration, it is important to understand the difference between a domain and a site URL.

A Totara site can be installed in a subfolder on a domain.

Example:

Type

Example

Type

Example

Domain

www.totarasite.com

Totara site URL

https://www.totarasite.com/learn

Use the site URL when configuring URLs that point to Totara pages or endpoints, for example redirect URLs, logout URLs, and the bot messaging endpoint.

Use the domain when configuring the Microsoft Entra API scope, for example:

api://www.totarasite.com/[Application client ID]

Microsoft’s Teams SSO documentation requires the Application ID URI to use the fully qualified domain name for the app, followed by the app ID.


Setup guide

Step 1: Prepare the Microsoft Teams tenant

You can find out more about preparing your Microsoft 365 tenant in Microsoft's documentation or sign up for a Microsoft Teams account.

  1. Sign in to the Microsoft Teams admin centre admin.teams.microsoft.com.

  2. Go to: Teams apps > Manage apps

  3. Open: Actions > Org-wide app settings

  4. Check that your tenant allows the app type you are configuring. Depending on your tenant configuration, this may include allowing third-party apps, allowing custom apps, and allowing the relevant admins or users to upload custom apps.

    1. For most instances, checking “Allow third-party app” will suffice.

  5. Save your changes.

Accessing Manage apps in the Microsoft Teams admin dashboard.
Accessing Manage apps in the Microsoft Teams admin dashboard.

Step 2: Create an app registration in Microsoft Entra ID

  • Microsoft Entra ID was previously known as Azure Active Directory.

  • Microsoft recommends single-tenant app registrations for most internal organisation apps. For this Totara integration, use a single-tenant app unless you have a specific reason to support multiple Microsoft Entra tenants. Microsoft describes single-tenant apps as apps available only in the tenant where they are registered, while multitenant apps can be used across other Microsoft Entra tenants.

Register the app

  1. Sign in to the Azure portal https://portal.azure.com/.

  2. Go to App registrations

    1. Navigate to App registrations by locating it under Manage > App registrations in the left navigation blade within the tenant; by searching 'app registrations' from the search bar, or by navigating to More services > All services.

  3. Select New registration.

  4. Enter a name for the app.

    Example:

    Totara Microsoft Teams
  5. Under Supported account types, select:

    Accounts in this organizational directory only

    This is the recommended option for a customer-owned internal Teams app.

There are four choices for Supported account types supported with Totara:

  • Accounts in this organizational directory only (TENANTNAME only - Single tenant): This is the recommended choice for this integration and is required for configuring a bot

  • Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant)

  • Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox): Users can also log in using their personal accounts

  • Personal Microsoft accounts only: Users can only log in using their personal account (e.g. @hotmail.co.uk)

Please note that the options including personal Microsoft accounts any personal accounts must be external users of your Microsoft Entra ID tenant. For more information please refer to Microsoft's documentation.

  1. Select Register.

  2. On the app overview page, copy and save the following values:

Value

Where it is used later

Value

Where it is used later

Application (client) ID

Totara Microsoft Teams integration settings.

Microsoft also recommends recording the Application (client) ID after registration because it uniquely identifies the application.

Directory (tenant) ID

Totara Microsoft Teams integration settings.

Complete the branding information

  1. In the app registration, go to the branding or properties area and complete the app information.

  2. Use values that match the Teams app you want users to see.

Field

Suggested value

Field

Suggested value

Name

The name of your Teams app

Logo

The same logo you plan to use in Totara’s Microsoft Teams settings

Home page URL

Your Totara site URL

Terms of service URL

Your organisation’s terms of use URL

Privacy statement URL

Your organisation’s privacy policy URL

  1. Save your changes.

Step 2a [Optional] - Configure Microsoft Single Sign-On

Complete this section only if you want users to sign in to Totara in Microsoft Teams using Microsoft single sign-on.

For additional information please see Microsoft's documentation.

If you select Personal Microsoft accounts only, or Accounts in any organizational directory and personal Microsoft accounts, Microsoft says to update the requestedAccessTokenVersion property in the app registration manifest to 2. See https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/tab-sso-register-aad#configure-access-token-version for more information.

This is not required for the recommended single-tenant option.

Teams SSO allows users who are already signed in to Teams with a Microsoft or Microsoft 365 account to access the app without signing in again, provided the app has been configured correctly in Microsoft Entra ID.

Add authentication URLs

  1. In the Microsoft Entra app registration, go to: Authentication

  2. Select Add a platform.

  3. Select Web.

  4. Add the redirect URI:

    https://[your.totara.site.url]/admin/oauth2callback.php

    If your Totara installation uses a different admin folder name, replace admin with your actual folder name.

  5. Add the logout URL:

    https://[your.totara.site.url]/totara/msteams/sso_logout.php
  6. Save your changes.

  7. Add another redirect URI:

    https://[your.totara.site.url]/totara/msteams/oidc_login.php
  8. Save your changes again.

Expose an API

  1. In the Microsoft Entra app registration, go to: Expose an API

  2. Select Add next to Application ID URI.

  3. Enter the Application ID URI in this format:

    api://[your.totara.domain]/[Application client ID]

    Example:

    api://www.totarasite.com/00000000-0000-0000-0000-000000000000

Important: Use the domain, not the full Totara site URL. For example, use www.totarasite.com, not www.totarasite.com/learn.

If Microsoft Entra ID displays an error when you enter the Application ID URI, open the app registration manifest and edit the value directly.

image-20260429-022213.png
  1. Save your changes.

Add the access scope

  1. In Expose an API, select Add a scope.

  2. Enter the following values:

Field

Value

Field

Value

Scope name

access_as_user

Who can consent

Admins and users

Admin consent display name

Teams can access the user's profile

Admin consent description

Allows Teams to call the app's web APIs as the current user.

User consent display name

Teams can access your user profile and make requests on your behalf

User consent description

Enable Teams to call this app's APIs with the same rights that you have.

State

Enabled

  1. Select Add scope.

Add authorised Teams client applications

In Expose an API, add the Teams client applications that are allowed to use this scope.

Add the following client IDs:

Teams client

Client ID

Teams client

Client ID

Teams desktop/mobile client

1fec8e78-bce4-4aaf-ab1b-5451cc387264

Teams web client

5e3ce6c0-2b1f-4285-8d4b-75ee78787346

Add Microsoft Graph delegated permissions

  1. In the app, go to: API permissions

  2. Select: Add a permission > Microsoft Graph > Delegated permissions

  3. Add the following permissions:

    email offline_access openid profile User.Read
  4. Save your changes.

  5. Select: Grant admin consent for [tenant name]

  6. Confirm the consent prompt.

Create a client secret

  1. Go to: Certificates & secrets

  2. Select New client secret.

  3. Enter a description.

  4. Choose an expiry period that matches your organisation’s security policy.

  5. Save the secret.

  6. Copy the Value (not ID) immediately.

Important: Microsoft only shows the client secret value once. Store it securely. You will need it when configuring the OAuth 2 service in Totara.


Step 3: Create an Azure Bot

Complete this section only if you want to use the messaging extension or Teams notifications.

The bot framework setup allows Teams to communicate with Totara through a bot endpoint.

Notifications for Microsoft Teams also need to be enabled in the message outputs.

Create the bot

  1. Sign in to the Azure portal https://portal.azure.com/ .

  2. Go to: Bot services

    Depending on your Azure portal layout, this may appear under Azure AI services, Applied AI services, or through search.

  3. Select Create.

  4. Choose Azure Bot.

  5. Complete the form.

Field

Value

Field

Value

Bot handle

A unique handle for your bot

Subscription

Your Azure subscription

Resource group

Select an existing group or create a new one

Location

Choose a region close to your Totara server

Pricing tier

Select the free F0 tier, if appropriate

Type of app

Single tenant

Creation type

Create new Microsoft App ID

  1. Select Review + create.

  2. Select Create.

  3. When deployment completes, select Go to resource.

Note: The bot handle is a unique identifier and cannot be changed after the bot is created.

Configure the bot profile

Optionally update the bot’s icon and display name.

Go to: Settings > Bot Profile

Update:

Field

Suggested value

Field

Suggested value

Icon

Your organisation or Totara app icon

Display name

The name users should see in Microsoft Teams

Configure the messaging endpoint

  1. Go to: Settings > Configuration

  2. Set the messaging endpoint to:

    https://[your.totara.site.url]/totara/msteams/botindex.php
  3. Select Apply.

The messaging endpoint is configured from the Azure Bot resource’s Configuration pane.

Enable the Microsoft Teams channel

  1. Go to: Settings > Channels

  2. Under Available channels, select Microsoft Teams.

  3. Read and accept the terms of service.

  4. Select the appropriate messaging environment.

    1. For most organisations this will be: Microsoft Teams Commercial

  5. Select Apply.

  6. Close the channel setup page.

Record the bot app ID and create a bot client secret

  1. In Azure, go to: App registrations

  2. Open the app registration created for the bot.

  3. Copy and save the Application (client) ID.

    You will use this as the Bot app ID in Totara.

  4. Go to: Certificates & secrets

  5. Delete any existing secret if required by your organisation’s process.

  6. Select New client secret.

  7. Enter a description.

  8. Choose an expiry period.

  9. Save the secret.

  10. Copy the Value immediately.

You will use this as the Client secret for Bot in Totara.


Step 4: Configure Microsoft Teams integration in Totara

Now configure the integration in your Totara site.

Configure OAuth 2 for SSO

Complete this subsection only if you are using Microsoft single sign-on.

  1. Sign in to Totara as a Site Administrator.

  2. Enable the OAuth 2 authentication plugin.

  3. Create a new Microsoft OAuth 2 service.

  4. Configure the service using the values from your Microsoft Entra app registration.

Totara setting

Value

Totara setting

Value

Client ID

Application (client) ID from the Microsoft Entra app registration

Client secret

Client secret value from the Microsoft Entra app registration

Require email verification

Choose according to your organisation’s authentication policy

  1. Select Configure endpoints for the Microsoft OAuth 2 service.

image-20260429-031137.png
  1. In your Microsoft Entra app registration, open your app registration and go to the Overview page.

  2. Select Endpoints.

image-20260429-031741.png
  1. Check that the endpoints configured in Totara match the Microsoft Entra endpoints.

  2. Save your changes in Totara.

Allow Totara to be embedded in Teams

Microsoft Teams displays the Totara app inside Teams, so Totara must allow frame embedding.

  1. In Totara, go to: Site administration > Security > HTTP security

  2. Enable: Allow frame embedding

  3. Save your changes.

Allow public catalogue images

Complete this subsection only if you want catalogue images to appear in the Teams messaging extension.

Microsoft requires images used in the messaging extension to be available by direct public URL.

  1. In Totara, go to: Quick-access menu > Security

  2. Enable: Allow public access to catalogue item pictures

  3. Save your changes.

Configure the Microsoft Teams integration settings

  1. In Totara, go to: Site administration > Microsoft Teams > Microsoft Teams integration

  2. Configure the required app settings.

Totara setting

Value

Totara setting

Value

Manifest app ID

Application (client) ID from the Microsoft Entra app registration

Package name

A unique package name in reverse-domain format, for example com.example.totara.msteams

Configure single sign-on settings

If you are using SSO, configure the following settings.

Totara setting

Value

Totara setting

Value

OAuth2 service

Microsoft

SSO app ID

Application (client) ID from the Microsoft Entra app registration

Resource scope

Application ID URI from Microsoft Entra ID, for example api://www.totarasite.com/[Application client ID]

If you are not using SSO, set the OAuth2 service to: None

Configure bot settings

Complete this subsection only if you created an Azure Bot.

Under Set up the conversational bot, configure the following settings.

Totara setting

Value

Totara setting

Value

Bot feature enabled

Enabled

Message extensions feature enabled

Enabled, if required

Bot app ID

Application (client) ID from the bot app registration

Client secret

Client secret value from the bot app registration

Bot tenant ID

Directory (tenant) ID from Microsoft

If you want to use Teams notifications, also enable the Microsoft Teams notification output in Totara message outputs.

Customise the app branding

Update the app branding so that users can recognise the app in Microsoft Teams.

Configure:

Setting

Description

Setting

Description

Short name

The main app name shown in Teams

Full name

Optional longer name, useful if the organisation name is more than 30 characters

Short description

A brief summary shown in the app catalogue

Full description

A more detailed description of the app and what users can do with it

Full colour icon

The app icon shown in the catalogue and app modals

Outline icon

The icon shown in the Teams side panel when the app is pinned

Accent colour

The background colour used behind transparent icons and on the sign-in card

Add publisher information

In the Publisher information section, add:

Field

Value

Field

Value

Publisher’s name

Your organisation name

Publisher’s website

Your organisation website

Privacy policy

Your organisation privacy policy URL

Terms of use

Your organisation terms of use URL

If privacy policy and terms of use fields are left blank, Totara will link to the equivalent pages on your Totara site.

Save the settings

Save the Microsoft Teams integration settings.

Saving the settings generates the Microsoft Teams app manifest package, which can then be downloaded from the Totara app installation page.


Step 5: Install the app in Microsoft Teams

  1. In Totara, go to: Site administration > Microsoft Teams > Totara app installation

  2. Confirm that each setup check has either passed or been skipped.

  3. Download the manifest file.

    This should download a .zip app package.

  4. Sign in to the Microsoft Teams admin centre.

  5. Go to: Teams apps > Manage apps

  6. Upload the app package.

    Depending on your Teams admin centre UI, select either: Upload new app or Actions > Upload new app

  7. Select the manifest .zip file downloaded from Totara.

  8. Confirm the upload.

If the manifest upload fails, validate the package with the Microsoft Teams app validator and check the troubleshooting section below.


Updating an existing Teams app

Changes can take time to appear for all users. Users may also need to restart Microsoft Teams.

Update the Teams app whenever you change app settings that affect the manifest, including:

  • App name

  • Description

  • Icons

  • Accent colour

  • Language packs or strings

  • SSO configuration

  • Bot configuration

  • Messaging extension settings

  • Any feature included in the Teams manifest

Update the manifest version

Before downloading a new manifest file, increase the app version number using semantic versioning.

Example:

1.0.0 -> 1.0.1

If Microsoft Teams says the app already exists when you upload the new package, increase the version number again, save the Totara settings, download a new manifest package, and re-upload it.

Upload the updated app package

  1. In Totara, save the updated Microsoft Teams integration settings.

  2. Go to:

    Site administration > Microsoft Teams > Totara app installation
  3. Download the updated manifest .zip file.

  4. In the Microsoft Teams admin centre, go to:

    Teams apps > Manage apps
  5. Search for your app.

  6. Open the app details page.

  7. Upload the updated manifest package.

If the updated app adds a new feature, such as enabling the bot when it was not previously enabled, users may see an upgrade banner on existing app tabs. An administrator may need to select Upgrade to apply the new app capabilities.


Troubleshooting

The Teams app package fails to upload

Check the following:

  • The manifest package is a .zip file downloaded from Totara.

  • The package contains the required manifest and icon files.

  • The app version number has been increased.

  • The manifest app ID has not been changed accidentally.

  • The app package validates in the Microsoft Teams app validator.

  • Your Teams admin centre settings, custom app settings, and app policies allow the app to be uploaded and made available to users.

SSO does not work

Check the following:

  • The Microsoft Entra Application ID URI uses the domain, not the full Totara site path.

  • The Application ID URI matches the resource scope configured in Totara.

  • The access_as_user scope exists and is enabled.

  • The Teams desktop/mobile and web client IDs have been authorised.

  • The Microsoft Graph delegated permissions have been added.

  • Admin consent has been granted.

  • The OAuth 2 client ID and client secret in Totara match the Microsoft Entra app registration.

  • The redirect URIs in Microsoft Entra ID match the Totara URLs exactly.

  • The endpoints configured in Totara match those in the Microsoft Entra App.

    • These MUST match exactly. A common mistake is not using the v2 endpoints.

Users can open the app but images do not appear in the messaging extension

Check whether catalogue item pictures need to be publicly available.

In Totara, enable:

Allow public access to catalogue item pictures

Bot, messaging extension, or notifications do not work

Check the following:

  • The Azure Bot messaging endpoint is:

    https://[your.totara.site]/totara/msteams/botindex.php
  • The Microsoft Teams channel is enabled for the Azure Bot.

  • The Bot app ID in Totara matches the bot app registration’s Application (client) ID.

  • The bot client secret in Totara is the current secret value.

  • The Bot tenant ID in Totara matches the Microsoft Entra Directory (tenant) ID.

  • Microsoft Teams notifications are enabled in Totara message outputs, if using notifications.

Users cannot see or install the app

Check the following in the Microsoft Teams admin centre:

  • The app has been uploaded successfully.

  • The app is allowed.

  • The app has been assigned to the correct users or groups.

  • App management or app policies allow the relevant users to access the app.

  • Enough time has passed for Microsoft Teams to publish the app to users. Microsoft notes that uploaded custom apps can take time to become available to organisation users.

The Totara app does not appear when adding a tab to a shared channel

The Totara app cannot currently be added to Microsoft Teams shared channels. Standard channels and private channels are not affected.

Microsoft requires an app to declare supportsChannelFeatures: tier1 in its manifest before the app appears in the app picker for a shared channel. This property was introduced in Teams app manifest schema version 1.25. Totara generates a manifest at schema version 1.10, so the property is not present.

Adding the property to the downloaded manifest does not resolve this. The Microsoft Teams admin centre rejects the package:

Schema validation failed at 'supportsChannelFeatures': Property "supportsChannelFeatures" has not been defined and the schema does not allow additional properties.

No configuration change in Totara or in Microsoft Teams resolves this. Support for shared channels requires a change to the manifest that Totara generates, currently on the Totara backlog to fix.

Firewall

If you have an outbound firewall that blocks traffic from your server to the Internet, you'll need to allowlist the specified URLs here: https://learn.microsoft.com/en-us/azure/bot-service/bot-service-resources-faq-security?view=azure-bot-service-4.0#which-specific-urls-do-i-need-to-allowlist-in-my-corporate-firewall-to-access-bot-framework-services.