<style>p { margin: 0; }span.fr-emoticon.fr-emoticon-img { background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle; } span.fr-emoticon { font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0; } blockquote { border-left: solid 2px #5e35b1; color: #5e35b1; margin-left:0; padding-left:5px;}blockquote blockquote{ border-color: #00bcd4; color: #00bcd4;}blockquote blockquote blockquote{ border-color: #43a047; color: #43a047;} table.grid{ border-collapse: collapse;} table.grid td, table.grid th { border: 1px solid #ddd;} .fr-fic.fr-dib{ display: block; margin: 5px auto;}.fr-fic.fr-dib.fr-fir{ text-align: right; margin: 5px 0 5px auto;}.fr-fic.fr-dib.fr-fil{ text-align: left; margin: 5px auto 5px 0;}.fr-fic.fr-dii{ float: none; margin: 5px auto;}.fr-fic.fr-dii.fr-fil{ float: left; margin: 5px auto;}.fr-fic.fr-dii.fr-fir{ float: right; margin: 5px auto;}img.fr-dib.fr-fir { margin-right: 0; text-align: right;}img.fr-dib.fr-fil { margin-left: 0; text-align: left;}img.fr-dib { margin: 5px auto; display: block; float: none;}img.fr-bordered { box-sizing: content-box; border: solid 5px #CCC;}img.fr-shadow { box-shadow: 10px 10px 5px 0px #cccccc;}img.fr-rounded { border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;}</style><style>
p {
margin: 0;
}
span.fr-emoticon.fr-emoticon-img {
background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle;
}
span.fr-emoticon {
font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0;
}
blockquote {
border-left: solid 2px #5e35b1; color: #5e35b1; margin-left: 0; padding-left: 5px;
}
blockquote blockquote {
border-color: #00bcd4; color: #00bcd4;
}
blockquote blockquote blockquote {
border-color: #43a047; color: #43a047;
}
table.grid {
border-collapse: collapse;
}
table.grid td,
table.grid th {
border: 1px solid #ddd;
}
.fr-fic.fr-dib {
display: block; margin: 5px auto;
}
.fr-fic.fr-dib.fr-fir {
text-align: right; margin: 5px 0 5px auto;
}
.fr-fic.fr-dib.fr-fil {
text-align: left; margin: 5px auto 5px 0;
}
.fr-fic.fr-dii {
float: none; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fil {
float: left; margin: 5px auto;
}
.fr-fic.fr-dii.fr-fir {
float: right; margin: 5px auto;
}
img.fr-dib.fr-fir {
margin-right: 0; text-align: right;
}
img.fr-dib.fr-fil {
margin-left: 0; text-align: left;
}
img.fr-dib {
margin: 5px auto; display: block; float: none;
}
img.fr-bordered {
box-sizing: content-box; border: solid 5px #CCC;
}
img.fr-shadow {
box-shadow: 10px 10px 5px 0px #cccccc;
}
img.fr-rounded {
border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;
}
</style><p><strong>In this guide we will cover:</strong></p><p id="isPasted"><strong>- The Single Sign-On Module</strong></p><p><strong>- Setting up Single Sign-On</strong></p><p><strong>- Single Sign-On Options</strong></p><p><strong>- Matching Users</strong></p><p><strong>- Claim Validations</strong></p><p><strong>- User Provisioning (creation)</strong></p><p><strong>- Adding SSO buttons to login Page</strong></p><p><strong>- Customise Single Sign-On Buttons</strong></p><p><br></p><p><br></p><p><strong><span style="font-size: 14pt;">The Single Sign-On Module</span></strong></p><p>A Single Sign-On module is available in Halo, a centralised location to setup each single sign on method you wish to integrate. Single sign-on can be integrated with Halo to allow your agents and/or users to log into Halo using their credentials from another application, usually you identity provider application. Reducing the number of login credentials your agents/users need. </p><p><br></p><p>Setting up single sign-on (SSO) in the single sign on module allows you to create multiple SSO records for each identity provider. Each record can then be linked to one of your Halo instances to restrict which instance the sign on method can be used in (Prod/UAT/Dev), useful when using linked instances. This allows you to use SSO in additional instances, but impose restrictions on who can log into the instance with their SSO credentials. Such as only allowing developers/administrators to login to your Dev instance. </p><p><br></p><p>The module also supports setting up a custom SSO connection, allowing you to use the sign in credentials from any identity provider that uses OIDC tokens. Sign in buttons can also be customised, allowing you to change the colour, label and logo on the button. </p><p><br></p><p><strong><span style="font-size: 14pt;">Setting up Single Sign-On</span></strong></p><p>Start by heading to Configuration > Integrations, and enable the module 'Single Sign-On' using the '+' icon. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxYzhlNzBkLWIxMjAtNDc0My04Y2FkLWNjNmNkM2Q1YmJjMyJ9.RTmOWk8GvShnJ8OYbmp88ktPrduabaYuCLEQxZslt_4" class="fr-fic fr-fil fr-dib" width="224" height="158"></p><p><strong><span style="font-size: 10pt;">Fig 1. Enable integration module.</span></strong></p><p><br></p><p>Once enabled click into the module to begin setup. </p><p><br>Start by creating a new SSO application using the 'New' button in the top right. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjBkNmE5NTE4LWMyZWQtNGU5NS1hMTAzLWNhMWNmOTBhNGQ3MCJ9.ZMZs4MwyqDU2KiqaJIO5LdFQ5Q1NbpSooWVqRz-1wdU" class="fr-fic fr-fil fr-dib" width="1693" style="width: 1695px; height: 782.308px;" height="782"></p><p><strong><span style="font-size: 10pt;">Fig 2. Create new SSO connection record. </span></strong></p><p><br></p><p>When creating a new application you will need to give the record a name and choose the type of SSO to use. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjA1ZWYyNjExLTk0MmQtNDEzMC1iZTNiLTFmNjc0YjNlOGNjNSJ9.SqcpTJPoFT1OnoKhOD8hZIKZgr5Q976CVUl7A0a41Ns" class="fr-fic fr-fil fr-dib" width="800" style="width: 802px; height: 440.914px;" height="441"></p><p><strong><span style="font-size: 10pt;">Fig 3. New application.</span></strong></p><p><br></p><p><strong>Type of SSO application:</strong></p><p>The type of SSO application you choose will depend on which application's credentials you would like users to be able to sign into Halo with.</p><p><strong>OIDC</strong> - (OpenID Connect) This is used to setup SSO using another user identity provider not in the given list. This can be used to setup SSO with any identity provider that can issue OIDC tokens and expose a discovery URL.</p><p><strong>Microsoft Entra</strong> - Used to setup SSO with Microsoft. </p><p><strong>Okta</strong> - Used to setup SSO with Okta. </p><p><strong>Google </strong>- Used to setup SSO with Google. </p><p><strong>Microsoft Entra External ID -</strong> Used to setup SSO with Microsoft for external users (previously B2C).</p><p><br></p><p>If you have multiple linked Halo instances you will also have the option to link the SSO record to an instance using the 'instance' field. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQ4MzlkMDI5LWRmZTUtNDNiNS1hNWZhLWJjNDY0MmFjNzkzOSJ9.BJZZk6Sb6xhlw6UkozzkyymKJkyOe_JSnQ_gakd60HU" class="fr-fic fr-fil fr-dib" width="1208" height="496"></p><p><strong><span style="font-size: 10pt;">Fig 4. Link to instance.</span></strong></p><p><br></p><p>When linked, this SSO option will only appear when signing in to the chosen instance. For example, if UAT is chosen this SSO option will only appear when logging into the UAT instance, it will not appear when logging into production. </p><p><br></p><p>The setup that follows will depend on the SSO type chosen. Only follow the next section that applies to your chosen type. </p><p><br></p><p><strong><span style="font-size: 12pt;">OIDC</span></strong></p><p>OpenID Connect is used when you would like to setup SSO using any other identity provider that is not in the given list. This provider must be able to issue OIDC tokens and a discovery URL.</p><p><br></p><p><strong><em>Note: The provider must also allow for authentication via a form post as Halo carries out the authentication request via a form post.</em></strong></p><p><br></p><p>Head to the 'Identity Provider Configuration' tab to continue setup. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxNzdkZDA1LTkyZmItNDNlNy1hZjc4LTFiNDU1NGU5ODNmMyJ9.2kcSrzfxwWssdOvZvprdDp3OkUO7Ym7EtKQfvvgKjEQ" class="fr-fic fr-fil fr-dib" width="973" style="width: 975px; height: 708.847px;" height="709"></p><p><strong><span style="font-size: 10pt;">Fig 5. Identity Provider Configuration for OIDC.</span></strong></p><p><strong><span style="font-size: 10pt;"><br></span></strong></p><p><strong>Discovery URL</strong> - You will need to enter the discovery URL your identity provider provides/has published for your tenant. This is usually provided per tenant in your identity provider, however, some providers may provide this per application. This should be publicly available and usually ends in '/.well-known/openid-configuration'.</p><p><br></p><p>You will need to create an API application within your chosen identity provider, to use for SSO. The application will need to be assigned the redirect URI found on the SSO setup page in Halo (figure 5). Keep the credentials of your application to hand as these will need to be entered into Halo.</p><p><br></p><p><strong>Authentication Type </strong>- Choose the authentication type used by your SSO application. This controls how user access will be authenticated (the authentication type used in the authentication flow). </p><p><strong>Client ID</strong> - Enter the Client ID of the application you have created in your identity provider for SSO. </p><p><strong>Client Secret </strong>- (Only applicable if using 'Authorization code with PKCE (recommended)' as the authentication type'). Enter the Secret of the application created for SSO. </p><p><br></p><p><strong><span style="font-size: 12pt;">Microsoft Entra</span></strong></p><p id="isPasted">Microsoft Entra is used when you would like to setup SSO using Microsoft Entra (Azure). </p><p><br></p><p><strong><em>Note: This method of connecting single sign on with Entra does not support <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2443" id="isPasted" target="_blank" rel="noopener noreferrer">B2C </a>SSO, only B2B. </em></strong></p><p><br></p><p id="isPasted">Head to the 'Identity Provider Configuration' tab to continue setup. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjJhMmNiZjRiLWM2MzYtNDg3Ni1hYTBlLTg1ZTEwZmE1MmM1MyJ9.yCmTts0fRQnHfDRMymRhldg8wqp-R2VmdFf04EVMAD0" class="fr-fic fr-fil fr-dib" width="1045" style="width: 1047px; height: 768.776px;" height="769"></p><p id="isPasted"><strong><span style="font-size: 10pt;">Fig 6. Identity Provider Configuration for Microsoft Entra.</span></strong></p><p><br></p><p id="isPasted">You will need to configure an app registration within your own Azure tenant. Before you do, you need to consider whether you will need a single or multi tenanted app. </p><p><br></p><p>The Halo SSO application can be single or multi tenant. Single tenant only allows Entra uses who are members of the same tenant as the one where the app registration is configured to sign-in. Multi-tenant applications allow Entra users from multiple tenants to sign in (restrictions on tenants can be configured in Halo). Our HaloITSM clients, which typically only have one Azure tenant will generally use a single tenant application. Our HaloPSA clients who wish their managed users to be able to use SSO along with HaloITSM clients with more than one tenant should configure a multi-tenant application. </p><p><br></p><p id="isPasted">Once you have decided the application type, follow the following steps to configure the app registration with your Entra ID tenant.</p><p><br></p><p><strong>Create Application for SSO </strong></p><p>Open the Entra Admin Center (or similar) and navigate to the App Registration section. Click "New Registration". Complete the details of the app registration. </p><p><br></p><p id="isPasted"><strong>Name:</strong> Be aware this could be visible to end-users, so choose a sensible name.</p><p><strong>Supported Account Type:</strong> Single or Multi depending upon your organisation's requirements</p><p><strong>Redirect URI:</strong> Choose the type web and insert the required RedirectURI, this can be found on the SSO setup page in Halo, seen in figure 6. This is the single redirect URI needed for both Agent and User SSO. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImI0ZTI2NWVlLWY0OTItNGQ0ZC1iNmQ5LTQ5MWMwZmM4ODU2ZCJ9.QVmBPyJXAyOAjKbmeeZ_alWxuFHzJySgqyaW-y76IRA" class="fr-fic fr-fil fr-dib" width="898" style="width: 900px; height: 750.28px;" height="750"></p><p><strong><span style="font-size: 10pt;">Fig 7. Azure application for SSO.</span></strong></p><p><br></p><p>Once registered, copy the "Application (client) ID" and "Directory (tenant) ID" from the Overview tab and store them safely, as these will be needed later.</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijk3YmVjZjJhLWNhMjQtNDBlOS1hZDI3LTQ5ZDIzM2IxZGQ2ZSJ9.HPOl7Ax_gleBAND_cIJDqQMrxtZq4uAznIT2uxT1m2s" class="fr-fic fr-fil fr-dib" width="1433" style="width: 1435px; height: 443.881px;" height="444"></p><p><strong><span style="font-size: 10pt;">Fig 8. Application client ID and Tenant ID.</span></strong></p><p><br></p><p id="isPasted">Navigate to the 'API permissions' tab and remove the default 'User.Read' permission.</p><p><br><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM4Y2U5OTAxLWQ3ZjItNGNkYy05MTljLTU1Y2I2MmRiMmVmYSJ9.MmkCIgZOyIlP4c62Efap5bRFT0dmt2qzbjYQgYgy_m8" class="fr-fic fr-fil fr-dib" width="1268" style="width: 1270px; height: 519.35px;" height="519"></p><p><strong><span style="font-size: 10pt;">Fig 9. Remove API permission.</span></strong></p><p><br></p><p id="isPasted">Now navigate to the 'Authentication' tab and enable 'ID tokens' under 'Implicit grant and hybrid flows'. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijc3NTVlZGUzLWE2NzUtNDIyMy05NmE5LWM0ZmIxMTM1NjFhNCJ9.VSoP2KkG7KasNakOyd5soEjAOcpf27WDemSTeUZ6guw" class="fr-fic fr-fil fr-dib" width="1254" height="855"></p><p><strong><span style="font-size: 10pt;">Fig 10. Enable ID tokens for application. </span></strong></p><p><br></p><p>If you would like additional claims to be validated when logging in ensure these claims are returned by the ID tokens. You may need to add additional claims you would like to validate to the application. Do this under the 'Token configuration' tab. Claims will be covered in more detail later in this guide. </p><p><br></p><p>If you are using the authentication type 'Authorization Code' or 'Authorization code with PKCE ' you will need to generate a secret for your application too. Head to the 'Certificates and Secrets' tab and add a 'New client secret'. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMzdkMGM3LTdmM2YtNDdlZC1iNjc1LWI3ZTgwMWY0ZDNjMiJ9.NbMBXNW081G0K9NYU7qA7YztWU_jMbWCRRRMIEtmoh4" class="fr-fic fr-fil fr-dib" width="1175" style="width: 1177px; height: 510.911px;" height="511"></p><p><strong><span style="font-size: 10pt;">Fig 11. Add client secret to Azure application. </span></strong></p><p><br></p><p>Once added copy the secret value. </p><p><br></p><p>Head back to Halo and enter the Tenant ID, Client ID (and secret if using) under the SSO setup page. Ensure you set the application type you have created too (single/multi tenanted). </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM4MTI5Nzc3LWM2MzMtNGI1Yi05NWY0LTAyZDg0MTUyODRiMyJ9.w1dKfgZhWztJklhNZYR-ngia_I_q3aL7LQ3NBCRLWOs" class="fr-fic fr-fil fr-dib" width="820" style="width: 822px; height: 422.879px;" height="423"></p><p><strong><span style="font-size: 10pt;">Fig 12. Enter application details in Halo.</span></strong></p><p><br></p><p>If you are using a multi tenanted application, you will also have the option to restrict which tenants can sign in using this SSO application. Simply enter the tenant IDs of the tenants that you would like to be able to sign into Halo using this SSO application. Any users within tenants not in this list will not be able to sign in. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImExMmQ3MWQxLWY5NTAtNGM4Ni1iYTgzLWNmYmY2NzAyZDgxNyJ9.sA1Z4jCufof1r8EnEWljHpltot44H9QV35pL2GoBJCk" class="fr-fic fr-fil fr-dib" width="828" style="width: 830px; height: 160.795px;" height="161"></p><p><strong><span style="font-size: 10pt;">Fig 13. Restrict tenant sign in.</span></strong></p><p><br></p><p><strong>Federated Domain</strong> - This can be used if Azure authentication requests in your tenant are forwarded to an ADFS server to streamline the SSO procedure in Halo. You will need to enter the fully qualified domain name for your ADFS server in the field here. </p><p><br></p><p><strong>User Interaction -</strong> Here, you can control how users can use this single sign on option.</p><ul><li><strong>None -</strong> When signing in users will not be prompted to enter credentials or choose the account they sign in with. They will be signed in with an account automatically based on identity information. </li><li><strong>Select an account - </strong>When signing in users will be prompted to choose who they would like to log in as. Accounts available to choose will be based on identity information.</li><li><strong>Force Credential Input -</strong> When signing in users will need to enter the credentials of the Microsoft account they would like to sign in with. </li></ul><p><br></p><p>When using this single sign-on type a discovery URL is still required for SSO connection, however, unlike OCID, this is generated and stored for you in the background. </p><p><br></p><p><strong><span style="font-size: 12pt;">Google</span></strong></p><p id="isPasted">Google is used when you would like to setup SSO using Google. </p><p><br></p><p>Head to the 'Identity Provider Configuration' tab to continue setup. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFkNmU2ZTcwLWUyZWItNDZhZS1iYWU3LTM4NGFkN2Q0YmRkNiJ9.trgoEZ6-JjufYFXejEoxt_dnO06ZDMDEA5B8U437oD0" class="fr-fic fr-fil fr-dib" width="823" style="width: 825px; height: 518.805px;" height="519"></p><p><strong><span style="font-size: 10pt;">Fig 14. Identity Provider Configuration for Google.</span></strong></p><p><br></p><p>You will need to create an application in the Google developer portal to use for SSO, this application will need to include the Sign-in redirect URI found on the SSO setup page in Halo (figure 14). If you are using 'Authorization Code' or 'Authorization code with PKCE' you will also need to generate a secret for the application. </p><p><br></p><p>In Halo, enter the Client ID (and secret if used) from your Google application. </p><p><br></p><p id="isPasted">When using this single sign-on type a discovery URL is still required for SSO connection, however, unlike OCID, this is generated and stored for you in the background. </p><p><br></p><p><strong><span style="font-size: 12pt;">Okta</span></strong></p><p id="isPasted">Okta is used when you would like to setup SSO using Okta. </p><p><br></p><p>Head to the 'Identity Provider Configuration' tab to continue setup. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImZlZTEzZGVhLTI3YjItNDhmMS1hYTBhLTExZWExNGVjOTFhZSJ9.fy7aG4IJN-qTi2PjGyfmK_bp6unWln13J6c-V9drFSs" class="fr-fic fr-fil fr-dib" width="843" style="width: 845px; height: 661.304px;" height="661"></p><p id="isPasted"><strong><span style="font-size: 10pt;">Fig 15. Identity Provider Configuration for Okta. </span></strong></p><p><br></p><p>You will need to create an application in Okta to use for single sign-on. Create an application of type 'Web' that uses 'OpenID Connect' sign in method. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImEyMDNmNjc2LWMxMTMtNDE0MC05MGYyLWU3ZDhiODdjYzI1MCJ9.WaleslVV9Udzu1xfIYlbQcAh-U8Pq2-SzO0k4pCC2zs" class="fr-fic fr-fil fr-dib" width="608" style="width: 610px; height: 355.98px;" height="356"></p><p><strong><span style="font-size: 10pt;">Fig 16. New application in Okta.</span></strong></p><p><br></p><p id="isPasted">When configuring, ensure "Authorization Code" and "Allow ID Token with implicit grant type" are both enabled. (If this is not available on your version of Okta, "Implicit (hybrid)" should be enabled).</p><p><br></p><p id="isPasted">Scrolling down, you can then set the redirect URIs for login. You will need to enter the sign-in redirect URI from the SSO setup page in Halo (figure 15). Enter <a data-fr-linked="true" href="https://YOURHALODOMAIN.com" id="isPasted">https://YOURHALODOMAIN.com</a> to use as the sign out redirect URI. </p><p><br></p><p>If you are using the 'Authorization Code' or 'Authorization code with PKCE' authentication type you will also need to generate a secret for the application. </p><p><br></p><p>Once you have the Client (application) ID (and secret is being used), enter these values into the SSO setup page in Halo. </p><p><br></p><p id="isPasted"><strong>Discovery URL </strong>- You will need to enter the discovery URL Okta has published for your tenant. This is usually provided per tenant in your identity provider, however, some providers may provide this per application. This should be publicly available and usually follows the format 'https://YOUROKTADOMAIN/.well-known/openid-configuration'.</p><p><br></p><p><strong><em>Note: When setting up SSO against the Okta module the discovery URL is generated for you, the option is included here to enter it yourself for flexibility.</em></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Microsoft Entra External ID</span></strong></p><p>Microsoft Entra External ID is used when you would like to setup SSO with Microsoft Entra External ID. This is Microsoft's CIAM platform, used to authenticate access for external users (those not in your organisation). Allowing them to sign up and sign into your Halo portal using credentials from other platforms.</p><p><br></p><p>Entra External ID replaces B2C SSO as Microsoft's CIAM platform. From 15 March 2026 B2C will be depreciated for everyone on P2 tier licencing. Your B2C tenant will remain but your Azure AD B2C P2 licence will no longer function. For everyone on P1 premium tier licencing existing B2C will be supported until May 2030. Therefore, when setting up SSO in Halo it is advised to use Microsoft Entra External ID as this is Microsoft's supported method going forward. </p><p><br></p><p>If you would like to setup single-sign on for external users using B2C checkout: <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2443" id="isPasted" target="_blank" rel="noopener noreferrer">Microsoft Entra ID: Single Sign-On (B2C)</a>.</p><p><br></p><p id="isPasted">Head to the 'Identity Provider Configuration' tab to continue setup. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjMzMjYwMTI3LTY0ODAtNGVjNi05ZDExLTQ4NzczNjg2NTkxYyJ9.BjdgF5Hv8_96SOHkCat5tb89Wrk2MbGFEp-uInR9xZo" class="fr-fic fr-fil fr-dib" width="816" style="width: 818px; height: 618.677px;" height="619"></p><p><strong><span style="font-size: 10pt;">Fig 17. Identity Provider Configuration for Entra External ID. </span></strong></p><p><strong><span style="font-size: 10pt;"><br></span></strong></p><p><strong>Discovery URL</strong> - You will need to enter the discovery URL your identity provider provides/has published for your tenant. This is usually provided per tenant in your identity provider, however, some providers may provide this per application. This should be publicly available and usually ends in '/.well-known/openid-configuration'. This will need to contain the user flow/policy you would like to use to authenticate users. </p><p><br></p><p>You will need to create an API application within your Entra External ID tenant, to use for SSO. This tenant will be separate to your primary Entra tenant. The application will need to be assigned the redirect URI found on the SSO setup page in Halo (figure 17). </p><p><br></p><p><strong>Authentication Type </strong>- Choose the authentication type used by your SSO application. This controls how user access will be authenticated (the authentication type used in the authentication flow). </p><p><strong>Client ID</strong> - Enter the Client ID of the application you have created in your identity provider for SSO. </p><p><strong>Client Secret </strong>- (Only applicable if using 'Authorization code with PKCE (recommended)' as the authentication type'). Enter the Secret of the application created for SSO.</p><p><br></p><p id="isPasted"><strong>User Interaction -</strong> Here, you can control how users can use this single sign on option.</p><ul><li><strong>None -</strong> When signing in users will not be prompted to enter credentials or choose the account they sign in with. They will be signed in with an account automatically based on identity information. </li><li><strong>Select an account - </strong>When signing in users will be prompted to choose who they would like to log in as. Accounts available to choose will be based on identity information.</li><li><strong>Force Credential Input -</strong> When signing in users will need to enter the credentials of the Microsoft account they would like to sign in with. </li></ul><p><strong><span style="font-size: 12pt;">Obtain Discovery URL for Microsoft Entra External ID</span></strong></p><p>To obtain the discovery URL needed you will first need to create an application in Entra. This application should be of type 'Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)', set the platform to be 'Web' and set the redirect URI that is present on the SSO setup page in Halo (figure 17). This URI follows the format <a data-fr-linked="true" href="https://YOURHALODOMAIN/auth/account/oidc/xyz">https://YOURHALODOMAIN/auth/account/oidc/xyz</a>. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImUzMzNkM2RhLTRkYmYtNDI2Zi1iMGQyLWE0ZjZlOGMxYTZlOSJ9._YAo4CI24h89hVvsDQTPaLJD7KUbc1x6Q8RwXzxV8WA" class="fr-fic fr-fil fr-dib" width="815" style="width: 817px; height: 690.461px;" height="690"></p><p><strong><span style="font-size: 10pt;">Fig 18. Azure application for External ID SSO.</span></strong></p><p><br></p><p>Once created head to the "Authentication" tab and enable "ID tokens (used for implicit and hybrid flows)" then save. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijc2MWNjNzA5LWUwNDAtNDgwYy1iMmJlLTQyYzk5MGRmY2VmNSJ9.p3aSCe03pxskOD_Yic4im0UQl8d88VwQ8hL03YS1F-c" class="fr-fic fr-fil fr-dib" width="776" style="width: 778px; height: 681.534px;" height="682"></p><p><strong><span style="font-size: 10pt;">Fig 19. Enable ID tokens for the application.</span></strong></p><p><br></p><p data-pasted="true">Now you will need to add the following permissions to this application:</p><ul><li>openid (Delegated) </li><li>email (Delegated)</li><li>profile (Delegated) </li></ul><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImJiM2YxNGI1LTMzMzktNDgxMi05ODdjLTJlYmRjNmYzYmE2NCJ9.1mDHVGr-NrLP0aDFnOtqebPA8a2kdMaoh4OcOATTVZM" class="fr-fic fr-fil fr-dib" width="1176" style="width: 1178px; height: 518.109px;" height="518"></p><p><strong><span style="font-size: 10pt;">Fig 20. Application permissions.</span></strong></p><p><br></p><p data-pasted="true">You will now need to link a user flow to this application to determine how users are authenticated. You may wish to create your own custom user flow, or use one of the standard user flows such as the 'sign up and sign in' user flow. </p><p><br></p><p>User flows can be added and configured under the "External Identities" section of your Azure. For information on creating user flows checkout <a data-fr-linked="true" href="https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-user-flow-sign-up-sign-in-customers" data-pasted="true" target="_blank" rel="noopener noreferrer">Create a sign-up and sign-in user flow for an external tenant app</a>.</p><p><br></p><p>Once you have chosen which user flow you would like to use, link the flow to the application. This is done within the "applications" tab of the user flow, for more detail on linking checkout <a data-fr-linked="true" href="https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-user-flow-add-application" data-pasted="true" target="_blank" rel="noopener noreferrer">Add your application to the user flow</a>. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImI3M2U4YTRjLWFlN2QtNGNhZC1iMTYzLTk2Y2ZmOTBhYWVhMyJ9.Q3tXqOkl__vmCZIsorQgWVvM8reHZOdBQ-beRxu7Dck" class="fr-fic fr-fil fr-dib" width="1041" style="width: 1043px; height: 425.868px;" height="426"></p><p><strong><span style="font-size: 10pt;">Fig 21. Application linked to user Flow.</span></strong></p><p><br></p><p>Once linked, run the flow to generate the Discovery URL you need to plug into Halo. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjcyMmRmN2ViLTIxN2MtNDU1ZS04ZDZhLWQ3ZjNjZWIwZmY0ZCJ9.67BTpDKXQGeE9Kjj2iqyAf77VHL3eTEVHObXz50G_xI" class="fr-fic fr-fil fr-dib" width="519" height="398"></p><p><strong><span style="font-size: 10pt;">Fig 22. Discovery URL.</span></strong></p><p><br></p><p>You will need the section of the Open Id Configuration highlighted in figure 22, you will not need the "?app=xyz" parameter. </p><p><br></p><p><strong><span style="font-size: 12pt;">Obtain Client ID and Secret </span></strong></p><p>Obtain the Client ID of your Azure application from the "Overview" tab within the application. </p><p><br></p><p>If you are using one of the Authorization Code authentication types, you will also need to generate a secret for your Azure application. This is done within the "Certificated and Secrets" tab of the application. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM3YmYzMjE0LTI4ZWItNDRhZC04NTE5LWY3NDFiYjk1ZGRhZiJ9.2NEC6AhrvyoiEsiK9RyM713BBQEuaxfzb4nV-CWPHZM" class="fr-fic fr-fil fr-dib" width="981" style="width: 983px; height: 365.857px;" height="366"></p><p><strong><span style="font-size: 10pt;">Fig 23. Client ID</span></strong></p><p><br></p><p>Now you have your connection details these can be plugged into Halo and you can configure the rest of the single sign on module. </p><p><br></p><p><strong><span style="font-size: 14pt;">Single Sign-On Options</span></strong></p><p>Now you have connected to the identity provider you would like to use for SSO you will need to setup how SSO behaves in Halo for this connection. These options are available for all SSO types. </p><p><br></p><p>Head to the 'Halo ... Configuration' tab to configure the behaviour settings. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQwMWNhNDI5LTZhNGItNGY3Mi1hZTk4LWQ2MGRjZDBkMjA2ZCJ9.bPSCPIfNWyySjzZMqwHjbo6i2dXA4LFZcoswEpqRU6s" class="fr-fic fr-fil fr-dib" width="907" height="396"></p><p><strong><span style="font-size: 10pt;">Fig 24. Additional SSO options.</span></strong></p><p><br></p><p><strong>Allow Single Sign-On for Agents and/or Users</strong> - Controls who will be able to use this SSO connection, Agents and/or Users. This will not control who the SSO button appears for, but rather who the sign in will be successful for. </p><p><strong>Automatically start the single sign-on flow for Agents without showing the Halo Service Desk login screen</strong> - When enabled, agents will be redirected to the sign in page using this SSO method automatically when logging into Halo. The Halo login screen will not be shown. If this option is enabled for multiple SSO connections, agents will be directed to login with the connection with the lowest ID. Therefore only enable this for one of your SSO connections. </p><p><strong>Automatically start the single sign-on flow for Users without showing the Halo Service Desk login screen</strong> - When enabled, users will be redirected to the sign in page using this SSO method automatically when logging into Halo. The Halo login screen will not be shown. If this option is enabled for multiple SSO connections, users will be directed to login with the connection with the lowest ID. Therefore only enable this for one of your SSO connections. </p><p><strong>Enable single-logout (SLO)</strong> - When enabled, logging out of the connected account anywhere, e.g. OneDrive will also log the user out of Halo; conversely if you log out of Halo, this will log you out of the connected applications entirely. Useful if you would like to only have to log out once at the end of the day, but you may want to disable this if you would like to be able to log out of one application but remain signed in to another.</p><p><br></p><p><strong><span style="font-size: 14pt;">Matching Users</span></strong></p><p>When logging in to Halo using their SSO credentials users/agents will need to be matched to their respective user/agent profile in Halo to determine who to log them in as. For each SSO connection you can choose how users are matched to their agent/user profile in Halo. </p><p><br></p><p>Head to the 'User Identification and Provisioning' tab. Here, use the 'User Identifier Claim' field to determine what field users are matched on. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjdjZDhhZDI5LTY3OWYtNGZiZC04ODI4LTdmNmY4ODc4YWI3NyJ9.xGVAoDE25Dn6vFLsAJgQg-HdUJd58TEsUr56vzyVo8s" class="fr-fic fr-fil fr-dib" width="858" height="366"></p><p><strong><span style="font-size: 10pt;">Fig 25. User Identifier Claim.</span></strong></p><p><br></p><p><strong>Subject </strong>- (OCID only) This will match users using their subject. In order to match to users/agents the subject of each user/agent will need to be stored in Halo. When this is chosen you will be given an additional 'User Matching Field', choose the field you are storing the subject for users/agents in. </p><p><br></p><p><strong><em>Note: The 'subject' is a claim returned in the ID token that is issued upon login. ID tokens are issued by the identity provider upon login, each token contains 'claims' which contain information about the user logging in. Some platforms (such as Entra) allow you to customise the claims returned by ID tokens. </em></strong></p><p><br></p><p><strong>Old</strong> - (Entra only) This will match users using their object ID in Entra. When using this claim for matching users/agents must have been imported into your Halo instance from the Entra or Microsoft CSP integration. The import is required as this stores the object ID of each user/agent, which is used when matching. </p><p><br></p><p><strong>Email </strong>- This will match users using their email address. Only use if all agent/user emails are unique. All connection types can use email to match. </p><p><br></p><p><strong>Custom Attribute</strong> - This will match users using a chosen attribute (claim). This attribute must be provided in the ID token issued by the identity provider upon logging in. When selected you will need to enter the name of the attribute to match on in the 'Custom attribute name' field. Then in the 'User Matching Field' select the field this attribute data is stored in, in Halo. In the figure 18 example users/agents will be matched using the 'username' attribute, if the value against this attribute in the ID token matches the value in the user field 'Additional Info' the person logging in will be matched to this user. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM3NTFjMGVlLTViY2UtNGVjZi1iMjlmLTQ4MzRiMjE4YWExNCJ9.w9oJPay3kGstih8E6axGtvYC4dI7-LTGuZeGFoORCCY" class="fr-fic fr-fil fr-dib" width="560" height="269"></p><p><strong><span style="font-size: 10pt;">Fig 26. Custom attribute matching example.</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Claim Validations</span></strong></p><p>You can also restrict who can sign in using this SSO connection based on claims. Useful if you would like to restrict who can sign in based on data in the identity provider, such as their group and account status etc. This can be used to restrict access to Dev/UAT instances too. This is set in the 'Additional Claim Validation' table. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijg0NDcwZDQ5LTA1MGUtNDg5NS04N2I2LWVhMDE3MDM1N2MyMCJ9.WoYeEurBOSglG75EZ321fe2boEsDgftmC-9yFI2S-Ow" class="fr-fic fr-fil fr-dib" width="1455" style="width: 1457px; height: 445.583px;" height="446"></p><p><strong><span style="font-size: 10pt;">Fig 27. Additional claim validations. </span></strong></p><p><br></p><p>When adding to the table enter the claim name you would like to restrict access based on. Then enter the value users must have in this claim to be able to sign in. In the figure 22 example only users that are issued a token with the claim "accountactive":true will be able to sign in. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQzOWNlNGQzLTAwMzMtNGFjZi1iNjdhLTFjNjU4MWU3NDQ4NCJ9.J4oJjUkCN7x2MoDLRU88YmOK8WPhq7KwCGUOxD00V_U" class="fr-fic fr-fil fr-dib" width="638" height="286"></p><p><strong><span style="font-size: 10pt;">Fig 28. Example claim validation.</span></strong></p><p><br></p><p>When using the SSO connection types 'Google' or 'Okta' a claim will be added for you automatically, as shown in figure 29. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImJjZWIzMzQyLTI4YjItNGE4Ny05NjNjLWRkMGQwZmY1NjNhMyJ9.9Sio4swHj5YhS3VjQTMAOcZH5vy7ijOVV-KWInouoSs" class="fr-fic fr-fil fr-dib" style="width: 1393px; height: 584.276px;" width="1562" height="656"><strong><span style="font-size: 10pt;">Fig 29. Email verified claim validation.</span></strong></p><p><br></p><p>This has been added for security purposes and we advise against removing this claim. This prevents any user with a fake/non verified email signing into your Halo. </p><p><br></p><p><strong><span style="font-size: 14pt;">User Provisioning (creation)</span></strong></p><p>Users can be automatically created during the sign-in process if they do not yet have a Halo Service Desk account. By enabling this functionality, the email address of the user signing in will be used as a secondary identifier if a user could not be located based on the User Identifier Claim.</p><p><br></p><p>Check 'Allow automatic user provisioning' to allow users to be created during the sign-in process. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImE0NjI0ZDQ1LTFiYTQtNDI1YS05MmZmLTAxZTJiZWI0Nzk4YyJ9.pBailPm6qfGn3yZqMeBQ-CxKrkPXbsUFUsBqQh6kdTg" class="fr-fic fr-fil fr-dib" width="903" style="width: 905px; height: 649.085px;" height="649"></p><p><strong><span style="font-size: 10pt;">Fig 30. Allow automatic user provisioning.</span></strong></p><p><br></p><p>When enabled additional options will become available. </p><p><br></p><p><strong>New Users will be matched to a Site based on Site domain matching</strong> - When enabled, new users will be assigned to a site based on the domain of their email address. If their email domain matches a site domain they will be created under this site. This is dependent on <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/878" id="isPasted" target="_blank" rel="noopener noreferrer">site domains</a> being setup.</p><p><strong>Default site for automatically created users</strong> - Choose the site users will be created under if the above setting is disabled or their domain cannot be matched to a site domain. </p><p><br></p><p><strong><span style="font-size: 14pt;">Adding SSO buttons to login Page</span></strong></p><p>Now your SSO connection(s) are setup you will need to add the button for this SSO connection to the login pages for the Halo agent app and self service portal. </p><p><br></p><p><strong><span style="font-size: 12pt;">Add SSO button to agent application</span></strong></p><p>Head to Configuration > Integrations > Halo API > View Applications 'nethelpdesk-agent-web-application'. Here you will see a list of all sign in options (SSO) you have configured. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjdlM2IwNDk1LTUyODgtNDcwMi1hM2Q3LWM0MmEzNmMxMjAwNiJ9.ZCoNuxI_fm9IvAEMTSzWyPCQiTTtTmigKs9MVWikToI" class="fr-fic fr-fil fr-dib" width="1036" height="495"></p><p><strong><span style="font-size: 10pt;">Fig 31. Sign in options for application (agent app).</span></strong></p><p><br></p><p>To make a sign in option (button) visible, edit the page, then edit the entry, set the 'Display' to be 'Show button'.</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQ4ZTczYTI5LThjMWItNDZmMS05MTNlLWIzZmEzYWZmYmVjNSJ9.Fu9_XEqdoebGgKJZ4RscCmyqJmbDyl5uAWHiYVSfO0I" class="fr-fic fr-fil fr-dib" width="637" height="290"></p><p><strong><span style="font-size: 10pt;">Fig 32. Set button for SSO connection to show (agent app).</span></strong></p><p><br></p><p>You also must set a 'Label override' to determine what the label for the button will be. If this is not set no label will be used. </p><p><br></p><p id="isPasted"><strong><span style="font-size: 12pt;">Add SSO button to self service portal </span></strong></p><p id="isPasted">Head to Configuration > Integrations > Halo API > View Applications 'halo-user-portal'. Here you will see a list of all sign in options (SSO) you have configured. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFkYjMwYmM5LTU1ZDItNGFmZi05NTNmLWE5NTUwNTNmYzk0NiJ9.Xu092_BbuUJNUaNxSQuAgJsqnC7XF6MJwcNDQFHkqOY" class="fr-fic fr-fil fr-dib" width="1478" style="width: 1480px; height: 423.258px;" height="423"></p><p id="isPasted"><strong><span style="font-size: 10pt;">Fig 33. Sign in options for application (portal).</span></strong></p><p><br></p><p id="isPasted">To make a sign in option (button) visible, edit the page, then edit the entry, set the 'Display' to be 'Show button'.</p><p><br></p><p id="isPasted">You also must set a 'Label override' to determine what the label for the button will be. If this is not set no label will be used. </p><p><br></p><p><strong><span style="font-size: 14pt;">Customise Single Sign-On Buttons</span></strong></p><p>Each button used to sign in using single sign on can be customised. Allowing you to change how the SSO button looks for each method of SSO. This is set per SSO connection under the 'Styling' tab. </p><p><br></p><p>If your SSO type is not OIDC you will need to enable 'Override the styling for the login button' in this tab before you can configure styling. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImExMWJiMmQ1LWQwZjYtNGQxMS05MmU2LTJlMjg4N2MyNzk0YSJ9.jewl3HKkZqrFlY8mo8c4RccmC3esAaAyaJcWLjUwOII" class="fr-fic fr-fil fr-dib" width="1033" style="width: 1035px; height: 655.087px;" height="655"></p><p><strong><span style="font-size: 10pt;">Fig 34. Options to customise SSO button.</span></strong></p><p><br></p><p><strong>Login Button Label</strong> - The label used for the button. This will be visible to users.</p><p><strong>Login Button Colour</strong> - The colour of the button.</p><p><strong>Login Button Logo</strong> - Upload an image of a logo here, this will be added to the button, left aligned to the button label. Use the 'Change' button to upload an image. The image will be resized automatically </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU2ODYyMjk0LTNjMzEtNDk3ZS1iNGFkLTE2ZWNiMWIxNTgyMiJ9.VwFVbApIv54ILtxdCQ3nweqPRJWD60eK1SVsCbgjVDg" class="fr-fic fr-fil fr-dib" width="375" style="width: 377px; height: 471.969px;" height="472"></p><p><strong><span style="font-size: 10pt;">Fig 35. Customised single sign on button. </span></strong></p><p><br></p><p><br></p><p><br></p>
