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.
- 1 Before you start
- 2 Setup guide
- 2.1 Step 1: Prepare the Microsoft Teams tenant
- 2.2 Step 2: Create an app registration in Microsoft Entra ID
- 2.2.1 Register the app
- 2.2.2 Complete the branding information
- 2.2.3 Step 2a [Optional] - Configure Microsoft Single Sign-On
- 2.2.3.1 Add authentication URLs
- 2.2.3.2 Expose an API
- 2.2.3.3 Add the access scope
- 2.2.3.4 Add authorised Teams client applications
- 2.2.3.5 Add Microsoft Graph delegated permissions
- 2.2.3.6 Create a client secret
- 2.3 Step 3: Create an Azure Bot
- 2.4 Step 4: Configure Microsoft Teams integration in Totara
- 2.4.1 Configure OAuth 2 for SSO
- 2.4.2 Allow Totara to be embedded in Teams
- 2.4.3 Allow public catalogue images
- 2.4.4 Configure the Microsoft Teams integration settings
- 2.4.5 Configure single sign-on settings
- 2.4.6 Configure bot settings
- 2.4.7 Customise the app branding
- 2.4.8 Add publisher information
- 2.4.9 Save the settings
- 2.5 Step 5: Install the app in Microsoft Teams
- 3 Updating an existing Teams app
- 4 Troubleshooting
- 4.1 The Teams app package fails to upload
- 4.2 SSO does not work
- 4.3 Users can open the app but images do not appear in the messaging extension
- 4.4 Bot, messaging extension, or notifications do not work
- 4.5 Users cannot see or install the app
- 4.6 The Totara app does not appear when adding a tab to a shared channel
- 4.7 Firewall
Before you start
You will need access to
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 |
|---|---|---|---|
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 |
|---|---|
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 |
|---|---|
Domain |
|
Totara site URL |
|
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.
Sign in to the Microsoft Teams admin centre admin.teams.microsoft.com.
Go to:
Teams apps > Manage appsOpen:
Actions > Org-wide app settingsCheck 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.
For most instances, checking “Allow third-party app” will suffice.
Save your changes.
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
Sign in to the Azure portal https://portal.azure.com/.
Go to
App registrationsNavigate 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.
Select New registration.
Enter a name for the app.
Example:
Totara Microsoft TeamsUnder Supported account types, select:
Accounts in this organizational directory onlyThis 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.
Select Register.
On the app overview page, copy and save the following values:
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
In the app registration, go to the branding or properties area and complete the app information.
Use values that match the Teams app you want users to see.
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 |
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
In the Microsoft Entra app registration, go to:
AuthenticationSelect Add a platform.
Select Web.
Add the redirect URI:
https://[your.totara.site.url]/admin/oauth2callback.phpIf your Totara installation uses a different admin folder name, replace
adminwith your actual folder name.Add the logout URL:
https://[your.totara.site.url]/totara/msteams/sso_logout.phpSave your changes.
Add another redirect URI:
https://[your.totara.site.url]/totara/msteams/oidc_login.phpSave your changes again.
Expose an API
In the Microsoft Entra app registration, go to:
Expose an APISelect Add next to Application ID URI.
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.
Save your changes.
Add the access scope
In Expose an API, select Add a scope.
Enter the following values:
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 |
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 desktop/mobile client |
|
Teams web client |
|
Add Microsoft Graph delegated permissions
In the app, go to: API permissions
Select: Add a permission > Microsoft Graph > Delegated permissions
Add the following permissions:
email offline_access openid profile User.ReadSave your changes.
Select: Grant admin consent for [tenant name]
Confirm the consent prompt.
Create a client secret
Go to: Certificates & secrets
Select New client secret.
Enter a description.
Choose an expiry period that matches your organisation’s security policy.
Save the secret.
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
Sign in to the Azure portal https://portal.azure.com/ .
Go to: Bot services
Depending on your Azure portal layout, this may appear under Azure AI services, Applied AI services, or through search.
Select Create.
Choose Azure Bot.
Complete the form.
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 |
Select Review + create.
Select Create.
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 |
|---|---|
Icon | Your organisation or Totara app icon |
Display name | The name users should see in Microsoft Teams |
Configure the messaging endpoint
Go to: Settings > Configuration
Set the messaging endpoint to:
https://[your.totara.site.url]/totara/msteams/botindex.phpSelect Apply.
The messaging endpoint is configured from the Azure Bot resource’s Configuration pane.
Enable the Microsoft Teams channel
Go to: Settings > Channels
Under Available channels, select Microsoft Teams.
Read and accept the terms of service.
Select the appropriate messaging environment.
For most organisations this will be: Microsoft Teams Commercial
Select Apply.
Close the channel setup page.
Record the bot app ID and create a bot client secret
In Azure, go to: App registrations
Open the app registration created for the bot.
Copy and save the Application (client) ID.
You will use this as the Bot app ID in Totara.
Go to: Certificates & secrets
Delete any existing secret if required by your organisation’s process.
Select New client secret.
Enter a description.
Choose an expiry period.
Save the secret.
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.
Sign in to Totara as a Site Administrator.
Create a new Microsoft OAuth 2 service.
Configure the service using the values from your Microsoft Entra app registration.
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 |
Select Configure endpoints for the Microsoft OAuth 2 service.
In your Microsoft Entra app registration, open your app registration and go to the Overview page.
Select Endpoints.
Check that the endpoints configured in Totara match the Microsoft Entra endpoints.
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.
In Totara, go to: Site administration > Security > HTTP security
Enable: Allow frame embedding
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.
In Totara, go to: Quick-access menu > Security
Save your changes.
Configure the Microsoft Teams integration settings
In Totara, go to: Site administration > Microsoft Teams > Microsoft Teams integration
Configure the required app settings.
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 |
Configure single sign-on settings
If you are using SSO, configure the following settings.
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 |
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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
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
In Totara, go to: Site administration > Microsoft Teams > Totara app installation
Confirm that each setup check has either passed or been skipped.
Download the manifest file.
This should download a
.zipapp package.Sign in to the Microsoft Teams admin centre.
Go to: Teams apps > Manage apps
Upload the app package.
Depending on your Teams admin centre UI, select either: Upload new app or Actions > Upload new app
Select the manifest
.zipfile downloaded from Totara.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.1If 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
In Totara, save the updated Microsoft Teams integration settings.
Go to:
Site administration > Microsoft Teams > Totara app installationDownload the updated manifest
.zipfile.In the Microsoft Teams admin centre, go to:
Teams apps > Manage appsSearch for your app.
Open the app details page.
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
.zipfile 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_userscope 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
v2endpoints.
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 picturesBot, messaging extension, or notifications do not work
Check the following:
The Azure Bot messaging endpoint is:
https://[your.totara.site]/totara/msteams/botindex.phpThe 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.