HaloITSM

HaloITSM Guides

Documentation to assist with the setup and configuration of the HaloITSM platform

Guides > Okta Integration

Okta Integration

In this guide we will cover:

- Creating an Token in Okta

- Creating an Application in Okta

- Connecting Okta in Halo

- Mappings and Configuration

- Configuring Okta SSO



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. For the extent of this guide, we recommend using the "Super Admin" role in Okta.


However, the minimum scopes required if using a custom role are:

  • okta.users.read: Allows reading user information.
  • okta.groups.read: Allows reading group information.
  • okta.apps.read: Allows reading application information


Creating an Token in Okta

In Okta, go to Security > API and click the "Create token" button.


Fig 1. Token configuration in Okta.


A popup will show to name your token, and set the IP limitations for the API. Save, and make note of the token.


Fig 2. Creating the new token.


Click "Create token".


Creating an Application in Okta

Next, go to Applications > Applications, and "Create App Integration".


Fig 3. Applications area.


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).


Fig 4. Enabling grants for the application.


Scrolling down, you can then set the redirect URIs for login. As below, the sign-in URI will include "/auth/account/openidresponse" at the end, and sign-out will be your regular Halo URL.


Fig 5. Setting redirect URIs for the application.


Connecting Okta in Halo

Back in Halo, 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. 


Enter your Okta instance URL in the first box with no additional parameters at the end, and enter the token you made note of previously.


Fig 6. Entering Okta credentials.


Click the "Test Credentials" button (you may need to do this twice the first time) to test your configuration. Upon successful configuration, the below popup will show.


Fig 7. Validation Successful popup.


Mappings and Configuration

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.


Fig 8. User Mappings table.


The second table is then for agent mappings. Depending on your setup, you may wish to add the "department" mapping to this table as well to import your departments.


Fig 9. Agent Mappings table.


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.


Fig 10. Site mappings table.


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.


Fig 11. Advanced mappings.


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.


Fig 12. New User Onboarding tab.


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.


You can manually import users and agent here, and then set the Halo Integrator to automatically sync these going forward.


Fig 13. Matching fields and integrator configuration.


Configuring Okta SSO

The final tab is "Single Sign-On". Upon enabling the first check box, you can enter the client ID and configure some optional settings. 


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.


Fig 14. Client ID on the application.


Then select whether the SSO is for both agents and users, or only one.


There is then the option to configure automatic redirect. 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.


Fig 15. Single sign on configuration for Okta.


If automatic redirect is not enabled, the Okta login button will appear on the login screen here.


Fig 16. Okta SSO button.


Potential errors 

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 (https://yourOktaSubdomain.okta.com) and not subdomain (https://yourOktaSubdomain.oktaSubdomain.com). The subdomain works for their API but doesn't work with Open ID Connect.


Popular Guides

Pin It on Pinterest