<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;}</style><p id="isPasted"><strong>In this guide we will cover:</strong></p><p id="isPasted"><strong>- What is the Okta Integration?</strong></p><p data-pasted="true"><strong>- Connecting Okta in Halo</strong></p><p><strong>- Creating an API Token in Okta</strong></p><p><strong>- Creating an Application in Okta</strong></p><p><strong>- Mappings and Configuration</strong></p><p><strong>- Configuring Okta SSO</strong></p><p><br></p><p><br></p><p><strong><span style="font-size: 14pt;">What is the Okta Integration?</span></strong></p><p>The Okta integration can be used to map Okta groups to Halo users/agents and their relevant roles, as well as allow them to log in to Halo using their Okta credentials. <em><strong>For the extent of this guide, we recommend using the "Super Admin" role in Okta.</strong></em></p><p><br></p><p>However, the minimum scopes required if using a custom role are:</p><ul><li>okta.users.read: Allows reading user information.</li><li>okta.groups.read: Allows reading group information.</li><li>okta.apps.read: Allows reading application information</li></ul><p><br></p><p data-pasted="true"><strong><span style="font-size: 14pt;">Connecting Okta in Halo</span></strong></p><p>Go into the Okta module in Configuration > Integrations > Identity Management. This will open the "Details" tab of the integration, where you can connect to Okta. </p><p><br></p><p>Enter your Okta instance URL in the first box with no additional parameters at the end.</p><p><br></p><p>From v2.232.1+, you will then need to determine your Authentication method using the "Authentication Type" drop-down. On versions prior to this only the Basic Auth option is available. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImE3N2QzMjkyLWY5YzUtNDEwZS05NWQwLTcyOGY0ODgwNWNlNiJ9.WIQT_3xV5jUsPP1LD3fRbLaFp2-k30kNvSsPX-MpP7A" class="fr-fic fr-fil fr-dib" width="1020" style="width: 1022px; height: 229.415px;" height="229"></p><p><strong><span style="font-size: 10pt;">Fig 1. Entering Okta credentials.</span></strong></p><p><br></p><p>The next steps will differ depending on the Authentication method you have chosen. This guide will outline how to use the Basic Auth method. If you would prefer to use OAuth2 please follow the relevant Okta guide linked below:</p><ul><li><a href="https://help.okta.com/wf/en-us/content/topics/workflows/connector-builder/authentication-oauth2-clientcred.htm" target="_blank" rel="noopener noreferrer">Use OAuth 2.0 Client Credentials</a> (v2.232.1+)</li><li><a href="https://help.okta.com/wf/en-us/content/topics/workflows/connector-builder/authentication-oauth2-authcode.htm" target="_blank" rel="noopener noreferrer">Use OAuth 2.0 Authorization Code</a> (v2.232.1+)</li></ul><p data-pasted="true"><strong><span style="font-size: 14pt;">Creating an API Token in Okta</span></strong></p><p><em><strong>Note: This step is only for Basic Auth, for information on setting up Okta using Client credentials or an Authorisation code see the relevant Okta guides linked above.<br></strong></em></p><p><br></p><p>In Okta, go to Security > API and click the "Create token" button.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImE4ZjU1NjBjLTM0NTAtNDhiNi05ZjVkLTRhNjU4NGRjOWUzNyJ9.DooaCmnWHvDngqy_wfgMBNxFIzCkz1SS19tBIdDfzis" width="1218" style="width: 1220px; height: 551.905px;" height="552" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 2. Token configuration in Okta.</span></strong></p><p><br></p><p>A popup will show to name your token, and set the IP limitations for the API. Save, and make note of the token.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM1YmY0YThmLWJiN2MtNDU4MS05YTMyLWYyZTE2YWE0ZjMyMCJ9.Sh4YGxJB_o9lI0XiMvgP_qNq0Yf6nr-nEzMS8OQ8gpY" width="464" height="349" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 3. Creating the new token.</span></strong></p><p><br></p><p>Click "Create token".</p><p><br></p><p><strong><span style="font-size: 14pt;">Creating an Application in Okta</span></strong></p><p>Next, go to Applications > Applications, and "Create App Integration".</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQyZWFjNDBiLTBlZTctNDM1NC04MTE1LWNlOWM3MGE5ZjBlYiJ9._K0xAJIxJDcvJjfSaDYIf2f2PJq1--fS-TwzvLx76ZE" class="fr-fic fr-fil fr-dib" width="1216" style="width: 1218px; height: 534.926px;" height="535"></p><p><strong><span style="font-size: 10pt;">Fig 4. Applications area.</span></strong></p><p><br></p><p><span style="font-size: 11pt;">Create an application of type 'Web' that uses 'OpenID Connect' sign in method. </span></p><p><br></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjQ5ZmZkNmU4LTgyNDctNDczNC1hNzMwLWIwZTc0Yzc5ZDI5OSJ9.yihdJDoqDp68jV2X6n5xyNZSa29Qb8Np1yR7eR3o2QQ" class="fr-fic fr-fil fr-dib" width="666" style="width: 668px; height: 389.827px;" height="390"></span></p><p><span style="font-size: 10pt;"><strong>Fig 5. Sign in Method for application.</strong></span></p><p><br></p><p>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><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImYzNGEyMjM2LTFkMmItNDJjOS04ZDgxLTJiMTg1NDNjZTNlMCJ9.ywnIqLkd5qCw2a18OnqLRnQkGhqwzvlEwTGXdnX8US4" width="691" height="628" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 6. Enabling grants for the application.</span></strong></p><p><br></p><p>Scrolling down, you can then set the redirect URIs for login. </p><p><br></p><p style="box-sizing: inherit; margin: 0px; line-height: 1.4285em; color: rgb(0, 0, 0); font-family: sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;" id="isPasted">The following redirect URIs are needed:</p><p style="box-sizing: inherit; margin: 0px; line-height: 1.4285em; color: rgb(0, 0, 0); font-family: sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><br style="box-sizing: inherit;"></p><ul style="box-sizing: inherit; margin-bottom: 1rem; margin-top: 0px; color: rgb(0, 0, 0); font-family: sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><li style="box-sizing: inherit;">Sign-in redirect URI - <a data-fr-linked="true" href="https://auth.nethelpdesk.com/account/openidresponse" style="box-sizing: inherit; color: rgb(15, 97, 161); background-color: transparent; touch-action: manipulation; text-decoration: none; cursor: pointer; user-select: auto;">https://YOURHALODOMAIN/auth/account/openidresponse</a> for agent login (to the agent application) and <a data-fr-linked="true" href="https://yourhalodomain/auth/account/openidresponse%C2%A0" style="box-sizing: inherit; color: rgb(15, 97, 161); background-color: transparent; touch-action: manipulation; text-decoration: none; cursor: pointer; user-select: auto;">https://YOURHALOPORTALDOMAIN/auth/account/openidresponse</a> for user logins (to the portal)</li><li style="box-sizing: inherit;">Sign- out redirect URI - <a data-fr-linked="true" href="https://mycompany.nethelpdesk.com/" style="box-sizing: inherit; color: rgb(15, 97, 161); background-color: transparent; touch-action: manipulation; text-decoration: none; cursor: pointer; user-select: auto;">https://YOURHALODOMAIN.com</a> for agent log outs of the agent application and <a data-fr-linked="true" href="https://yourhalodomain.com/" style="box-sizing: inherit; color: rgb(15, 97, 161); background-color: transparent; touch-action: manipulation; text-decoration: none; cursor: pointer; user-select: auto;">https://YOURHALOPORTALDOMAIN.com</a> for user logouts of the portal. </li></ul><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjUzMzY5ZjY2LWE5OGItNDVjMy05YjQ3LWYzMTI0NDkwMTFjYiJ9.tT_-D8YI5MmMMbRzPQmRJvnQK7Q9XnN0JFE1r0ckQUI" class="fr-fic fr-fil fr-dib" width="697" height="303"></p><p><strong><span style="font-size: 10pt;">Fig 7. Setting redirect URIs for the application.</span></strong></p><p><br></p><p>Once you have created your Token, head back to the Okta integration in Halo and paste this in the "API Token" field.</p><p><br></p><p data-pasted="true">Click the "Test Credentials" button (you may need to do this twice the first time) to test your configuration. Upon successful configuration, a "Validation Successful" popup will show.</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImRlMDQ2ODVhLTZkODUtNGM0MS1hN2ViLWFkMTQ0ZjgyN2QwOCJ9.yfMkD4PZHELcRuR6B8iU1cSHWEBZGGmleqUEpmtXC9k" class="fr-fic fr-fil fr-dib" width="1015" style="width: 1017px; height: 283.587px;" height="284"></p><p><strong><span style="font-size: 10pt;">Fig 8. Setting and testing credentials.</span></strong></p><p><br></p><p><strong><span style="font-size: 14pt;">Mappings and Configuration</span></strong></p><p>The next tab, "Field Mappings" is where the user and agent mappings are set. These are pre-set here, but can be altered if needed for your set-up. The first table is for user mappings. As of v2.232.1+, you can map a User's Preferred and Middle Name here.</p><p><span style="font-size: 14pt;"><br></span></p><p><span style="font-size: 14pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImU3NDAzZjg0LTY4NDMtNDZiOC1iNThkLWEwM2QzZjQ3ZTFmOSJ9.0e4w_7NX-dMtqXNvVskmvSDAjLT-38Nq4HReA2_ye6Y" width="1209" style="width: 1211px; height: 357.979px;" height="358" class="fr-fic fr-dii"></span></p><p><strong><span style="font-size: 10pt;">Fig 9. User Mappings table.</span></strong></p><p><br></p><p>The second table is then for agent mappings.</p><p><br></p><p data-pasted="true">As of v2.238+, you can map an Okta field to the Halo field "team", this will populate the default team against the agent. This can be used to assign agents to teams automatically using information in Okta. The Okta field you are mapping must contain the name of the team in Halo you would like the agent to have, matching will be based on the team name. If the data in this field cannot be matched to a team, the default team for the agent will not be populated. When a default team is set for an agent they will be granted the following membership to this team:</p><ul><li>Can be assigned to</li><li>Can see Unassigned Tickets for this Team</li><li>Can see Tickets assigned to other Agents in this Team</li></ul><p><br></p><p>Depending on your setup, you may wish to add the "department" mapping to this table as well to import your departments.</p><p><br></p><p><span style="font-size: 14pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjNhYTU1ODhlLTAzZjctNGFhMC04NDAyLThmZDQ1OWQwMWUyNSJ9.N6qC7YEUhIOoGIx8Sue9q23Yp4-ARWhuez8tFJSdyrI" width="1210" style="width: 1212px; height: 323.332px;" height="323" class="fr-fic fr-dii"></span></p><p><strong><span style="font-size: 10pt;">Fig 10. Agent Mappings table.</span></strong></p><p><br></p><p>The next tab is the "Site/Agent Mappings". Here you can map a site to a specific Okta group, or set certain statuses from the mapping. You can also add filters for the mapping, as well as set a default user role.</p><p><br></p><p><span style="font-size: 14pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjlkZDNiNDIzLTMzMDktNDIyYS1iOTM0LTczYjM4NWMzMWM0ZiJ9._WUF3TA-ngt4V530h9D278PvCSnPw0Ys-Yb8-Ok16k4" width="1216" style="width: 1218px; height: 175.604px;" height="176" class="fr-fic fr-dii"></span></p><p><strong><span style="font-size: 10pt;">Fig 11. Site mappings table.</span></strong></p><p><br></p><p>The "Advanced" tab is where mappings can be set for agent roles, change advise boards, or user roles. They can be assigned or removed from these using the group set on the mappings.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImRmMThkNGNkLWRjNGEtNGU0Ni1hNjBiLTQ3OGQyNjNiYmUwOCJ9.wZQ6yt-3WYWRra4Kn7if9A-JmTHApB2g4Uyb50_v688" width="1220" style="width: 1222px; height: 516.281px;" height="516" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 12. Advanced mappings.<br></span></strong></p><p><br></p><p>The "New User Onboarding" tab allows you to set a ticket type to be logged when new users are created in Halo from Okta. If a template is set, the end-user and ticket field mappings can be set.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImI5ZTU0NjkyLTc4ZWQtNGJiNC05MmIxLTViMWVjNmMxMjhkNSJ9.lbayoDEG5SmNJ6GaGT0WOczwGjI-re2sAHt17rREgo8" width="1215" style="width: 1217px; height: 274.288px;" height="274" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 13. New User Onboarding tab.</span></strong></p><p><br></p><p>In the "Imports" tab, you can then choose the matching fields and statuses that are considered to make them "active". The below statuses are by default considered "Active" in Okta, so will be the likely selection here. If any other status is set, the agents/users will be deactivated upon the next import.</p><p><br></p><p>You can manually import users and agent here, and then set the Halo Integrator to automatically sync these going forward.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjhlZTI2ZjAxLTI0Y2UtNDAyMC1hNTE5LTM2ZDAxOTcyYjVhYyJ9.VcKJcWYZ4W9UuKTnV-i0WaNeTCt9qT_f6XJ1SPT_mBs" class="fr-fic fr-fil fr-dib" width="1191" height="583"></p><p><strong><span style="font-size: 10pt;">Fig 14. Matching fields and integrator configuration.</span></strong></p><p><br></p><p><span style="font-size: 14pt;"><strong>Configuring Okta SSO</strong></span></p><p>The final tab is "Single Sign-On". Upon enabling the first check box, you can enter the client ID and configure some optional settings. </p><p><br></p><p>The application client ID can be found at the end of the URL of Okta when viewing the application you wish to use, or in the below box that shows at the top when viewing the application.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImE5Y2I3ZTZjLTA1MTctNGY4My1iMGNhLTJkMWU5MDQ5ZThiOSJ9.GwEwuRrkqitkZj_RrocZVOwCxeEmabK3fovvKWSR654" class="fr-fic fr-fil fr-dib" width="742" height="385"></p><p><strong><span style="font-size: 10pt;">Fig 15. Client ID on the application.</span></strong></p><p><br></p><p>Then select whether the SSO is for both agents and users, or only one.</p><p><br></p><p>There is then the option to configure automatic redirect. <strong><em>Note: It is recommended to test login of your Okta SSO before enabling this, to ensure there is no issues with agents/users trying to log in.</em></strong></p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjUzZTVjMDVlLWM5OGYtNDhhMy1iOTdjLTE3OGZkMGM5ODE4MCJ9.814O15Yex1VOnXCTRPZAOUSdARo-hiX9U-juIPAT8_s" width="1219" style="width: 1221px; height: 243.237px;" height="243" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 16. Single sign on configuration for Okta.</span></strong></p><p><br></p><p>If automatic redirect is not enabled, the Okta login button will appear on the login screen here.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImM1MTdiODBiLTU2NGItNGNhZS1hOWY3LWYyYzQ0MmViOTE3YyJ9.sAuFWbZUokxU2xdc_ctwS8eGfvqBf-YgYUIycRyfl5M" width="381" height="490" class="fr-fic fr-dii"></p><p><strong><span style="font-size: 10pt;">Fig 17. Okta SSO button.<br></span></strong></p><p><br></p><p id="isPasted"><strong><span style="font-size: 12pt;">Potential errors </span></strong></p><p>If you encounter a 404 while attempting to sign into Halo via Okta, ensure the Okta Instance URL configured in Halo uses the primary Okta domain (<a href="https://youroktasubdomain.okta.com/" style="box-sizing: inherit; color: rgb(15, 97, 161); background-color: rgb(255, 255, 255); touch-action: manipulation; text-decoration: none; cursor: pointer; user-select: auto; font-family: Calibri, sans-serif; font-size: 15px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal;">https://yourOktaSubdomain.okta.com</a>) and not subdomain (<a href="https://youroktasubdomain.oktasubdomain.com/" style="box-sizing: inherit; color: rgb(15, 97, 161); background-color: transparent; touch-action: manipulation; text-decoration: none; cursor: pointer;">https://yourOktaSubdomain.oktaSubdomain.com</a>). The subdomain works for their API but doesn't work with Open ID Connect.</p><p><br></p><p id="isPasted"><strong><span style="font-size: 12pt;">SSO in Multiple Instances</span></strong></p><p>A Single Sign-On module is available to setup single sign on in your Halo instance. This allows you to create multiple SSO records. 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. For information on setting up single sign on using the dedicated module instead checkout: <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/2667" target="_blank" rel="noopener noreferrer">Single Sign-On in Halo</a>.</p>
