Chatta subito con l'assistenza
Chat con il supporto

Safeguard for Privileged Sessions On Demand Hosted - 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

Global HTTP options

List of options that affect all HTTP connections.

URL
GET https://<IP-address-of-SPS>/api/configuration/http/options
Cookies
Cookie 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 SPS REST API.

NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format)..

Sample request

The following command lists global HTTP options.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/http/options
Response

The following is a sample response received when listing global HTTP options.

For details of the meta object, see Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/http/channel_policies",
    "href": "/api/configuration/http/options",
    "last": "/api/configuration/http/settings_policies",
    "next": "/api/configuration/http/settings_policies",
    "parent": "/api/configuration/http",
    "previous": "/api/configuration/http/channel_policies",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key Top level item Contains the ID of the endpoint.
body Top level item Contains the elements of the global HTTP options.
audit Top level item Contains settings for timestamping and cleanup.
service Top level item Global setting to enable HTTP connections, and specify the logging detail.
enabled boolean Set to true to enable HTTP connections.
log_level int Defines the logging detail of HTTP connections.
Elements of audit Type Description
cleanup Top level item Global retention settings for HTTP connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead.
channel_database_cleanup_days int

Only if enabled is set to true.

Global retention time for the metadata of HTTP connections, in days. Must exceed the retention time of the archiving policy (or policies) used for HTTP connections, and the connection-specific database cleanup times (if configured).

enabled boolean To enable the global cleanup of HTTP connection metadata, set this element to true.
timestamping Top level item Global timestamping settings for HTTP connections.
selection string

Configures local or remote timestamping.

  • Set local to use SPS for timestamping.

  • Set remote to configure a remote timestamping server.

server_url string

Required for remote timestamping.

The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported.

oid Top level item The Object Identifier of the policy used for timestamping.
enabled boolean

Required for remote timestamping.

Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server.

policy_oid string

Required if the oid is enabled.

The Object Identifier of the timestamping policy on the remote timestamping server.

signing_interval int Time interval for timestamping open connections, in seconds.
Examples:

Set SPS as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}
Modify global HTTP settings

To modify global HTTP settings, you have to:

  1. Open a transaction.

    For more information, see Open a transaction.

  2. Modify the JSON object of the global HTTP settings endpoint.

    PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/http/options endpoint. You can find a detailed description of the available parameters listed in Element. The elements of the audit item are described in Elements of audit.

  3. Commit your changes.

    For more information, 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 Application level error codes.

Code Description Notes
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.

HTTP settings policies

HTTP settings policies define protocol-level settings for idle and session timeout. You can create multiple policies, and choose the appropriate one for each HTTP connection.

URL
GET https://<IP-address-of-SPS>/api/configuration/http/settings_policies
Cookies
Cookie 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 SPS REST API.

NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format)..

Sample request

The following command lists HTTP settings policies.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/http/settings_policies

The following command retrieves the properties of a specific policy.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/http/settings_policies/<policy-id>
Response

The following is a sample response received when listing HTTP settings policies.

For details of the meta object, see Message format.

{
  "items": [
    {
      "key": "-3040010",
      "meta": {
        "href": "/api/configuration/http/settings_policies/-3040010"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/http/channel_policies",
    "href": "/api/configuration/http/settings_policies",
    "last": "/api/configuration/http/settings_policies",
    "next": null,
    "parent": "/api/configuration/http",
    "previous": "/api/configuration/http/options",
    "transaction": "/api/transaction"
  }
}

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

{
  "body": {
    "client_tls_security_settings": {
        "cipher_strength": {
            "selection": "recommended"
        },
        "minimum_tls_version": "TLSv1_2"
    },
    "name": "default",
    "server_tls_security_settings": {
        "cipher_strength": {
            "selection": "recommended"
        },
        "minimum_tls_version": "TLSv1_2"
    },
    "session_timeout": 900,
    "timeout": 300
    "webapp_session_cookies": [
      "PHPSESSID",
      "JSESSIONID",
      "ASP.NET_SessionId"
    ]
  },
  "key": "-3040010",
  "meta": {
    "first": "/api/configuration/http/settings_policies/-3040010",
    "href": "/api/configuration/http/settings_policies/-3040010",
    "last": "/api/configuration/http/settings_policies/-3040010",
    "next": null,
    "parent": "/api/configuration/http/settings_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

When retrieving the default settings policy with a built-in HTTP proxy error template, the response is the following.

{
     "key": "-3040010",
     "body": {
       "name": "default",
       "timeout": 300,
       "session_timeout": 900,
       "webapp_session_cookies": [],
       "client_tls_security_settings": {
         "minimum_tls_version": "TLSv1_2",
         "cipher_strength": {
           "selection": "recommended"
         }
       },
       "server_tls_security_settings": {
         "minimum_tls_version": "TLSv1_2",
         "cipher_strength": {
           "selection": "recommended"
         }
       },
       "error_template": {
         "selection": "builtin"
       }
     }
   }

When you create a new settings policy with a custom error template, the response is the following.

{
       "name": "custom_http_settings_policy",
       "timeout": 400,
       "session_timeout": 1000,
       "webapp_session_cookies": [
         "PHPSESSID",
         "JSESSIONID",
         "ASP.NET_SessionId"
       ],
       "client_tls_security_settings": {
         "minimum_tls_version": "TLSv1_2",
         "cipher_strength": {
           "selection": "recommended"
         }
       },
       "server_tls_security_settings": {
         "minimum_tls_version": "TLSv1_2",
         "cipher_strength": {
           "selection": "recommended"
         }
       },
       "error_template": {
         "selection": "custom",
         "reference": "123456789"
       }
     }
Element Type Description
key string Top level element, contains the ID of the policy.
body Top level element (string) The elements of the HTTP settings policy.
client_tls_security_settings JSON object Configures TLS security settings on the client side.
name string Name of the HTTP settings policy. Cannot contain whitespace.
server_tls_security_settings JSON object Configures TLS security settings on the server side.
session_timeout int Session timeout, in seconds.
timeout int Idle timeout, in seconds. Note that the SPS web UI displays the same value in seconds.
webapp_session_cookies​ list (string)

To distinguish the audited HTTP requests and responses based on the session cookies of web applications, enter the name of the session cookie, for example, PHPSESSID, JSESSIONID, or ASP.NET_SessionId. Note that the names of session cookies are case sensitive.

Note that this is a priority list. If there are multiple cookie names, SPS will use the first one from this list it finds in the request headers to assign the requests to a session.

error_template

object

 

error_template.selection

enum

The type of the error template. Possible values: builtin, custom

error_template.reference

number

The identifier of the error template.

Elements of client_tls_security_settings and server_tls_security_settings Type Description
cipher_strength JSON object Specifies the cipher string OpenSSL will use.
custom_cipher string

The list of ciphers you want to permit SPS to use in the connection. For more details on customizing this list, check the 'openssl-ciphers' manual page on your SPS appliance.

selection string

Specifies the cipher string OpenSSL will use. The following settings options are possible:

  • recommended: this setting only uses ciphers with adequate security level.

  • custom: this setting allows you to specify the list of ciphers you want to permit SPS to use in the connection. This setting is only recommended to ensure compatibility with older systems. For more details on customizing this list, check the 'openssl-ciphers' manual page on your SPS appliance.

    For example: ALL:!aNULL:@STRENGTH

minimum_tls_version string

Specifies the minimal TLS version SPS will offer during negotiation. The following settings options are possible:

  • TLSv1_2: this setting only offers TLS version 1.2 during the negotiation. This is the recommended setting.

  • TLSv1_1: this setting offers TLS version 1.1 and later versions during the negotiation.

  • TLSv1_0: this setting offers TLS version 1.0 and later versions during the negotiation.

Add HTTP settings policies

To add a settings policy, you have to:

  1. Open a transaction.

    For more information, see Open a transaction.

  2. Create the JSON object for the new policy.

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

    If the POST request is successful, the response includes the key of the new policy. For example:

    {
      "key": "3848c708-2e1d-4463-b232-0c8c5875ff55",
      "meta": {
        "href": "/api/configuration/http/settings_policies/3848c708-2e1d-4463-b232-0c8c5875ff55",
        "parent": "/api/configuration/http/settings_policies",
        "transaction": "/api/transaction"
      }
    }
  3. Commit your changes.

    For more information, see Commit a transaction.

Modify HTTP settings policies

To modify a settings policy, you have to:

  1. Open a transaction.

    For more information, see Open a transaction.

  2. Modify the JSON object of the policy.

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

  3. Commit your changes.

    For more information, 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 Application level error codes.

Code Description Notes
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.

Creating custom HTTP error templates

Configure HTTP error templates to create custom error pages when HTTP proxy errors occur.

URL
GET https://<IP-address-of-SPS>/api/configuration/http/error_templates
Cookies
Cookie 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 SPS REST API.

NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format)..

Operations

Operations with the /http/error_templates endpoint include:

Operation HTTP method URL

Notes

Querying existing error templates GET /api/configuration/http/error_templates  

Creating a new error template with a custom logo

POST

/api/configuration/http/error_templates

 

Updating an existing error template

PUT

/api/configuration/http/error_templates/<key>

 

Querying error templates info

GET

/api/configuration/http/error_templates?info=

 

Querying custom error template preview

GET

/api/configuration/http/error_templates?preview=&error_type=<type-of-the-error-template>

 

Sample request

The following command lists the available HTTP proxy error templates.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/http/error_templates
Response

The following is a sample response received when available HTTP proxy error templates are queried.

For details of the meta object, see Message format.

{
     "name": "Template_with_logo",
     "color": "#123456",
     "logo": "<'logo_id' from the response of the first creation>",
     "brand_name": "Noname brand",
     "md_contents": {
       "auth": "Custom auth failed markdown content.",
       "badcontent": "Custom bad content error markdown content.",
       "clientsyntax": "Custom client syntax error markdown content.",
       "clienttimeout": "Custom client timeout error markdown content.",
       "connecterror": "Custom connection error markdown content.",
       "ftperror": "Custom FTP error markdown content.",
       "internal": "Custom internal error markdown content.",
       "invalidurl": "Custom invalid URL markdown content.",
       "ioerror": "Custom I/O error markdown content.",
       "policysyntax": "Custom policy syntax error markdown content.",
       "policyviolation": "Custom policy violation error markdown content.",
       "redirect": "Custom redirect markdown content.",
       "serversyntax": "Custom server syntax error markdown content.",
       "servertimeout": "Custom server timeout error markdown content."
     }
    }

The following is a sample response received when HTTP proxy error template information is queried with /api/configuration/http/error_templates?info=.

{
     "error_type_names": {
       "auth": "Authentication Failed",
       "badcontent": "Bad Content",
       "clientsyntax": "Client Syntax",
       "clienttimeout": "Client Timeout",
       "connecterror": "Connection Error",
       "ftperror": "FTP Error",
       "internal": "Internal Error",
       "invalidurl": "Invalid URL",
       "ioerror": "I/O Error",
       "policysyntax": "Policy Syntax",
       "policyviolation": "Policy Violation",
       "redirect": "Redirect",
       "serversyntax": "Server Syntax",
       "servertimeout": "Server Timeout"
     }
    }

Elements of the response message include:

Element

Type

Description

Notes

name string The name of the template.

 

color number The color of the brand and links appearing in the error template. The value is given in hex color code.
logo string? union? The identifier of the logo. The value of the logo can be 'null'.

brand_name

string

The name of the brand.

 

md_contents

object

Contains a list of error templates written in Markdown.

 

md_contents.auth

string

The content of the Authentication failed error template in Markdown.

 

md_contents.badcontent

string

The content of the Bad content error template in Markdown.

 

md_contents.clientsyntax

string

The content of the Client syntax error template in Markdown.

 

md_contents.clienttimeout

string

The content of the Client timeout error template in Markdown.

 

md_contents.connecterror

string

The content of the Connect error error template in Markdown.

 

md_contents.ftperror

string

The content of the FTP error error template in Markdown.

 

md_contents.internal

string

The content of the Internal error error template in Markdown.

 

md_contents.invalidurl

string

The content of the Invalid URL error template in Markdown.

 

md_contents.ioerror

string

The content of the IO error error template in Markdown.

 

md_contents.policysyntax

string

The content of the Policy syntax error template in Markdown.

 

md_contents.policyviolation

string

The content of the Policy violation error template in Markdown.

 

md_contents.redirect

string

The content of the Redirect error template in Markdown.

 

md_contents.serversyntax

string

The content of the Server syntax error template in Markdown.

 

md_contents.servertimeout

string

The content of the Server timeout error template in Markdown.

 

For details of the meta object, see Message format.

HTTP response codes

HTTP response codes comprise of standard or endpoint-specific HTTP status and error codes. The following table lists the endpoint-specific HTTP response codes for this request.

HTTP response code Status/Error Description
400 NotSupportedProxyErrorType Preview could not be created. The used error type is not supported. Use an error type from the following list: Authentication failed, Bad content, Client syntax, Client timeout, Connect error, FTP error, Internal, Invalid URL, IO error, Policy syntax, Policy violation, Redirect, Server syntax, Server timeout.

For more information and a complete list of standard HTTP response codes, see Application level error codes.

Uploading a custom logo to your custom HTTP proxy error pages

Upload a custom logo to your custom HTTP proxy error pages.

Supported formats: PNG, JPEG, GIF.

URL
GET https://<IP-address-of-SPS>/api/configuration/http/proxy_error_logo
Cookies
Cookie 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 SPS REST API.

NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format)..

Operations

Operations with the /http/proxy_error_logo endpoint include:

Operation HTTP method URL

Notes

Uploading a custom logo POST /api/upload/http/proxy_error_logo If you upload an oversized logo, for example 800x800 pixels, your image will be automatically resized to 128x128 pixels, keeping the original aspect ratio.

NOTE: GET / PUT / DELETE methods are not allowed on logo upload.

Sample request

The following command uploads a custom logo.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/http/proxy_error_logo
Response

The following is a sample response received when the custom logo has been uploaded.

The response of the creation without the unique ID is the following.

{
     "logo_id": "rest_XXXXXXXX",
     "meta": {
       "href": "/api/upload/http/proxy_error_logo",
       "parent": "/api/upload/http"
     }
   }

The response of the query without a unique logo ID is the following.

{
     "changes": [
      {
       "new_value": "rest_XXXXXXXX",
       "path": "/api/upload/http/proxy_error_logo",
       "type": "creation"
      }
     ],
     "meta": {
       "href": "/api/transaction/changes",
       "parent": "/api/transaction",
       "transaction": "/api/transaction"
     }    
   }

For details of the meta object, see Message format.

Elements of the response message include:

Element

Type

Description

Notes

logo_id string The identifier of the custom logo.

 

supported_formats enum The supported image formats. Possible values: PNG, JPEG, GIF.
actual_resolution number The actual resolution of the uploaded custom logo.  
max_resolution

number

The maximal resolution of the uploaded custom logo. The maximum accepted size is 4096x4096 pixels.

file_size

number

The actual size of the file.

 

file_limit

number

The maximum size of the file.

The file size limit is 16 megabyte.

HTTP response codes

HTTP response codes comprise of standard or endpoint-specific HTTP status and error codes. The following table lists the endpoint-specific HTTP response codes for this request.

HTTP response code Status/Error Description
400 ResolutionTooLarge The logo you uploaded (5200x5200 pixels) is larger than the maximum accepted size (4096x4096 pixels). Upload a logo that is not larger than 4096x4096 pixels.

413

FileTooLarge

The file in the request exceeds the file size limitation.

415

InvalidImageFormat

The file format of the uploaded logo is not supported. Make sure that you upload a logo in one of our supported file formats (PNG, JPEG, GIF).

For more information and a complete list of standard HTTP response codes, see Application level error codes.

Related Documents

The document was helpful.

Seleziona valutazione

I easily found the information I needed.

Seleziona valutazione