<style>p { margin: 0 0 10px; }h1, h2, h3 { margin: 20px 0 10px; }h4, h5, h6 { margin: 10px 0 10px; }</style><p><b><span style="color:red;">This guide is now deprecated. <a href="https://usehalo.com/haloitsm/guides/1269">The up to date guide on how to embed your Halo portal into MS Teams with SSO (automatic sign in) can be found here.</a> </span></b></p>

<style>p { margin: 0 0 10px; }h1, h2, h3 { margin: 20px 0 10px; }h4, h5, h6 { margin: 10px 0 10px; }</style><p>This guide will explain how to embed your self service portal within teams and allow for automatic sign in with SSO.</p> <br> <h4 id="prerequisites">Prerequisites</h4> <ul> <li>You need to have already setup SSO, within Halo, with Azure.</li> <li><strong>Please Note:</strong> As of 2025, Microsoft are now enforcing verified domains when adding an Application ID URL <a href="https://learn.microsoft.com/en-us/entra/identity-platform/security-best-practices-for-app-registration#application-id-uri-also-known-as-identifier-uri">Microsoft Learn</a>. Therefore, this feature is only available if you have Halo configured with a custom domain, which is verified within your Azure tenant <a href="https://learn.microsoft.com/en-us/entra/identity/users/domains-manage#add-subdomains-of-a-custom-domain">Microsoft Learn</a>.</li> </ul> <br> <h4 id="verify-your-domain-in-your-azure-tenant">Verify your Domain in your Azure Tenant</h4> <p>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).</p> <p>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.</p> <p>Once your custom domain is in use, you will need to verify this within your Microsoft Azure tenant.</p> <p>Head to the Entra admin centre (ensure you are signed in as a Global Administrator). Head to 'Custom domain names'&gt; 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.</p> <br> <h4 id="azure-entra-configuration">1. Azure Entra Configuration</h4> <p>To begin, we will configure all that is required within Azure Entra. <br><br></p> <p><strong>1. Create a new app registration for the MS Teams app</strong></p> <div style="margin-left: 20px;"> No permissions or redirects need to be configured for this app, we just need to obtain the application (client) ID. </div> <br> <p><strong>2. Configure the SSO app registration</strong></p> <div style="margin-left: 20px;"> <p>Within the seperate app registration you have configured to use SSO for within Halo, you now need to expose it as an API.</p> <p>Go to the 'Expose an API' tab and select the add button next to the text 'Application ID URI'. Then pass the URI in the below format:</p> <p><code>api://{Halo Portal URL}/{Client ID of the app you're currently editing}</code></p> <p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkOTQ1ZTUyLWY1ZjEtNGRmZS04MTAzLTkwNmI4Y2NlMjdlZiJ9.W5nhX6EeDFAct3LJ_uv93LirQF9X5dLFAMTwgEcCTWQ" width="800px"><br></p> <p>Next, you need to define a scope. We recommend using the below config:</p> <p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFiNWFjMzJlLTMyYzMtNGFiYS1hNmYwLWI5MzM4N2ZhZGJiMyJ9.za-Z1LRv9YeaHK_asVgvF6uBEAQZrZ2bA09TTj4uMmM" width="400px"><br></p> <p>Next, under the heading 'Authorized client applications', you now need to add the application (client) ID of the app registration we created earlier for the Teams Portal and provide the scope we just created. Also add the general Teams application (client) ID here (1fec8e78-bce4-4aaf-ab1b-5451cc387264), with the same scope as your app registration client ID.</p> <blockquote> <h4 id="note">Note</h4> <p>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 ID that it mentions in the error here.</p> </blockquote> <p>Finally, you will need to add the below value to the manifest file of the app registration:</p> <p><code>&quot;requestedAccessTokenVersion&quot;: 2</code></p> <p>The key should already exist, so you will just need to set it to '2'.</p> </div> <br> <blockquote> <h4 id="checkpoint">Checkpoint</h4> <p>At this point, you should now have two seperate Azure app registrations. One basic one, that we will just pass to the MS Teams app and the one that is used for SSO.</p> </blockquote> <h4 id="microsoft-teams-app-configuration">2. Microsoft Teams App Configuration</h4> <p>We will now configure the app within the Microsoft Teams developer portal.</p> <p>Create a new application and configure it using the recommended config below:</p> <p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjgyNjY0OTYyLWM5MDgtNGM5OC1iZjY0LWM2MWQ4ZGE2YjgzMCJ9.CKOv_A_q6YMLBpoQ_OMJs329Hr4e9hjUDPeFy--UmBw" width="800px"><br></p> <p>In the 'Application (client) ID' field, this is where you want to provide the client ID of the seperate MS Teams app registration we created earlier.</p> <p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU0Nzg1NmVlLTUwZGMtNDI4MC1iZmZlLTZhZDdjNjgwMDQ1MyJ9.9wZ8j0Kju3LSHfp2HJ7DOtB7Wzt4lTYBDQ9vuGWyo24" width="800px"><br></p> <p>Go to the 'App Features' section and create a new 'Personal App'. Then create a tab with your Halo portal URL.</p> <p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijk5MWU3ZWI5LTM2OGItNDg3Yy1iNDU4LTc2MjhlMmJjMDRiNiJ9.C6HQVjdoNrvpv7Oci343ZB3-VoVXXw6-SDQwaJRNHQY" width="800px"><br></p> <p>Finally, go to the 'Single Sign On' tab and provide the URI that we created earlier when we exposed the API. You do not need to provide the scope.</p> <p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjA0NDcwMjI0LTkzZWMtNDFmMy05NTc0LWE0MTQwMTMxMDUzOSJ9.x83LJKE5z4tKCD_JB60xZqWN0DHpBw8XdvJRySHsPGs" width="800px"><br></p> <!---<img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjljMzhhZmRhLTIzYzctNDkzNC04MGNhLWU0ZWU5MGU5Y2NkYyJ9.PFJ0oDc6SfSOR7MFHIhFz3LCtsc4iaqDHL7qU_OiVY4" width="800px"><br>--> <h4 id="test-the-app">2. Test the App</h4> <p>That is the setup complete, so now either publish the app or test it within MS Teams and if it is successful, the portal will automatically be signed in upon opening the app.</p>