What Oleria discovers
Once connected, Oleria continuously discovers and maps the following from your Halo tenant:- Accounts - every agent, including disabled and API-only agents, and every end user, including inactive end users. Halo’s per-site general user isn’t imported. Each account shows the name, email address, whether it’s enabled, its last login, and its two-factor authentication and single sign-on (SSO) status. Agents also show their job title, line manager, and creation date. An end user linked to an agent appears once, as the agent.
- Administrators - agents with the Is an Administrator permission are marked as administrators.
- Non-human identities - API applications, shown with the agent each one logs in as and the scopes it’s granted. API-only agents (Is an API-only Agent, or Agent Access set to API Only) and end users marked as service accounts are also imported as machine accounts. Agents with Agent Access set to Dashboard Only are imported as people. Halo’s system applications are marked as system accounts.
- Credentials - the client secret, API key, or JWT assertion key of each API application, and any federated credentials it trusts. Oleria imports only metadata, such as the type and whether the application is active. It never reads secret values.
- Groups - teams and agent departments, with their members and the agents who manage them. Memberships that an agent gets from a role are included. Each team is shown inside its department, and each department inside its parent department.
- Roles - agent roles and end-user roles, with the agents and end users who hold them.
Oleria doesn’t import tickets, assets, clients, sites, contracts, or other service desk content. Halo has no identity audit or sign-in API, so Oleria doesn’t import activity. See Known limitations.
Prerequisites
- A HaloITSM tenant, hosted by Halo or on-premise, that Oleria can reach over HTTPS from the internet.
- A Halo administrator who can create agents and API applications.
- For a custom domain or an on-premise Halo host, an allowlist entry for that host. Contact support@oleria.com before you connect. Hosts under
haloitsm.comandhaloservicedesk.comdon’t need one. - Admin access to the Oleria workspace.
Create the Halo API application
1
Create an integration agent
In Halo, go to Configuration > Teams & Agents > Agents and create a dedicated agent for Oleria. Under Permissions, give it the Is an Administrator permission. We recommend making it API-only (Agent Access set to API Only, or Is an API-only Agent on older Halo versions): an API-only agent takes no Halo license and can’t sign in to the Halo web or mobile apps.The agent must be an administrator. Halo shows non-administrators only the agents and teams they can edit, so Oleria refuses a non-administrator agent rather than sync a partial inventory. Oleria also runs remediation actions as this agent.
2
Create the API application
Go to Configuration > Integrations > Halo API > View Applications, select New, name the application, and make sure it’s enabled. Set it up as follows:
3
Grant the all scope
In the application’s permissions, select the
all scope. Oleria requests this scope when it signs in. Halo has no read-only administrator scope.Halo also limits the application to what its log-in agent is allowed to do, so the agent’s permissions decide what Oleria can read and change.4
Copy the client credentials
Save the application, then copy its Client ID and Client Secret. You’ll paste them into Oleria in the next section.
Store the client secret securely, and rotate it per your organization’s security policy.
The exact location of these settings can change between Halo versions. If the steps above don’t match what you see, refer to Halo’s guide to creating API applications.
If the log-in agent can’t read end users, API applications, roles, departments, or tenant security settings, Oleria skips them and syncs the rest. If it can list API applications but can’t open them, Oleria still syncs those applications but without their scopes and federated credentials, and logs the missing permission. If it can’t read agents or teams, the sync fails.
Connect HaloITSM to Oleria
1
Open the integration
Go to your Oleria workspace, select Integrations, then select the HaloITSM tile.
2
Complete the connection form
Fill in the connection form:
3
Confirm the connection
Select Authenticate. Oleria signs in with the client credentials, checks that the log-in agent is an administrator, reads one agent and one team, and identifies your Halo tenant before saving the integration.
You can connect each Halo tenant to Oleria once. To connect a different tenant, add a new integration.
Verify the integration
Confirm the HaloITSM instance appears on the Connected tab of your Oleria Integrations page with a status of Healthy. The integration’s Capabilities tab shows Read users, Read groups, and Read roles with the Halo permissions each one needs, and checks them against your API application. After the first sync completes, you can review the discovered accounts, non-human identities, groups, and roles in your Oleria workspace.Edit the integration
You can change the Client ID, Client secret, and Tenant of an existing integration, for example to rotate the client secret. Select Update to validate and save your changes.- To keep the stored client secret, leave Client secret empty.
- To remove a stored tenant name, clear Tenant.
- You can’t change the Halo URL of an existing integration. To connect another Halo URL, add a new integration.
- The new credentials must belong to the same Halo tenant. Oleria refuses credentials from a different tenant.
Remediation actions
Oleria can take these actions in Halo. Each one runs as the API application’s log-in agent, and Oleria checks that the agent is still an administrator before it runs.
Keep these limits in mind when you use these actions:
- Oleria reads the account, role, group, or application before it changes it. If it’s already in the requested state, the action makes no change, and reverting it makes no change either.
- Oleria sends each change once, then reads it again to confirm. If Halo’s response is lost and the change doesn’t show when Oleria reads it again, the action fails and reports that the change may have been applied. Check Halo before you run the action again.
- Oleria refuses to disable, delete, revoke the sessions of, or change the roles or groups of the integration’s own log-in agent, and refuses to disable the integration’s own API application. These changes would disconnect the integration.
- Oleria refuses to disable Halo’s system applications, to remove an agent’s last role, and to add a role or group that doesn’t exist in Halo. To remove an agent’s last role, assign another role first or disable the agent.
- Agents hold agent roles, and end users hold end-user roles. Team and department actions, Delete user, and Revoke user sessions apply to agents only. Oleria can’t delete end users.
- If an agent’s team or department membership comes from one of their roles, Remove user from group refuses it. Remove the role instead.
- If you sync users into Halo from Microsoft Entra ID (Azure AD) or Okta, the next sync may overwrite role changes made from Oleria.
- Create user doesn’t set a password. The new agent signs in with SSO or Halo’s password reset. If an agent with the same email address already exists, the action makes no change. Reverting Create user disables the agent instead of deleting it.
- Create group makes no change if a team with the same name already exists.
- Disable NHI applies only to API applications, API-only agents, and end users marked as service accounts. To disable another agent or end user, use Disable user. Tokens an API application already holds may keep working until they expire, which is up to an hour.
- Halo doesn’t expose session state, so Oleria confirms Revoke user sessions only from Halo’s response.
Known limitations
- No activity. Halo has no identity audit or sign-in API, so Oleria doesn’t import activity. Each account’s last login is still shown.
- No last password change. Halo doesn’t report when an agent or end user last changed their password.
- Team and department nesting shows Halo’s structure. Oleria shows each team inside its department, as Halo organizes them. Halo doesn’t document whether a department’s access extends to the members of its teams, so confirm in Halo before you act on access that comes only through the nesting.
- SSO is never shown as required. Halo login stays available alongside SSO, so Oleria shows SSO as configured, not required. MFA shows as unavailable if the log-in agent can’t read the tenant’s security settings.
- No API application owners or credential dates. Halo’s API doesn’t report who created an API application, or when a credential was created, expires, or was last used.
- Webhook, runbook, and connector secrets aren’t imported.
- HaloPSA and HaloCRM. HaloPSA and HaloCRM use the same API as HaloITSM, but Oleria offers only a HaloITSM tile. Their hosted domains, such as
halopsa.comandhalocrm.io, are treated as custom hosts and need an allowlist entry. Contact support@oleria.com. - Custom and on-premise hosts. Oleria connects to hosts under
haloitsm.comandhaloservicedesk.com. A custom domain or on-premise Halo host needs an allowlist entry for that exact host first. Contact support@oleria.com. Hosts that resolve to private or loopback addresses can’t be connected. - Rate limits. Halo limits API requests per tenant, and your other Halo integrations share that limit. Oleria paces its requests to leave room for them, and during a sync it waits and retries when Halo reports the limit is reached. Actions aren’t retried: if an action reports the rate limit, run it again later. A tenant with many end users takes longer to sync, about an hour for every 100,000 end users.
- End-user roles on large tenants. If Halo doesn’t include end users’ roles when it lists them, Oleria reads them one end user at a time, for up to 2,000 end users per sync. Role memberships of further end users aren’t shown.