Setting up Microsoft Teams integration

Sites and domains

When configuring various settings for your Microsoft Teams integration it is important to understand the difference between Totara sites and domains. Sites can be installed in a sub-folder on a domain. For example, a domain with Totara Learn installed could have the following:

• Domain: www.totarasite.com
• Site: https://www.totarasite.com/learn 

The domain shows which domain the site is located on, but to access the Totara Learn instance itself you need to use the site name. For certain settings, such as API scope, you need to use the domain name (www.totarasite.com/) rather than the Learn site name.

Set up process

Step 1: Prepare Office 365

1. Log in to your Microsoft account at https://admin.teams.microsoft.com/.
2. Navigate to Teams App > Manage Apps and select Org-wide App settings.
3. Check the Allow third-party apps setting and save.

Step 2: Create an application in Azure

1. Log in to Microsoft Azure at https://portal.azure.com/.
2. Navigate to App registrations either by searching 'app registrations' from the search bar, or by navigating to More services > All services. If you have recently accessed App registrations it will be available on the dashboard.
3. Click New Registration.

4. Enter the Name for your app and select Accounts in any organizational directory (Any Azure AD directory - Multitenant) in Supported account types.
   

   In Azure there are three choices for Supported account types supported with Totara:

   • Accounts in any organizational directory (Any Azure AD directory - Multitenant): This is the recommended choice for this integration
   • Accounts in any organizational directory (Any Azure AD 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 Azure AD tenant. For more information please refer to Microsoft's documentation.

5. Click Register to create the app.
6. Make a note of the Application (client) ID as this will be required when configuring Totara integration settings later.
7. Complete all fields on the Branding page:
   • Name: The name of your app, which you should have set in step 2
   • Logo: You can use the same logo when configuring MS Teams within Totara
   • Home page URL: This should be the URL of your Totara website
   • Terms of service URL: This should be the same URL you use when configuring MS Teams within Totara
   • Privacy statement URL: This should be the same URL you use when configuring MS Teams within Totara
8. Save your changes.

Step 2a: Setting up Microsoft Single Sign-On (optional)

For additional information please see Microsoft's documentation.

1. In the Authentication blade click Add Platform then select Web.
2. Enter https://[your.totara.site]/admin/oauth2callback.php for the Redirect URI and https://[your.totara.site]/totara/msteams/sso_logout.php for the Logout URL, then Save. If you use a different folder than 'admin', use that one instead.
3. Add one more Redirect URI: https://[your.totara.site]/totara/msteams/oidc_login.php then Save.
4. In the Expose an API blade click Add Scope and enter api://[your.totara.domain]/[Application (client) ID], then select Save. This will be used in the Totara integration settings, but is only necessary if you require Single Sign-On.
5. Enter the following scope properties:
   • Scope name: 'access_as_user'
   • Who can consent: Admin and user
   • 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
6. Click Add a client application.
7. Add Teams desktop/native client: 1fec8e78-bce4-4aaf-ab1b-5451cc387264 and Add Teams web client: 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.
8. In the API permissions blade click Add permission and select the following permissions under Microsoft Graph > Delegated permissions:
   • email
   • offline_access
   • openid
   • profile
   • User > User.Read
9. Save your selection and click and confirm Grant admin consent for [tenant name].
10. In Certificates & Secrets blade click New client secret.
11. Give it a Name, choose the Expiration period and Save.
12. Make a note of the Client Secret value, as this will be required later in the process.

Step 3: Create a Bot in Azure (optional)

The bot framework setup is required in order to enable the messaging extension and notifications. The bot framework within Microsoft Teams allows for authentication to support these two features. However, these are optional features - if you do not wish to enable the messaging extension and notifications then creating a bot in Azure is not required.

1. Log in to Microsoft Azure at https://portal.azure.com/.
2. Navigate to Applied AI services > Bot services.
3. Click Create, then scroll down and click Load more, then select Azure Bot.
4. Click Create and complete the form with the following details:
   • Bot Handle: Any unique handle of your choice
   • Subscription: Select your existing subscription
   • Resource group: Select an existing group or create a new one
   • Location: For new resource groups select the location of your choice (choose somewhere close to your server)
   • Pricing tier: Click change plan and select the F0 (free) tier
   • Microsoft App ID:
     • For Type of App select Multi Tenant
     • For Creation Type select Create new Microsoft App ID
   • Click Review and Create, then Create, then Go to resource
5. You can optionally personalise the icon and name for the bot under Settings > Bot Profile > Icon & Display Name.
6. Under Settings > Configuration enter:
   • Messaging endpoint: https://[your.totara.site]/totara/msteams/botindex.php, then click Apply.
7. Under Settings > Channels click Microsoft Teams under Available Channels. Agree to the Terms of Service. Select the appropriate Messaging setting (probably Microsoft Teams Commercial), then click Apply, then Close.
8. Navigate to App registrations and select the newly created bot.
9. Make a note of the Application (client) ID, as this will be used as the Bot app ID in the Totara integration settings later in the process.
10. On the Manage > Certificates & Secrets page, delete any existing secret, then click New client secret.
11. Give it a Name, choose the Expiration period and Save.
12. Make a note of the Client Secret for Bot value, as this will be required later in the process.

Step 4: Prepare the Microsoft Teams extension in the Totara admin settings

Next you need to go to your Totara site to configure the admin settings.

1. Log in to your Totara site as a Site Administrator.
2. If using Single Sign On, set up the OAuth 2 SSO plugin using the following steps. Otherwise, skip to step 3.
   1. Enable the OAuth 2 plugin. 
   2. After selecting Create new Microsoft service set the following values for the settings:
      • Client ID: Your Application (client) ID from the Azure app
      • Client secret: Your Client Secret from the Azure app
      • Require email verification: Decide if you want to require email verification
   3. Click Save changes.
   4. Click the Connect system account icon in the System account connected column and log in to your Microsoft account.
3. Navigate to Site administration > Security > HTTP security and enable Allow frame embedding, then click Save changes.
4. (Optional) In order to allow catalogue images to show in the Messaging Extension feature, Microsoft requires images to be made publicly accessible via direct URL. If you would like the images to show, navigate to Quick-access menu > Security and enable the Allow public access to catalogue item pictures setting.
5. Navigate to Site administration > Microsoft Teams > Microsoft Teams integration.
6. Set the following values:
   • Manifest app ID: Your Application (Client) ID from the Azure app
   • Package name: Unique package name as a reversed domain (e.g. site.totara.your.msteams)
   • Under the Set up single sign-on heading, if you are using single sign-on:
     • Set the OAuth2 service setting to Microsoft - note that the OAuth2 authentication plugin must be enabled and using Microsoft's identity provider for single sign-on.
     • Set the SSO app ID to the Application (client) ID from the Azure app
     • Set the Resource scope to the api://[your.totara.domain]/[Application (client) ID] from the Azure app
   • Otherwise, make sure the OAuth2 service setting is set to None and continue
   • If you are planning to use Bot notifications (see step 3) then under the Set up the conversational bot heading:
     • Tick the Bot feature enabled setting
     • Tick the Message extensions feature enabled setting
     • Set the Bot app ID setting to the Application (client) ID for the Bot from the Azure bot app
     • Set the Client secret setting to the Client secret setting from the Azure bot app
7. Customise the application to match your organisation's visual brand.
8. In the Publisher information section add the Publisher's name and a link to the Publisher's website, as well as URL links to your own Privacy policy and Terms of use. If these are left blank then these will link to the equivalent pages on your Totara site.
9. Save your changes to generate a manifest file, while can then be downloaded in the Totara app installation settings.

Step 5: Install the app

Finally you just need to install the app on Microsoft Teams. You can do this by following these steps:

1. Navigate to Site administration > Microsoft Teams > Totara app installation.
2. Confirm that all checks for enabled features have been passed or skipped.
3. Download the manifest file.
4. Navigate to https://admin.teams.microsoft.com/, then Teams apps > Manage apps.
5. Click Upload, then Select a file. Select the manifest file downloaded in step 3, then confirm. 
6. If your manifest fails to be uploaded, you can try to validate it with App Validator - https://dev.teams.microsoft.com/appvalidation.html

Updating an existing app

If you are updating your app or making changes to the app name, description, icon, or adding or making changes to the language packs/strings, you will need to download and re-upload the manifest file. When you are creating a new manifest file you need to ensure that you update the app version number in the semver format, e.g. 1.0.0 to 1.0.1.

Once you have made the required updates, click Save and go to the Totara app installation setting.

1. Go to Team admin settings > Manage apps (https://admin.teams.microsoft.com/policies/manage-apps).
2. Search for your app and select it.
3. Click Update.
4. Select the downloaded manifest.zip file.
5. If Microsoft Teams says the app already exists, you should keep increasing the version number, re-download and re-upload a manifest file.

Please note that it can take up to 30 minutes for the app to update for all users, and may require restarting the app.

Customising the app

The Microsoft Teams integrations settings in Totara allow you to customise your app before downloading the manifest file. This configuration includes the app name, descriptions and icons. 

Once the configurations have been set and saved, a manifest file will be created.