> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OTRS

Oleria provides identity security and access management teams with visibility and intelligence into who has access to what, where they got that access, how they use it, and whether they should even have it. As part of that promise, we deeply integrate your OTRS (or Znuny) instance into the Oleria platform. This document provides step-by-step guidance for integrating OTRS with your Oleria workspace.

A single Oleria connection covers your **entire OTRS instance** - Oleria discovers every agent, group, and role the connection can reach.

## Prerequisites

* An **OTRS or Znuny instance** reachable over HTTPS, with the GenericInterface framework enabled.
* An **OTRS administrator** who can configure a GenericInterface webservice and generate a Bearer token.
* Optional, for ticket activity: a dedicated **ticket agent** login and password. This is a separate, session-based webservice from the Bearer-token webservice used for everything else.

<Note>Use a dedicated service agent (not a named employee account) for both the Bearer token and the optional ticket agent credentials, so the integration keeps working through personnel changes.</Note>

## What Oleria discovers

| Area               | Detail                                                                                                                                                      |
| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Users**          | Agents (OTRS's internal users) as Accounts.                                                                                                                 |
| **Groups & Roles** | OTRS groups (as UserGroups) and roles, with per-agent membership and role assignment.                                                                       |
| **Activity**       | Ticket history events (`TicketHistoryGet`), when ticket agent credentials are provided. Without them, activity data is empty; all other data is unaffected. |
| **Risk signals**   | Standard posture signals derived from agent, group, and role membership.                                                                                    |

## Set up the integration

OTRS authentication uses a **Bearer token** for the Agent/Group/Role webservice, and (optionally) a separate **session-based login** for ticket history.

<Steps>
  <Step title="Generate a Bearer token for the Agent/Group/Role webservice">
    In your OTRS admin panel, configure the GenericInterface webservice that exposes the Agent, Group, and Role operations Oleria calls, and generate a **Bearer token** for it. Consult your OTRS/Znuny administration documentation for your version - token generation is done through the admin UI or the underlying Perl API, not through a customer-facing page.

    Copy the token - you will enter it in Oleria.
  </Step>

  <Step title="Create a ticket agent for activity (optional)">
    If you want Oleria to collect ticket activity, create (or designate) an agent OTRS can authenticate with a login and password against the Ticket GenericInterface webservice. This webservice authenticates by session (login and password), not by the Bearer token from Step 1.

    <Note>Ticket agent login and password are optional and independent of the Bearer token. Provide both together or leave both blank - a login without a password (or vice versa) is rejected.</Note>
  </Step>
</Steps>

## Connect OTRS to Oleria

<Steps>
  <Step title="Open the integration">
    Go to your Oleria workspace, select **Integrations** -> select **OTRS**.
  </Step>

  <Step title="Complete the connection form">
    Select **Continue** and fill in the connection form:

    | Field                                | Notes                                                                                                                                                                                                                                                                                                              |
    | :----------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Instance URL**                     | Your OTRS instance's HTTPS base URL (for example `https://otrs.example.com`). We recommend a bare host URL with no path; if a path is included, it will be preserved and appended to — which may produce an incorrect endpoint if your webservice is not mounted there. No query string or credentials in the URL. |
    | **API Token**                        | Required. The Bearer token from Step 1.                                                                                                                                                                                                                                                                            |
    | **Ticket Agent Login** (optional)    | The ticket agent's login from Step 2. Required only if you want activity data.                                                                                                                                                                                                                                     |
    | **Ticket Agent Password** (optional) | The ticket agent's password from Step 2. Required only if you want activity data.                                                                                                                                                                                                                                  |
  </Step>

  <Step title="Save the integration">
    Select **Authenticate** to validate and save the integration.
  </Step>
</Steps>

## Verify the integration

Confirm OTRS appears in your Oleria workspace connected integrations. After the first sync completes, you can review the discovered agents, groups, and roles in your Oleria workspace. If ticket agent credentials were provided, ticket activity appears alongside them.

## Supported remediation actions

| Action                      | What it does                                                                                         |
| :-------------------------- | :--------------------------------------------------------------------------------------------------- |
| **Create user**             | Creates a new agent. The agent is created inactive unless the action explicitly requests activation. |
| **Enable user**             | Activates a previously disabled agent.                                                               |
| **Disable user**            | Deactivates an agent.                                                                                |
| **Add / Remove from group** | Grants or removes the agent's read-write membership in the selected group.                           |
| **Assign / Remove role**    | Assigns or removes the selected role for the agent.                                                  |

## Notes and limitations

* **Activity is optional:** ticket history requires the ticket agent credentials from Step 2. Without them, Oleria still collects agents, groups, and roles normally.
* **Group hierarchy** is inferred from group naming conventions, not a native OTRS parent/child relationship.
* **No dynamic tenant discovery:** one connection maps to exactly one OTRS instance.
* **No bulk operations:** remediation actions operate on one agent at a time.
* **No group-scoped roles:** OTRS roles are assigned instance-wide, not per group.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).