This document provides information about the generic REST ITSM connection, which lets Segura® Platform validate access tickets against any ITSM that exposes a REST or OData API. It covers the fields of the connection form and how validation behaves once the connection is in use. More information in Configure a generic REST ITSM connection.
Path to access
- On Segura® Platform, in the navigation bar, hover over the Products menu and select Settings.
- In the side menu, select Integrations > ITSM > ITSM Connections.
- In the top bar, click + Add, then select Generic REST.
General
Identifies the connection, points it at the ITSM API, and sets whether it is the tenant default.
| Item | Type | Required | Description |
|---|---|---|---|
| Connection name | Text field | Yes | Identifies the connection in Segura Platform and must be unique in the tenant. Requesters see this name when they choose an ITSM source at access time. |
| Instance URL | Text field | Yes | Base URL of the ITSM REST or OData API. Must start with https://. The platform refuses plain HTTP unconditionally, including in laboratory and homologation environments, and validates the URL format inline. |
| Status | Toggle button | No | Makes the connection available for validation. Only active connections are used to validate tickets and only active connections appear in the ITSM source selector. |
| Tenant default connector | Toggle button | No | Makes this the connection used when the requester does not select a source and no access policy defines one. Only one connection per tenant can hold this flag. |
| Description | Text field | No | Free text for internal record-keeping. It does not affect validation. |
Authentication
| Item | Type | Required | Description |
|---|---|---|---|
| Authentication method | Dropdown menu | Yes | Selects how the platform authenticates against the ITSM API, and determines which fields the tab displays. The options are OAuth 2.0 Client Credentials, API key, Session token, and Composite token. Basic (user + password) also appears in the list, but it is disabled and cannot be selected for a generic REST connection. |
OAuth 2.0 Client Credentials
The platform requests a temporary token once, then sends only that token on each ticket query, renewing it when it expires. Leave Token URL and Scope empty to keep the behavior of a ServiceNow-style instance, which issues tokens from a fixed path inside the instance itself.
| Item | Type | Required | Description |
|---|---|---|---|
| Client ID | Text field | Yes | Identifier of the application registered in the token provider. |
| Client Secret | Text field | Yes | Secret of that application. It is stored in the vault and never appears in the saved configuration. Editing a connection without retyping it keeps the stored value. |
| Token URL | Text field | No | Address that issues the token. Complete it when a separate identity server issues tokens, such as Microsoft Entra ID, Keycloak, or Okta, instead of the ITSM instance. |
| Scope | Text field | No | Declares what the token is for. Some providers refuse to issue a token when the request omits it. |
| Client credentials delivery | Dropdown menu | No | Whether the client identifier and secret travel in the request body or in an HTTP header. The OAuth specification allows both, and some providers accept only one. |
When the provider does not issue the token, the platform records an authentication failure in the diagnostic logs and reproduces the provider's own error message — read that message before suspecting the query configuration.
The OAuth 2.0 resource owner password credentials grant, in which the application also sends the user name and password of a service account, is not supported. It appears in older ServiceNow and Ivanti integrations, and modern OAuth guidance discourages it. A provider that accepts only that grant cannot be used with a generic REST connection.
API key
| Item | Type | Required | Description |
|---|---|---|---|
| Secret | Text field | Yes | The API key itself. Stored in the vault. |
| Authentication header | Text field | Yes | Name of the HTTP header that carries the key. |
Session token
| Item | Type | Required | Description |
|---|---|---|---|
| Login path | Text field | Yes | Endpoint that issues the session token, relative to the instance URL. |
| Token field in response | Text field | Yes | Path to the token in the login response. |
Composite token
| Item | Type | Required | Description |
|---|---|---|---|
| Value template | Text field | Yes | Template that assembles the credential value from its parts. The real secret lives in the vault and is referenced by the template rather than stored in the configuration. |
Query
Describes the request that retrieves the ticket and how to read the answer.
Ticket lookup
| Item | Type | Required | Description |
|---|---|---|---|
| HTTP method | Dropdown menu | Yes | Method used for the ticket query. The options are GET and POST. |
| Query template | Text field | Yes | Request that retrieves the ticket, relative to the instance URL. Write {ticket_id} where the ticket number belongs. Example: tickets?filter=number eq '{ticket_id}'. |
| Body template (POST) | Text field | No | JSON payload sent with the request. It appears only when HTTP method is POST. |
| Response list path | Text field | No | Path to the node that carries the ticket records, applied before any field is read. Example: value or result. Leave it empty when the payload is a flat object at the root. |
{ticket_id} is the only placeholder a generic REST connection accepts.
Approval
| Item | Type | Required | Description |
|---|---|---|---|
| Approval rule | Dropdown menu | Yes | Decides when a returned ticket counts as approved. Non empty response approves: any record the query returns approves the request. Field equals value: a field in the response must carry a specific value. |
| Approval field | Text field | Conditional | Response field that carries the approval state. Required when Approval rule is Field equals value. |
| Approved value | Text field | Conditional | Value of that field which means approved. Required when Approval rule is Field equals value. |
| Second approval call | Toggle button | No | Queries a second endpoint for the approval state, for ITSMs that do not return it with the ticket. |
| Second call path | Text field | Conditional | Endpoint of the second call. Required when Second approval call is on. |
| Approval field (second call) | Text field | Conditional | Response field of the second call that carries the approval state. |
| Approved value (second call) | Text field | Conditional | Value of that field which means approved. |
[NEEDS CLARIFICATION: the product specification also lists configurable request headers and query
filters for the ticket query. Neither appears in the record of the shipped form. Confirm whether they
exist and, if so, under which labels.]
Validity window
Denies access outside a window the ITSM returns with the ticket. Set both field names or neither.
| Item | Type | Required | Description |
|---|---|---|---|
| Validity start field | Text field | No | Response field that holds the start of the window. |
| Validity end field | Text field | No | Response field that holds the end of the window. |
| Validation timezone | Dropdown menu (IANA timezone) | Yes | Timezone used to read the date and time fields of the response. Segura Platform stores dates in UTC and converts them with this setting, so a validation near midnight can differ from the local clock of whoever is testing. |
| Date format | Dropdown menu | Yes | Format the ITSM returns for those fields. Select Other format... to supply a mask in Custom format. |
| Custom format | Text field | Conditional | Format mask, for example d.m.Y or Y-m-d H:i:s. Required when Date format is Other format.... |
Requester and target checks
Each check is optional and needs the response field that carries the value.
| Item | Type | Required | Description |
|---|---|---|---|
| Require requester = user | Toggle button | No | Compares the Segura Platform user against a field of the ticket. |
| Requester field (response) | Text field | Conditional | Response field holding the requester. Required when the toggle is on. |
| Require target = device/account | Toggle button | No | Compares the access target against a field of the ticket. Leave it off when no response field carries a host: a field holding something else, such as a site or building name, never matches, so every request is denied. |
| Target field (response) | Text field | Conditional | Response field holding the target. Required when the toggle is on. The value must match the device IP address or hostname, or the credential username. |
Connection test
Runs before saving, from the bottom of the Query tab.
| Item | Type | Required | Description |
|---|---|---|---|
| Test ticket | Text field | No | Number of a real ticket used by the test and by the periodic health probe. Without it, the health probe measures only whether the endpoint answers — any HTTP response counts as reachable, so broken authentication still reports as healthy. |
| Test user (requester) | Text field | No | User name the test uses when the requester check is on. |
| Sample IP (test) | Text field | No | IP address the test uses when the target check is on. |
| Sample target user (test) | Text field | No | Target user name the test uses when the target check is on. |
| Test connection | Button | — | Runs the same pipeline as a real validation, including the second approval call when one is configured. It saves nothing and writes no log entry. The result appears inline: a green Would APPROVE this ticket when the query succeeded and every condition was met, or a red Would DENY this ticket when the request returned data but a check failed. |
Behavior
Network settings for the connection. Each one ships with a default, so the tab can be left untouched.
| Item | Type | Default | Description |
|---|---|---|---|
| Connect timeout (seconds) | Number field | 10 | How long the platform waits to establish the connection. |
| Read timeout (seconds) | Number field | 30 | How long the platform waits for the ITSM to answer. |
| Maximum retries | Number field | 3 | How many times the platform retries after a communication failure. |
| Validation cache TTL (seconds) | Number field | 60 | How long a validation result is reused before the platform queries the ITSM again. |
| Health check interval (minutes) | Number field | 5 | How often the health probe runs against the connection. |
Fallback
What the platform does when the ITSM cannot be reached.
| Item | Type | Required | Description |
|---|---|---|---|
| Fallback behavior | Radio button | Yes | The options are Deny access when ITSM is unreachable (no access is granted — the recommended setting), Allow only emergency / break-glass access (access only through the emergency procedure), and Allow access and log for later audit (access is granted and recorded for review). |
There is no fail-open option. An access policy can override this choice for itself, in Fallback behavior (override) on its Approvers tab.
How validation runs
Validation checks
Each check is fail-closed: a check that cannot be satisfied denies access rather than passing.
| Check | What it verifies |
|---|---|
| Validity window | The current date and time fall inside the window the ticket returns. |
| Approval | The response satisfies the connection's approval rule. |
| Requester | The ticket names the user requesting access. |
| Target | The ticket names the device or account being accessed. |
Segura Platform queries the ITSM read-only. It never opens, updates, or closes a ticket.
Response handling
| Item | Description |
|---|---|
| Response format | JSON only. XML responses are not supported. |
| Multiple records | When the query returns several records, the request is approved if a single record passes every enabled check on its own. Fields are never combined across records. |
| Value comparison | Approval, requester, and target comparisons ignore letter case and leading or trailing spaces. |
| Field names | Field names taken from the ITSM response are treated as opaque strings and are never translated. |
| Requester message | A denied requester sees a generic message stating that the ticket is invalid or unauthorized. Details of the ITSM response go to the connection diagnostic log and are not shown to the requester. |
Not found is not a failure
A ticket the ITSM does not return is a normal outcome, not an error. Only a failure triggers the fallback behavior:
| ITSM answer | Result |
|---|---|
| Empty response, 204, 400, or 404 | Ticket not found — access denied. |
| 401, 403, 429, 5xx, or a timeout | Failure — the fallback behavior applies, and the diagnostic log records the identified cause. |
Validity window and timezone
The validity window is read in the timezone set in Validation timezone, not the timezone of the appliance or of the requester. With a date-only format, the end of the window is inclusive through 23:59:59 of that day, so a ticket valid until 28 July is denied only on 29 July.
Validation cache
A repeated validation of the same ticket within Validation cache TTL (seconds) reuses the previous result instead of querying the ITSM again. Two consequences are worth knowing:
- Authorization can be slightly stale. A ticket closed or revoked in the ITSM during the cache window is still validated with the cached result.
- The validation log records one entry per access, as always, but the connection diagnostic log records no line for a cached result, because no request left the platform. An approval with no matching diagnostic line is expected, not a missing record.
Which connection validates a request
When more than one ITSM connection is active, one connection decides the outcome and its answer is final. Segura Platform resolves which one on every validation, in this order:
- The connection pinned for the requester's access group. When an administrator pins a source, it wins over everything else: the requester cannot change it, and a source sent with the request anyway is ignored.
- The source the requester selects in the justification form, offered only when the access group is not pinned.
- The connection with Tenant default connector turned on.
- The only active connection, when exactly one exists and no default is set.
- Compatibility mode, when none of the above resolves.
Notes on the requester's selection:
- The selector appears only in the web justification form and only when more than one connection is active. Terminal proxy sessions, EPM, and API calls always resolve through the automatic order above.
- The selector lists active connections only, using the name each connection was given.
- The selection is not stored with the justification. It applies to that validation alone.
- In an access group that is not pinned, the requester may select any active connection, including one more permissive than the default. To tie a group to a single source, pin it; to stop a source from being used at all, turn its Status off.
- If a connection is deactivated after being chosen, the justification form returns an error asking for another source. If a pinned connection is deactivated, the pin is ignored and resolution continues from the next step.
Compatibility mode
While more than one connection is active and none has Tenant default connector turned on, 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.
This preserves the outcome of environments that ran multiple connections before connection resolution existed, so no environment changes behavior on upgrade without an administrator acting. Turning on Tenant default connector ends compatibility mode; turning it off again while more than one connection is active restores it.
Setting a default can change the outcome of requests that compatibility mode used to approve: a ticket that was valid in another connection is now evaluated only by the connection that resolution selects, and can be denied. Confirm which source should decide before setting the default.
While compatibility mode applies, one access produces one request per active connection, so the connection diagnostic logs record one line per connection. The validation log still records a single entry for the access.