--- title: "Configure a generic REST ITSM connection" slug: "how-to-configure-a-generic-rest-itsm-integration-in-segura" updated: 2026-11-06T02:14:02Z published: 2026-11-06T02:14:02Z canonical: "docs.senhasegura.io/how-to-configure-a-generic-rest-itsm-integration-in-segura" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt > Use this file to discover all available pages before exploring further. # Configure a generic REST ITSM connection Segura™ Platform can require a ticket from your ITSM before it grants privileged access. When your ITSM has no dedicated integration, add a generic REST connection instead: you describe the endpoint, the authentication, and how to read the response, and the platform validates tickets against it with no development work. ## Requirements - An administrator profile. Only administrators can create, edit, test, and disable ITSM connections. - An ITSM that exposes its tickets through a REST or OData API and answers in JSON. XML responses are not supported. - The base URL of that API, served over HTTPS. - Authentication data for one of the supported methods: OAuth 2.0 Client Credentials, API key, session token, composite token, or Basic (user + password). - The number of a real ticket you can use to test the configuration. Attention The certificate presented by the ITSM endpoint must be trusted by the appliance, and it must be installed on every node of the cluster. The health probe runs on any node, so a certificate installed on only some of them produces intermittent unreachable results on a connection that tests and validates correctly. ## Steps The form is a wizard with six tabs: **General**, **Authentication**, **Query**, **Behavior**, **Fallback**, and **Review**. Click **Continue** to move between them. 1. On Segura™ Platform, in the navigation bar, hover over the **Products** menu and select **Settings**. 2. In the side menu, select **Integrations > ITSM > ITSM Connections**. 3. In the **ITSM Connections** report, in the top bar, click **+ Add**. 4. In the **Registration of integration with ITSM** screen, select **Generic REST**. 5. On the **General** tab, complete the following fields: - **Connection name** *: identifies the connection in Segura™ Platform and must be unique. Requesters also see this name when they choose an ITSM source at access time. - **Instance URL** *: the base URL of the ITSM API. It must start with `https://`. Plain HTTP is refused, including in laboratory and homologation environments. - **Status**: turn it on to make the connection available for validation. - **Tenant default connector**: turn it on to make this the connection used when the requester does not choose one and no access policy defines one. Only one connection per tenant can be the default. - **Description**: free text for your own records. It does not affect validation. 6. Click **Continue**. 7. On the **Authentication** tab, select the **Authentication method** *. The options are **OAuth 2.0 Client Credentials**, **API key**, **Session token**, **Composite token**, and **Basic (user + password)**. 8. Complete the fields the selected method displays: - **OAuth 2.0 Client Credentials**: **Client ID** and **Client Secret**. Complete **Token URL** when a separate identity server issues the tokens, such as Microsoft Entra ID, Keycloak, or Okta, and **Scope** when the provider requires the request to declare what the token is for. Use **Client credentials delivery** to send the credentials in the request body or in an HTTP header. - **API key**: **Secret** for the key itself, and **Authentication header** for the header that carries it. - **Session token**: **Login path** for the endpoint that issues the token, and **Token field in response** for where the token sits in the answer. - **Composite token**: **Value template**, which assembles the credential from its parts. - **Basic (user + password)**: **Username** and **Password**. The username cannot contain a colon (`:`). The platform sends both on every request. Prefer **OAuth 2.0 Client Credentials** or **API key** when the ITSM supports them. 9. Click **Continue**. 10. On the **Query** tab, describe how the platform finds the ticket: - **HTTP method**: **GET** or **POST**. - **Query template** *: the request that retrieves the ticket. Write `{ticket_id}` where the ticket number belongs, for example `tickets?filter=number eq '{ticket_id}'`. `{ticket_id}` is the only placeholder available. - **Body template (POST)**: the JSON payload to send. It appears only when the method is **POST**. - **Response list path**: the path to the node that carries the ticket records, for example `value` or `result`. 11. In **Approval rule**, define when a ticket counts as approved: - **Non empty response approves**: any record the query returns approves the request. - **Field equals value**: complete **Approval field** with the response field that carries the approval state, and **Approved value** with the value that means approved. 12. To deny access outside a validity window, complete the following fields: - **Validity start field** and **Validity end field**: the response fields that hold the start and the end of the window. Set both or neither. - **Validation timezone** *: the timezone used to read those fields. Segura™ Platform stores dates in UTC and converts them with this setting, so the result can differ from the local clock of whoever is testing near midnight. - **Date format** *: the format the ITSM returns. Select **Other format...** to enter a mask in **Custom format**. With a date-only format, the end of the window is inclusive through 23:59:59 of that day. 13. To check who asked for access and what they are accessing, turn on the corresponding rule and name the response field that carries the value: Info Leave **Require target = device/account** off when no field in the ITSM response carries a host. A field holding something else, such as a site or building name, never matches a device or a credential, so every request would be denied. - **Require requester = user**, then complete **Requester field (response)**. - **Require target = device/account**, then complete **Target field (response)**. The value must match the device IP address or hostname, or the credential username. 14. When the approval state is not returned together with the ticket, turn on **Second approval call** and complete **Second call path**, **Approval field (second call)**, and **Approved value (second call)**. 15. Click **Continue**. 16. On the **Behavior** tab, adjust the network settings: - **Connect timeout (seconds)**: how long to wait to establish the connection. Default: 10. - **Read timeout (seconds)**: how long to wait for the ITSM to answer. Default: 30. - **Maximum retries**: how many times to retry after a communication failure. Default: 3. - **Validation cache TTL (seconds)**: how long a validation result is reused before the platform queries the ITSM again. Default: 60. - **Health check interval (minutes)**: how often the health probe runs. Default: 5. 17. Click **Continue**. 18. On the **Fallback** tab, select the **Fallback behavior** to apply when the ITSM cannot be reached: - **Deny access when ITSM is unreachable**: no access is granted. Recommended. - **Allow only emergency / break-glass access**: access is granted only through the emergency procedure. - **Allow access and log for later audit**: access is granted and the event is recorded for review. 19. Click **Continue**. 20. Return to the **Query** tab and test the configuration before saving: - **Test ticket**: the number of a real ticket. - **Test user (requester)**: the user name to test with, when the requester rule is on. - **Sample IP (test)** and **Sample target user (test)**: the values to test with, when the target rule is on. - Click **Test connection**. 21. Read the result. A green **Would APPROVE this ticket** means the query succeeded and every condition was met. A red **Would DENY this ticket** means the request returned data but a check failed, for example a requester that does not match. The test runs the same pipeline as a real validation, including the second approval call when you configured one, but it saves nothing and writes no log entry. 22. Go to the **Review** tab, review the configuration, and click **Save**. ## Make the connection available A saved connection is used according to how each request resolves its source. Besides **Tenant default connector** on the **General** tab, you can pin a connection to a single access policy: in the access policy's **Approvers** tab, select it in the **ITSM connection** field. That takes precedence over the tenant default for that policy. Attention While more than one connection is active and none of them is the default, Segura™ Platform validates the ticket against every active connection and grants access when any one of them approves. The **ITSM Connections** screen shows a persistent warning while this applies. Setting a default ends it, and a request that another connection used to approve can start being denied. See [Generic REST ITSM connection settings](/v4-2/docs/reference-generic-rest-itsm-connector-settings) for the full resolution order. ## Related topics - [Generic REST ITSM connection settings](/v4-2/docs/reference-generic-rest-itsm-connector-settings) - [About Segura™'s ITSM integration](/v4-2/docs/about-senhaseguras-itsm-integration)