Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 7.0.5.1 LTS - REST API Reference Guide

Introduction Using the SPS REST API Basic settings User management and access control Managing SPS General connection settings HTTP connections Citrix ICA connections MSSQL connections RDP connections SSH connections Telnet connections VNC connections Search, download, and index sessions Reporting Health and maintenance Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST

Completing the Welcome Wizard using REST

The Welcome Wizard helps you complete the initial configuration of SPS. Starting with version 5 F4, you can complete the Welcome Wizard using REST as well.

URL
GET https://<IP-address-of-SPS>/api/setup
Prerequisites

You can complete the Welcome Wizard only if it has not been already completed. To verify this, access the /api/setup endpoint. If the value of the status field is uninitialized, you can complete the Welcome Wizard.

Sample request

The following command completes the Welcome Wizard. The data content of the request is read from the file body.json. For the details of the body of the request, see Request body.

curl -H "Content-Type: application/json" -d @body.json -X POST https://<IP-address-of-SPS>/api/setup/

NOTE: The request automatically fails if there are any other clients connected to the REST or the web interface of SPS.

Response

If completing the Welcome Wizard is successful, you should receive the 303 status code. The body of the response is empty.

If you GET the /api/setup endpoint, the status field of the response should be completed, for example:

{
    "meta": {
        "eula": "https://www.oneidentity.com/legal/sta.aspx",
        "href": "/api/setup",
        "parent": "/api",
        "remaining_seconds": 0
    },
    "status": "completed"
}
Request body
Element Type Description
accept_eula   boolean Indicates that you have read and accept the terms of the Software Transaction, License and End User License Agreements. Must be true to complete the Welcome Wizard.
network   JSON object Contains the initial networking configuration of SPS.
license   string

Your SPS license as a string. You can download your license from support portal. Example:

"license": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><LicenseFile><Licenses><License Generator=\"File\" GeneratorVersion=\"3.0\" Signature=\"FEEDCAFE\"><Enterprise>true</Enterprise><LicenseNumber>123-456-789</LicenseNumber><LicenseType>Perpetual</LicenseType><ProductName>Safeguard for Privileged Sessions</ProductName><ProductVersion>7</ProductVersion><Property Name=\"Basic Proxies\">999999</Property><sudo-iolog>0</sudo-iolog><Analytics>True</Analytics></License></Licenses></LicenseFile>"

Note that you can complete the Welcome Wizard without uploading a license. In this case, SPS will start in demo mode. To skip uploading the license, use the null value:

"license": null,

To upload a license file, see Upload a new license.

certificates   JSON object Contains the initial certificates used on SPS: the internal Certificate Authority, Timestamping Authority, and the SSL certificate of the web and REST interface. After completing the Welcome Wizard, you can manage these certificates at Internal certificates.
administration   JSON object

Contains the passwords of the root and admin users, for example:

"administration": {
                  "root_password": "asdgf-sdffe-aasc-oijernf",
                  "admin_password": "bd9r3-adedfk2-fsdf-fs"
              },
email   JSON object

Contains the SMTP server to use, and the e-mail address of the SPS administrator. For example:

"email": {
                  "smtp_server": "smtp.example.com",
                  "admin_email": "psm-administrator@example.com"
              },
datetime   JSON object

Contains the timezone of SPS and the address of an NTP server to use for date synchronization. For example:

"datetime": {
                  "timezone": "Europe/Budapest",
                  "primary_ntp_server": "time.test-domain"
              }
Element Type Description
network   JSON object The initial networking configuration of SPS.
  hostname string

Name of the machine running SPS. For example:

"hostname": "psm",
  domainname string

Name of the domain used on the network. For example:

"domainname": "example.com",
  initial_address IPv4 address/netmask

The IP address of interface 1 (or EXT, for older hardware) of SPS (for example, 192.168.1.1). The IP address can be chosen from the range of the corresponding physical subnet. Clients will connect to this interface, therefore it must be accessible to them. The IP prefix of the given range. For example, general class C networks have the /24 prefix.

"initial_address": "192.168.1.10/24",

Use an IPv4 address.

NOTE: Do not use IP addresses that fall into the following ranges:

  • 1.2.0.0/16 (reserved for communication between SPS cluster nodes)

  • 127.0.0.0/8 (localhost IP addresses)

  vlantag string

The VLAN ID of interface 1 (or EXT). Optional, use null if it is not set. For example:

"vlantag": null,

Caution:

Do not set the VLAN ID unless your network environment is already configured to use this VLAN. Otherwise, your SPS appliance will be unavailable using this interface.

  gateway IPv4 address

The IP address of the default gateway.

"gateway": "192.168.1.1",

Use an IPv4 address.

  primary_dns IPv4 address

The IP address of the name server used for domain name resolution.

"primary_dns": "192.168.1.1",

Use an IPv4 address.

Element Type Description
certificates   JSON object

The internal certificates of SPS.

TIP: One Identity recommends using 2048-bit RSA keys (or stronger).

For example:

"certificates": {
                  "ca": {
                      "certificate": "-----BEGIN CERTIFICATE-----\nMIIEWTCCA0GgAwIBAgIBAjANBgkqhkiG9w0BAQ0FADCBzDELMAkGA1UEBhMCUk8x\n...\n-----END CERTIFICATE-----\n"
                  },
                  "webserver": {
                      "certificate": "-----BEGIN CERTIFICATE-----\nMIIEWTCCA0GgAwIBAgIBAjANBgkqhkiG9w0BAQ0FADCBzDELMAkGA1UEBhMCUk8x\n...\n-----END CERTIFICATE-----\n",
                      "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEA/JERC+o1UksvUfbzS5Yp77CNlS6RkkdZLPjl2i9+ACzv/lOy\n...\n-----END RSA PRIVATE KEY-----\n"
                  },
                  "tsa": {
                      "certificate": "-----BEGIN CERTIFICATE-----\nMIIEWTCCA0GgAwIBAgIBAjANBgkqhkiG9w0BAQ0FADCBzDELMAkGA1UEBhMCUk8x\n...\n-----END CERTIFICATE-----\n",
                      "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEA/JERC+o1UksvUfbzS5Yp77CNlS6RkkdZLPjl2i9+ACzv/lOy\n...\n-----END RSA PRIVATE KEY-----\n"
                  }
              },
  ca JSON object

The certificate of SPS's internal Certificate Authority.:

  webserver JSON object

The SSL certificate of SPS's web and REST interface.

  tsa JSON object

The certificate of SPS's internal Timestamping Authority.

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 Application level error codes.

Code Description Notes
401 WebGuiOrRpcApiConfigInProgress

Web based or RPC API configuration is in progress — another client is connected to SPS. You can see the IP address of the client in the details key of the response, for example:

{
    "error": {
        "details": {
            "user": "admin@10.30.255.70"
        },
        "message": "Web based or RPC API configuration is in progress.",
        "type": "WebGuiOrRpcApiConfigInProgress"
    },
    "meta": {
        "href": "/api/setup",
        "next": "/api/transaction",
        "parent": "/api",
        "remaining_seconds": 0
    }
}
401 ConfigurationAlreadyInitialized

The Welcome Wizard was already successfully completed on this SPS.

{
    "error": {
        "message": "The configuration of the system is already initialized.",
        "type": "ConfigurationAlreadyInitialized"
    },
    "meta": {
        "href": "/api/setup",
        "parent": "/api",
        "remaining_seconds": 0
    }
}

Enable and configure analytics using REST

Detailed information about this topic

Enable One Identity Safeguard for Privileged Analytics

This endpoint allows you to enable One Identity Safeguard for Privileged Analytics.

To enable One Identity Safeguard for Privileged Analytics and analyze the behavior of your users, One Identity Safeguard for Privileged Sessions (SPS) requires a special license. Also, depending on the number of your users and sessions, the performance and sizing of SPS must be considered. If you are interested in One Identity Safeguard for Privileged Analytics, contact our Sales Team, or your One Identity representative. For details on One Identity Safeguard for Privileged Analytics, see the One Identity One Identity Safeguard for Privileged Analytics website. For details on enabling One Identity Safeguard for Privileged Analytics, see Safeguard for Privileged Analytics Configuration Guide.

URL
GET https://<IP-address-of-SPS>/api/configuration/local_services/analytics/

Querying this endpoint returns the true if One Identity Safeguard for Privileged Analytics is enabled, false otherwise. For example:

{
    "body": {
        "enabled": false
    },
    "key": "analytics",
    "meta": {
        "first": "/api/configuration/local_services/admin_web",
        "href": "/api/configuration/local_services/analytics",
        "last": "/api/configuration/local_services/user_web",
        "next": "/api/configuration/local_services/indexer",
        "parent": "/api/configuration/local_services",
        "previous": "/api/configuration/local_services/admin_web",
        "remaining_seconds": 600,
        "transaction": "/api/transaction"
    }
}

To modify enable One Identity Safeguard for Privileged Analytics, you have to complete the following.

Prerequisites

To enable One Identity Safeguard for Privileged Analytics and analyze the behavior of your users, One Identity Safeguard for Privileged Sessions (SPS) requires a special license. Also, depending on the number of your users and sessions, the performance and sizing of SPS must be considered. If you are interested in One Identity Safeguard for Privileged Analytics, contact our Sales Team, or your One Identity representative. For details on One Identity Safeguard for Privileged Analytics, see the One Identity One Identity Safeguard for Privileged Analytics website. For details on enabling One Identity Safeguard for Privileged Analytics, see Safeguard for Privileged Analytics Configuration Guide.

For details on uploading a license, see Upload a new license.

  1. Change the enabled option to true.

    PUT the enabled option with the true value as a JSON object to the https://<IP-address-of-SPS>/api/configuration/local_services/analytics/ endpoint. For example:

    curl -H "Content-Type: application/json" -d '{ "enabled": true}' -X POST https://<IP-address-of-SPS>/api/configuration/local_services/analytics/
Code Description Notes
200 OK Updating the resource was successful
201 Created The new resource was successfully created.
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.
403 Unauthorized The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
404 NotFound The requested object does not exist.

Configure One Identity Safeguard for Privileged Analytics

The /api/configuration/policies/analytics endpoint allows you to configure One Identity Safeguard for Privileged Analytics by adding and removing analytics policies.

URL
GET https://<IP-address-of-SPS>/api/configuration/policies/analytics/
Sample request

The following command lists the analytics policies configured.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/policies/analytics/

The following command retrieves the properties of a specific policy.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/policies/analytics/<policy-key>
Response

The following is a sample response received when listing analytics policies.

{
  "items": [
    {
      "key": "9316362595a747b24d295e",
      "meta": {"href": "/api/configuration/policies/analytics/9316362595a747b24d295e"}
    }, {
      "key": "9316362595a747b24d295f",
      "meta": {"href": "/api/configuration/policies/analytics/9316362595a747b24d295f"}
    }
  ]
}
  "meta": {
    "first": "/api/configuration/policies/aa_plugin_instances",
    "href": "/api/configuration/policies/analytics",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/audit_policies",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/aa_plugin_instances",
    "remaining_seconds": 599,
    "transaction": "/api/transaction"
  }

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

{
    "body": {
        "name": "my_analytics_policy",
        "scoring": {
            "command": "trust",
            "fis": "disable",
            "hostlogin": "use",
            "keystroke": "trust",
            "logintime": "use",
            "mouse": "disable",
            "windowtitle": "disable"
        }
    },
    "key": "9316362595a747b24d295e",
    "meta": {
        "first": "/api/configuration/policies/analytics/9316362595a747b24d295e",
        "href": "/api/configuration/policies/analytics/9316362595a747b24d295e",
        "last": "/api/configuration/policies/analytics/9316362595a747b24d295e",
        "next": null,
        "parent": "/api/configuration/policies/analytics",
        "previous": null,
        "remaining_seconds": 600,
        "transaction": "/api/transaction"
    }
Element Type Description
body, or items when a list is returned Top-level element (string) Contains the properties of the analytics policy.
name string The unique name of the policy. This name is also displayed on the SPS web interface. It cannot contain whitespaces.
scoring Top-level element Scoring settings for analytics.
key string Top-level element, contains the ID of the policy.
Elements of scoring Type Description
command string

Contains one of the following values:

  • disable: The algorithm is not used and is therefore not scoring session data.

  • use: The algorithm is used and is therefore scoring session data. The highest and lowest scores given by this algorithm are ignored when aggregating scores.

  • trust: The algorithm is used and is therefore scoring session data. The highest and lowest scores given by this algorithm are taken into account when aggregating scores.

fis string
hostlogin string
keystroke string
logintime string
mouse string
windowtitle string
Add an analytics policy

To add an analytics policy, complete the following steps.

  1. Create the JSON object for the new analytics policy.

    POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/analytics endpoint. You can find a detailed description of the available parameters listed in Element .

    If the POST request is successful, when querying /api/configuration/policies/analytics, the response includes the key of the new analytics policy. For example:

    {
      "key": "1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
      "meta": {
        "href": "/api/configuration/policies/analytics/1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
        "parent": "/api/configuration/policies/analytics",
        "transaction": "/api/transaction"
      }
    }
Modify an analytics policy

To modify an analytics policy, complete the following steps.

  1. Modify the JSON object of the analytics policy.

    PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/analytics/<policy-key> endpoint. You can find a detailed description of the available parameters listed in Element .

Delete an analytics policy

To delete an analytics policy, complete the following steps.

  1. DELETE the JSON object of the analytics policy.

    DELETE the JSON object using the ID of the object as the key: https://<IP-address-of-SPS>/api/configuration/policies/analytics/<policy-key>. For details on how to delete an object, see Delete an object.

    If the DELETE request is successful, when querying /api/configuration/policies/analytics, the response includes the key of the deleted analytics policy. For example:

    {
      "meta": {
        "first": "/api/configuration/policies/analytics/9316362595a747b24d295e",
        "href": "/api/configuration/policies/analytics/9316362595a747b24d295e",
        "last": "/api/configuration/policies/analytics/9316362595a747b24d295e",
        "next": "/api/configuration/policies/analytics/9316362595a747b24d295e",
        "parent": "/api/configuration/policies/analytics",
        "previous": null,
        "transaction": "/api/transaction"
      }
    }
  2. Commit your changes to actually delete the object from SPS. For details, see Commit a transaction.

Code Description Notes
201 Created The new resource was successfully created.
400 SemanticError The request to create an object has failed due to semantic errors in the configuration.
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.
403 Unauthorized The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
404 NotFound The requested object does not exist.
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating