Setting up the Microsoft Teams integration (Private Cloud)

This feature is available with:

Don't know which module you're using? Find out here.

  • Engage - Intranet & Employee App
  • Microsoft 365 Integration

We have a new MS Teams app! The instructions in this article are for the new MS Teams app configuration. 

Are you looking to transition from an old to the new app? Read our recommended steps for a successful transition in this article.

Users can easily explore their Haiilo platform and its content right in MS Teams! You have the option to give them the full experience within Teams or just a view of your homepages. If you choose the full experience, users can see and interact with everything directly in Teams. If you go with the homepages only view, they can still like and comment on content, but clicking a link will open the Haiilo platform in a new browser tab.

Additionally, users get notifications for new blog articles, Studio posts, mentions, community invites, and event invites. Clicking a notification will take you to the relevant content on the Haiilo platform to see the complete content. The content opens in the Home tab for full-view Teams apps, or in a new browser tab for homepage-only view apps. When new notifications are available, a number will appear on the app in Teams, notifying you to check them.

To use the Microsoft Teams integration functionalities, you need to first set up an OpenID authentication provider and activate the Microsoft add-on. Please complete the Microsoft authentication setup and add-on activation before proceeding with these setup instructions.

1. Update Your Entra ID App

You need admin rights in your Microsoft Entra ID account to complete these steps.

  1. Log in to the Microsoft Azure Platform.
  2. Go to Microsoft Entra ID > App registrations > select the app that you created when setting up the Microsoft authentication and add-on for Haiilo.
  • 1. Update the Manifest
    1. Go to Manifest.
    2. Set the attribute for "requestedAccessTokenVersion" to 2. In some versions, the default value is null, and it should be 2.ms graph manifest token.png
  • 2. Define API Permissions
    1. Go to API permissions.
    2. Add permissions > Microsoft Graph > Application permissions.
    3. Add or make sure the following API permissions are added:
      • TeamsAppInstallation.ReadWriteSelfForUser.All
      • AppCatalog.Read.All
      • User.Read.All
    4. Select Grant admin consent for app_name for the added permissions and ensure the status for all permissions is marked Granted for your_tenant.api permissions ms graph for teams.png
  • 3. Add a Scope
    1. Go to Expose an API > Add scope
    2. In the field Application ID URI, add your Haiilo domain and Microsoft application ID in this format:
      • api://your_haiilo-domain/applicationId . Example: api://example.haiilo.app/e7d2fcb0-4c19-43a8-8ccc-2605be203fac
    3. Select Save and Continue.
    4. If the Application ID URI is successfully updated, another pop-up will appear. Fill out the fields as follows:
      • Scope name: access_as_user
      • Who can consent: Admins only
      • Admin consent display name: access_as_user
      • Admin consent description: access_as_user
      • State: Enabled
    5. Select Add Scope 
    6. Confirm that the new Application ID URI is added (this URl is always built as api://your_haiilo-domain/applicationId).
  • 4. Add a Client Application
    1. In the same section as above (Expose an API), select Add a client application.
    2. Add both these Client IDs one by one:
      • 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (For the mobile and desktop MS Teams app)
      • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (For the browser MS Teams app)
    3. Select the checkbox to authorize the Client ID for the scope you created above
    4. Select Add Application
    5. Repeat once for the other Client ID. Both are required.

Continue to the next steps.

2. Create an MS Teams Bot

To complete these steps, you need access to your Azure subscription and permission to create Azure Bot resources.

  • 1. Verify the Microsoft Entra app registration
    1. In your app that you created in the previous step, go to the Overview page.
    2. Copy the following values for later use:
      • Application (client) ID
      • Directory (tenant) ID
  • 2. Create the Azure Bot resource
    1. In Azure, select the search bar and search for and select Azure Bot (filter: Marketplace).azure bot.webp
    2. Select Create.
    3. Configure the resource:
      • Bot handle: Enter a name for the bot, for example, Haiilo Notifications.
      • Subscription: Select the Azure subscription in which the bot should be created.
      • Resource group: Select a resource group.
      • Pricing tier: Select the tier that matches your organization's requirements.
      • Type of App Microsoft App ID: Select Single Tenant.
      • Creation type: Select Use existing app registration.
      • App ID: Enter the Application (client) ID of the Microsoft Entra app registration you copied before.
      • Tenant ID: Enter the Directory (tenant) ID of your Microsoft Entra tenant you copied before.
    4. Select Review + create.
    5. After validation succeeds, select Create.
    6. When the deployment is complete, select Go to resource.
  • 3. Configure the messaging endpoint
    1. In the Azure Bot resource, go to Settings > Configuration.
    2. In the Messaging endpoint field, enter your Haiilo platform URL followed by: /web/content-teams-bot/api/messages. For example: https://example.haiilo.app/web/content-teams-bot/api/messages
    3. Select Apply.
  • 4. Enable the Microsoft Teams channel
    1. In the Azure Bot resource, go to Settings > Channels.
    2. Select Microsoft Teams.
    3. Accept the Microsoft terms of service if prompted.
    4. Select Save or Apply.

  • 5. Create a client secret for the bot

    We recommend creating a dedicated client secret for the bot, even if the app registration already has one for authentication.

    1. In the Azure Bot resource, go to Settings > Configuration.
    2. Next to the Microsoft App ID, select Manage Password. This opens the Client secrets page of the associated Microsoft Entra app registration.manage password azure bot.webp
    3. Select New client secret.
    4. Enter a descriptive name, for example, Haiilo Teams Bot.
    5. Select an expiration period according to your organization's security policy.
    6. Select Add.
    7. Immediately copy and securely store the secret Value. The value cannot be retrieved again later.
      • After the secret expires, you need to create a new secret and provide it to Haiilo for the bot integration to continue working. We recommend setting up a reminder before the expiration date.
  • 6. Provide the bot information to Haiilo
    1. Open a ticket in our Service Desk and provide the following information:
      • The Application (client) ID of the Microsoft Entra app registration
      • The newly created client secret Value. Share the client secret only through a secure channel approved by your organization.
      • The Directory (tenant) ID

Haiilo will configure the bot for your Private Cloud environment. After Haiilo confirms the configuration is complete, proceed to the next steps.

3. Download Haiilo's Teams App Manifest

You need "Manage integrations" permission to complete these steps.

  1. In Haiilo, go to Administration > Integrations > MS Teams.
  2. Toggle on the MS Teams settings.
  3. Scroll down to the bottom and find your Haiilo authentication provider that matches your Entra ID app. If you have multiple authentication providers, you need to set up the Teams app for each separately.
  4. Select Download next to the authentication provider to download the manifest.
  5. Under   , activate the MS Teams app. You can do this later as well, but we recommend doing it now so you don't forget. This will ensure your Teams app is active as soon as it's published.
  6. Select the platform experience for your Teams app(s). All your apps will use the same view. You can change the view later, and it will take effect in already installed MS Teams apps:
    • Full view: Your users can experience the full Haiilo platform within the Teams app.
    • Homepages only: Your users can only view the homepages within the Teams app. They can like and comment on posts on the timeline, but selecting any other element will open the platform in a browser.
  7. Continue to the next steps.

ms teams setup in haiilo.png

For technical reasons related to how Microsoft Teams currently handles external integrations, the Haiilo integration is embedded as an iFrame. This architectural constraint may, at times, affect the Haiilo platform experience within Teams. As a result, certain areas and functionalities may not appear or behave exactly the same as in the full browser version of Haiilo.

4. Import the Teams App

You need admin rights in your Microsoft Teams Developer Portal to complete these steps.

  1. Log in to the Developer Portal in Microsoft Teams.
  2. Go to Apps > Import app and choose the recently downloaded manifest (.zip file). Screenshot 2023-12-15 at 14.48.41.png

  3. Haiilo pre-fills the app information based on information from your Haiilo platform, your Microsoft authentication provider, and your custom bot. You can optionally edit some information, including the app name, description, branding, etc., to make the app work for your organization.

    • Please do not modify the following settings. They are pre-configured based on your Microsoft app and Haiilo authentication provider and are necessary for the app to function correctly.

      • Application (client) ID
      • App features
      • Domains
      • Single Sign-On
  4. After configuring the app, you can test it by selecting Preview in Teams and then adding the app to Teams.
  5. If the app works as expected, you can Publish it to your organization per your company guidelines.

Once published, your users can open the app in MS Teams! 

 

Homepages only experience ⬇️

MS Teams homepage gif.gif

Full view experience ⬇️

MS Teams homepages Full View.png

New blog and Studio notifications ⬇️

Blog and Studio notifications in MS Teams.png

Was this article helpful?

0 out of 0 found this helpful