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

Decide which features you need

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

Sites and domains

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:

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:

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

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.

Open

Accessing Manage apps in the Microsoft Teams admin dashboard.

Step 2: Create an app registration in Microsoft Entra ID

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.

7. Select Register.

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

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.

3. Save your changes.

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

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.

Open

4. Save your changes.

Add the access scope

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

2. Enter the following values:

3. 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:

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

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.

6. Select Review + create.

7. Select Create.

8. 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:

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.