Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 5.7.0 - REST API Reference Guide

Introduction Using the Safeguard for Privileged Sessions REST API Basic settings User management and access control Managing Safeguard for Privileged Sessions General connection settings HTTP connections Citrix ICA connections RDP connections SSH connections Telnet connections VNC connections Search, download, and index sessions Reporting Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST About us Third-party contributions

Credential stores

Credential Stores offer a way to store user credentials (for example, passwords, private keys, certificates) and use them to login to the target server, without the user having access to the credentials. That way, the users only have to perform gateway authentication on Safeguard for Privileged Sessions with their usual password (or to an LDAP database), and if the user is allowed to access the target server, Safeguard for Privileged Sessions automatically logs in using the Credential Store.

URL
GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/credentialstores
Headers
Header name Description Required Values
session_id Contains the authentication token of the user Required

The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format).

Sample request

The following command lists the credential stores.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/credentialstores

The following command retrieves the properties of a specific credential store.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/policies/credentialstores/<policy-id>
Response

The following is a sample response received when listing credential stores. For details of the meta object, see Introduction.

{
  "items": [
    {
      "key": "1580973975727acedd51b2",
      "meta": {
        "href": "/api/configuration/policies/credentialstores/1580973975727acedd51b2"
      }
    },
    {
      "key": "935272738572bc2ec1dbdd",
      "meta": {
        "href": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/credentialstores",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/indexing",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/content_policies",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific credential store, the response is the following.

{
  "body": {
    "name": "API_LIEBERMANN",
    "type": {
      "authenticator_name": "auth_server_name",
      "default_namespace": "{HOST}",
      "dns_servers": {
        "primary": "192.168.56.1",
        "secondary": "192.168.56.2"
      },
      "domain_mappings": [
        {
          "domain": "domain",
          "host": {
            "selection": "fqdn",
            "value": "host"
          }
        }
      ],
      "login_mode": {
        "password": {
          "key": "e0ecbe98-bd17-4805-ba5d-17fb789f3971",
          "meta": {
            "href": "/api/configuration/passwords/e0ecbe98-bd17-4805-ba5d-17fb789f3971"
          }
        },
        "selection": "fixed",
        "username": "fixed_username"
      },
      "proxy_server": "http://192.168.56.201:9999",
      "selection": "lieberman",
      "server_certificate_check": {
        "enabled": true,
        "trusted_ca": {
          "key": "12269547065727ad6e79d9e",
          "meta": {
            "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e"
          }
        }
      },
      "web_interface_url": "http://erpm_address"
    }
  },
  "key": "935272738572bc2ec1dbdd",
  "meta": {
    "first": "/api/configuration/policies/credentialstores/1580973975727acedd51b2",
    "href": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd",
    "last": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd",
    "next": null,
    "parent": "/api/configuration/policies/credentialstores",
    "previous": "/api/configuration/policies/credentialstores/1580973975727acedd51b2",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key string Top level element, contains the ID of the credential store.
body Top level element (string) The configuration elements of the credential store.
name string The name of the credential store. This name is also displayed on the Safeguard for Privileged Sessions web interface. It cannot contain whitespace.
type Top level item All elements for the configured type of credential store.
authenticator_name string If your ERPM setup is configured to use an external authentication method, enter the name of the Authentication Server (Authenticator Source) set on your ERPM server. If empty, Safeguard for Privileged Sessions uses the [Explicit] authenticator.
default_namespace string The default namespace of the accounts (for example, [Linux], [LDAP], [IPMI], W2003DOMAIN).
dns_servers Top level item The IP addresses of the DNS servers to use for resolving the hostnames provided in domain_mappings.
domain_mappings Top level list

Use for RDP connections only. In a domainless environment, use default_namespace.

To retrieve the password of a domain user from Lieberman ERPM, Safeguard for Privileged Sessions queries the domain controller directly. This element contains the necessary Domain/Host mappings.

encryption Top level item Configures the encryption key for the local credential store.
login_mode Top level item Configures the account Safeguard for Privileged Sessions uses to login to the ERPM server.
plugin string

Must be used if the selection element is set to external_plugin.

References the Credential Store plugin. You can find the list of available plugins at the /api/configuration/plugins/credentialstore/ endpoint.

To modify or add a plugin, use the value of the returned key as the value of the plugin element, and remove any child elements (including the key).

Plugins can only be uploaded using the web interface of Safeguard for Privileged Sessions.

proxy_server string The IP address and port of the proxy server. Use the http:// or https:// prefix.
selection string

Configures the type of the credential store. Possible values are:

server_certificate_check Top level item To verify the certificate of the ERPM server, configure server_certificate_check.
web_interface_url string Name of the DN of the ERPM server. Use the http:// or https:// prefix.
Elements of dns_servers Type Description
primary string The IP address of the primary DNS server.
secondary string The IP address of the secondary DNS server.
Elements of domain_mappings Type Description
domain string The domain name used for Domain/Host mapping.
host Top level item The host name or address of the domain controller used for Domain/Host mapping.
selection string

Declares if the value element contains an IP or an FQDN. Possible values are:

  • fqdn

    The value element contains a hostname.

  • ip

    The value element contains an IP.

value string The IP address or hostname of the domain controller.
Elements of encryption Type Description
selection string

Defines the encryption of the local credential store. Possible values are:

  • basic

    The local credential store uses the built-in protection of Safeguard for Privileged Sessions.

  • password

    The local credential store is protected by one or more passwords.

Elements of login_mode Type Description
password string

Must be used if the selection element is set to fixed_username.

References the password Safeguard for Privileged Sessions uses to authenticate on the ERPM server. You can configure passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

selection string

Possible values are:

  • fixed_username

    Safeguard for Privileged Sessions uses a fix username and password.

    Requires the username and password elements.

  • gateway_auth_credentials

    Safeguard for Privileged Sessions uses the username and password that the user provided during the gateway authentication process.

    Can only be used for SSH connections.

username string

Must be used if the selection element is set to fixed_username.

The username Safeguard for Privileged Sessions uses to authenticate on the ERPM server.

Elements of server_certificate_check Type Description
enabled boolean Set to true to verify the ERPM server's certificate.
trusted_ca string

Must be used if server certificate checking is enabled.

References the list of trusted Certificate Authorities. You configure trusted CAs at the /api/configuration/policies/trusted_ca_lists/ endpoint.

To reference a trusted CA list, use the value of the returned key as the value of the trusted_ca element, and remove any child elements (including the key).

Examples:

NOTE:

The following examples are responses only. Credential stores can only be configured using the web interface of Safeguard for Privileged Sessions.

Use a Lieberman ERPM server, configure domain mapping and provide the host address as an IP, reuse the gateway login credentials of the user to access the ERPM server, and do not verify the server's certificate.

{
  "name": "API_LIEBERMANN",
  "type": {
    "authenticator_name": "auth_server_name",
    "default_namespace": "{HOST}",
    "dns_servers": {
      "primary": "192.168.56.1",
      "secondary": "192.168.56.2"
    },
    "domain_mappings": [
      {
        "domain": "domain",
        "host": {
          "selection": "ip",
          "value": "192.168.56.1"
        }
      }
    ],
    "login_mode": {
      "selection": "gateway_auth_credentials"
    },
    "proxy_server": "http://192.168.56.201:9999",
    "selection": "lieberman",
    "server_certificate_check": {
      "enabled": false
    },
    "web_interface_url": "https://erpm_address"
  }
}

Change the host address to a hostname for domain mapping, and verify the server's certificate.

{
  "name": "API_LIEBERMANN",
  "type": {
    "authenticator_name": "auth_server_name",
    "default_namespace": "{HOST}",
    "dns_servers": {
      "primary": "192.168.56.1",
      "secondary": "192.168.56.2"
    },
    "domain_mappings": [
      {
        "domain": "domain",
        "host": {
          "selection": "fqdn",
          "value": "host"
        }
      }
    ],
    "login_mode": {
      "selection": "gateway_auth_credentials"
    },
    "proxy_server": "http://192.168.56.201:9999",
    "selection": "lieberman",
    "server_certificate_check": {
      "enabled": true,
      "trusted_ca": {
        "key": "12269547065727ad6e79d9e",
        "meta": {
          "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e"
        }
      }
    },
    "web_interface_url": "https://erpm_address"
  }
}

Use a fixed username to access the Lieberman ERPM server.

{
  "name": "API_LIEBERMANN",
  "type": {
    "authenticator_name": "auth_server_name",
    "default_namespace": "{HOST}",
    "dns_servers": {
      "primary": "192.168.56.1",
      "secondary": "192.168.56.2"
    },
    "domain_mappings": [
      {
        "domain": "domain",
        "host": {
          "selection": "fqdn",
          "value": "host"
        }
      }
    ],
    "login_mode": {
      "password": {
        "key": "e0ecbe98-bd17-4805-ba5d-17fb789f3971",
        "meta": {
          "href": "/api/configuration/passwords/e0ecbe98-bd17-4805-ba5d-17fb789f3971"
        }
      },
      "selection": "fixed",
      "username": "fixed_username"
    },
    "proxy_server": "http://192.168.56.201:9999",
    "selection": "lieberman",
    "server_certificate_check": {
      "enabled": true,
      "trusted_ca": {
        "key": "12269547065727ad6e79d9e",
        "meta": {
          "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e"
        }
      }
    },
    "web_interface_url": "http://erpm_address"
  }
}

Use a credential store plugin.

{
  "name": "API_PLUGIN",
  "type": {
    "plugin": {
      "key": "2534221015734bb18aaf32",
      "meta": {
        "href": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32"
      }
    },
    "selection": "external_plugin"
  }
}
Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Using the Safeguard for Privileged Sessions REST API.

Code Description Notes
401 Unauthenticated The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
404 NotFound The requested object does not exist.

Ticketing policies

Safeguard for Privileged Sessions provides a plugin framework to integrate Safeguard for Privileged Sessions to external ticketing (or issue tracking) systems, allowing you to request a ticket ID from the user before authenticating on the target server. That way, Safeguard for Privileged Sessions can verify that the user has a valid reason to access the server — and optionally terminate the connection if he does not. Requesting a ticket ID currently supports the following protocols:

  • Remote Desktop (RDP)

  • Secure Shell (SSH)

  • TELNET

  • TN3270

To request a plugin that interoperates with your ticketing system, contact the One Identity Support Team.

You can upload ticketing plugins using the web interface of Safeguard for Privileged Sessions. The API allows you to reference existing (uploaded) ticketing plugins, change the message prompts, and configure the validation of the provided ticket number.

URL
GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/ticketing_policies
Headers
Header name Description Required Values
session_id Contains the authentication token of the user Required

The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format).

Sample request

The following command lists ticketing policies.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/ticketing_policies

The following command retrieves the properties of a specific ticketing policy.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/ticketing_policies/<policy-id>
Response

The following is a sample response received when listing ticketing policies. For details of the meta object, see Introduction.

{
  "items": [
    {
      "key": "9816939765734be5978af1",
      "meta": {
        "href": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/ticketing_policies",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/time_policies",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/signing_cas",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific ticketing policy, the response is the following.

{
  "body": {
    "name": "API_ticketing_plugin",
    "plugin": {
      "key": "21425174515734bb223d197",
      "meta": {
        "href": "/api/configuration/plugins/ticketing/21425174515734bb223d197"
      }
    },
    "prompt": "Please enter ticket ID: ",
    "require_valid_ticket": true
  },
  "key": "9816939765734be5978af1",
  "meta": {
    "first": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1",
    "href": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1",
    "last": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1",
    "next": null,
    "parent": "/api/configuration/policies/ticketing_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key string Top level element, contains the ID of the ticketing policy.
body Top level element (string) Contains the properties of the ticketing policy.
name string The name of the policy. This name is also displayed on the Safeguard for Privileged Sessions web interface. It cannot contain whitespace.
plugin string

References the Ticketing plugin. You can find the list of available plugins at the /api/configuration/plugins/ticketing/ endpoint.

To modify or add a plugin, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

Plugins can only be uploaded using the web interface of Safeguard for Privileged Sessions.

prompt string The user prompt that is displayed in terminal connections (for example, "Enter the ticket ID:").
require_valid_ticket boolean Set to true to terminate the connection if the provided ticket number is invalid.
Add a ticketing policy

To add a ticketing policy, you have to:

  1. Open a transaction.

    For details, see Open a transaction.

  2. Upload a plug-in to use

    For details, see To upload or update a plugin, complete the following steps. Note that currently you cannot delete a plugin, only update it by uploading a new version.. You can find the list of uploaded plug-ins at the /api/configuration/plugins/ticketing/ endpoint.

  3. Create the JSON object for the new ticketing policy.

    Use the ticketing plugin's key as the value of the plugin element. You can find a detailed description of the available parameters listed in Ticketing policies.

    POST the JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/ticketing_policies endpoint. If the POST request is successful, the response includes the key of the new ticketing policy. For example:

    {
      "key": "aa423b72-0d0f-4275-be30-494e9a99ffad",
      "meta": {
        "href": "/api/configuration/policies/ticketing_policies/aa423b72-0d0f-4275-be30-494e9a99ffad",
        "parent": "/api/configuration/policies/ticketing_policies",
        "transaction": "/api/transaction"
      }
    }
  4. Commit your changes.

    For details, see Commit a transaction.

Modify a ticketing policy

To modify a ticketing policy, you have to:

  1. Open a transaction.

    For details, see Open a transaction.

  2. Find the plugin you want to modify

    You can find the list of available plugins at the /api/configuration/plugins/ticketing/ endpoint.

  3. Modify the JSON object of the ticketing policy.

    Use the ticketing plugin's key as the value of the plugin element. You can find a detailed description of the available parameters listed in Ticketing policies.

    PUT the modified JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/ticketing_policies/<key-of-the-object> endpoint.

  4. Commit your changes.

    For details, see Commit a transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Using the Safeguard for Privileged Sessions REST API.

Code Description Notes
201 Created The new resource was successfully created.
400 InvalidQuery The requested filter or its value is invalid.
401 Unauthenticated The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
404 NotFound The requested object does not exist.

Ticketing plugins

The ticketing plugins used on Safeguard for Privileged Sessions. To upload or update a plugin, see To upload or update a plugin, complete the following steps. Note that currently you cannot delete a plugin, only update it by uploading a new version..

URL
GET https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/plugins/ticketing
Headers
Header name Description Required Values
session_id Contains the authentication token of the user Required

The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format).

Sample request

The following command lists the ticketing plugins stored on Safeguard for Privileged Sessions..

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/plugins/ticketing

The following command retrieves the properties of a specific plugin.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/plugins/ticketing/<plugin-id>
Response

The following is a sample response received when listing ticketing plugins stored on Safeguard for Privileged Sessions. For details of the meta object, see Introduction.

{
  "items": [
    {
      "key": "21425174515734bb223d197",
      "meta": {
        "href": "/api/configuration/plugins/ticketing/21425174515734bb223d197"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/plugins/aa",
    "href": "/api/configuration/plugins/ticketing",
    "last": "/api/configuration/plugins/ticketing",
    "next": null,
    "parent": "/api/configuration/plugins",
    "previous": "/api/configuration/plugins/credentialstore",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific plugin, the response is the following.

{
  "body": {
    "api": "1.0",
    "description": "Demo ticketing plugin for demonstration purposes",
    "name": "DemoTicketingPlugin",
    "path": "/opt/scb/var/plugins/ticketing/DemoTicketingPlugin",
    "version": "0.0"
  },
  "key": "21425174515734bb223d197",
  "meta": {
    "first": "/api/configuration/plugins/ticketing/21425174515734bb223d197",
    "href": "/api/configuration/plugins/ticketing/21425174515734bb223d197",
    "last": "/api/configuration/plugins/ticketing/21425174515734bb223d197",
    "next": null,
    "parent": "/api/configuration/plugins/ticketing",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key string Top level element, contains the ID of the plugin.
body Top level element (string) Contains the properties of the plugin.
api string The API version of the plugin.
description string The description of the plugin. This description is also displayed on the Safeguard for Privileged Sessions web interface.
name string The name of the plugin. This name is also displayed on the Safeguard for Privileged Sessions web interface. It cannot contain whitespace.
path string The path where the plugin is stored on Safeguard for Privileged Sessions.
version string The version of the plugin.
Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Using the Safeguard for Privileged Sessions REST API.

Code Description Notes
401 Unauthenticated The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
404 NotFound The requested object does not exist.

Completing the Welcome Wizard using REST

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating