HaloCRM

HaloCRM Guides

Guides > Embedding your Halo Self-Service Portal into Microsoft Teams

Embedding your Halo Self-Service Portal into Microsoft Teams

In this guide we will cover:

- What is Embedding the self-service Portal into Microsoft Teams?

- Part 1 - Embed your Halo Portal into Teams

- Part 2 - Configure Automatic Sign in



What is Embedding the self-service Portal into Microsoft Teams?

Embedding your Halo self-service portal into Microsoft Teams allows your users to access the Halo portal from Microsoft Teams. Providing them an easy way to log service requests, report incidents, complete approvals, etc. When embedded the portal can appear in Teams as an app, allowing them to navigate between their Teams chats/channels and the Halo portal easily. The portal can be embedded with or without single sign-on. 


When embedded without single sign-on users will need to sign into the Halo portal when this is opened in Teams. When embedded with single sign-on users will not need to sign into the Halo portal, they will automatically be signed in. When they sign in to Teams their credentials will authenticate their access both to Teams and to the Halo Portal. 


This guide is split into two parts. Part 1 covers how to embed the Halo self-service portal into Microsoft Teams. Part 2 covers the additional configuration that will need to be carried out in order for single sign on to be used to automatically log users into the embedded portal. 


Part 2 is not mandatory, but  if you would like to setup this automatic login functionality you must follow BOTH parts 1 and 2. 



Part 1 - Embed your Halo Portal into Teams

This part will cover how to embed your Halo portal into MS Teams. 


Create an Azure Application

Firstly, you will need to set up an App Registration in Microsoft Azure (Entra). This can be created from your Azure portal (https://portal.azure.com)


Give it a name and set it as a single tenant app registration (leave the "Redirect URI" field blank). Register the app by clicking the button on the bottom left of the screen.

Fig 1. New Azure application.


No further configuration needs to be completed for this app registration. 


Once registered head to the 'Overview' tab and copy the 'Application (client) ID'. Keep note of this as this will be used later. 

Fig 2. Application (client ID) for Azure application. 


Now you will need to create a Microsoft Teams application. 


Create Microsoft Teams Application

To create a MS Team application head to https://dev.teams.microsoft.com/home and log in with your Azure credentials. Once you have access to the Teams developer portal head to the 'Apps' tab and create a new app.

Fig 3. Create new app in MS Teams developer portal.


Once you have given the app a name and created it head to the 'Basic Information' tab. Here you will need to complete all mandatory (and applicable) fields. Not all fields may seem relevant but these fields must be filled out for this to work. 

Fig 4a. MS Teams app information.

Fig 4b. MS Teams app information.


Application (client) ID - Enter the ID of the Azure application created earlier (figure 2). 


The developer information is just the website of your organisation and your companies name, this is just to see who published the app. These settings are strict because the app being connected could be for payment processing, so by default app creation on the dev console has mandatory fields for many things. Make sure to add to all the starred fields to get the app to work.


Once this has all been filled out, select the 'App features' tab and then 'Personal App'.

Fig 5. Add personal app tab.


Then use the button on the page to 'Create your first personal app tab'. 


In the popup enter your Halo portal URL, a name to identify it and a scope. 

Fig 6. Personal app tab details.


Tab name - This will be the name (of the app) users see when using this app in Teams. 

Content URL - Enter the URL of your Halo portal here. This this the portal that will appear in Teams. To find your portal URL head to Configuration > Self Service Portal in your Halo instance and look for the 'Web portal URL' field. 

Fig 7. Halo portal URL.


Scope - Determines who can see your app and where it can be installed. When set to 'personal' each user can add the app to their personal app collection. 

Context - Controls where the app appears in Teams. When set to 'personalTab' the app will only appear in the personal app area. 


Finally, press publish and select 'Publish to your organisation' which will allow users in your organisation to make use of the app you have created. You can also preview the app in Teams before publishing to ensure that everything is set up correctly.

Fig 8. Preview/Publish app.


Note: The Website URL will be shown in the URL preview for the personal app tab. 


Using the Teams App

Once you have added the application to your Microsoft Teams, open it up. When opening a pop-up will appear prompting you to log into the Halo portal.

Fig 9. Log in to Halo portal.


Note: If you have SSO configured for your Halo portal users will be able to log into the portal from Teams using the respective button, as they would when logging into the portal outside of Teams.


Once you have logged in you will be able to navigate the portal within MS Teams. 

Fig 10. Halo portal embedded in Teams.


Part 2 - Configure Automatic Sign in

This part will cover the additional configuration required for users to bypass the need to log into the embedded Halo portal. 


Before following this section ensure you have completed the following pre-requisites:

  • Followed Part 1 of this guide
    • In Part 1 you should have created:
      • x1 Azure application
      • x1 Microsoft Teams application
  • Your Halo instance needs to already have single sign-on setup with Azure (Entra). Single sign on should be allowed for users. 
  • As of 2025, Microsoft are enforcing verified domains when adding an Application ID URL (which is required Part 2 setup). Therefore, this feature is only available if your Halo instance and portal use a custom domain, which is verified within your Azure tenant Microsoft Learn.

Verify your Domain in your Azure Tenant

If you are setting this functionality up from 2025 onwards your Halo Portal URL will need to use a custom domain. You will not be able to set this up if your Portal is using a Halo domain (.halopsa.com, .haloitsm.com, .halocrm.io).


To change the URL of your instance, you will need to log a request with our support team to have this changed once you have registered your own domain.


Once your custom domain is in use, you will need to verify this within your Microsoft Azure tenant.


Head to the Entra admin centre (ensure you are signed in as a Global Administrator). Head to 'Custom domain names' > Add a custom domain. Here, enter your custom domain name e.g. 'YOURCOMPANY.COM' and add the domain. Microsoft will show you a TXT DNS record. You will need to add this TXT record to the DNS host where your domain is managed. DNS propagation can take 72 hours, so we recommend continuing setup after this 72 hour period. Now head back to Entra and verify the custom domain added, you will need to select the custom domain and hit verify. If the TXT record is found, your domain will be marked as verified.


Configure Azure application for Single Sign-On

To begin, you will need to complete some additional configuration to your Azure application that is being used to authenticate single sign-on in your Halo instance. This is not the Azure application we created earlier, but an existing Azure application you should already have from a previous single sign on setup. 


We will need to expose this Azure application as an API. Within the SSO Azure application head to the 'Expose as API' tab and 'Add' an Application ID URI. 

Fig 11. Expose Azure app as an API.


Add in the URI in the following format:

  • api://{Halo Portal URL}/{Client ID of the app you're currently editing}

Fig 12. Add application ID URI.


Once saved you will need to define a scope. Use the 'Add scope' button on this same page. 


Configure the scope as shown in figure 13. 

Fig 13. Scope for application ID URI.


Next, under the heading 'Authorized client applications', you now need to add a the following application (client) IDs along with with the scope just created. 

  • Application (client) ID of the app registration we created earlier for embedding the Halo portal in Teams
  • 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Official Teams Desktop application (client) ID)
  • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Official Teams Web application (client) ID)

Note: The official application IDs for Microsoft Teams are published here. 

Fig 14. Adding the application ID created earlier as an authorised client application. 

Fig 15. Authorized client applications added. 


Once all the client applications are added copy the 'Application ID URI' as this will be needed later. 


Note: Later on, when testing, if you get a redirect error regarding the Microsoft Teams client ID not being in the redirect. You will need to add the client ID that it mentions in the error here as an Authorized client application.


Finally, you will need to add the below value to the manifest file of the app registration:

  • "requestedAccessTokenVersion": 2


The key should already exist, so you will just need to set it to '2'.

Fig 16. Adjust manifest values. 


Ensure the save the manifest after editing. 


Now the configuration for this Azure (SSO) application is complete. At this point you should have:

  • created x1 Azure application for embedding the Halo portal into Teams.
  • edited the Azure application you use for authenticating SSO in your Halo instance.
  • created x1 MS Teams application

You will now need to configure the app within the Microsoft Teams developer portal.


Microsoft Teams App Configuration

Head to the single sign-on tab within the MS Team application you created earlier. Paste the application ID URI you created earlier. 

Fig 17. Add application ID URI to MS Teams app. 


Now setup is complete you can press publish and select 'Publish to your organisation' which will allow users in your organisation to make use of the app you have created. You can also preview the app in Teams before publishing to ensure that everything is set up correctly.


Using the Teams app with Automatic sign in (Single Sign-On)

Once you have added the application to your Microsoft Teams, open it up. When opening no pop-up will appear prompting you to log into the Halo portal. Instead the user will be logged in automatically and will be able to see/use the Halo portal right away. 

Fig 18. Halo Portal embedded in Teams. 




Popular Guides

Pin It on Pinterest