Completing the Welcome Wizard using REST
The Welcome Wizard helps you complete the initial configuration of Safeguard for Privileged Sessions. Starting with version 5 F4, you can complete the Welcome Wizard using REST as well.
URL
GET https://<IP-address-of-Safeguard for Privileged Sessions>/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 Completing the Welcome Wizard using REST.
curl -H "Content-Type: application/json" -d @body.json -X POST https://<IP-address-of-Safeguard for Privileged Sessions>/api/setup/
|
|
NOTE:
The request automatically fails if there are any other clients connected to the REST or the web interface of Safeguard for Privileged Sessions. |
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.balabit.com/documents/scb-latest-guides/en/scb-guide-admin/html/app-eula.html",
"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 End User License Agreement (EULA). Must be true to complete the Welcome Wizard. | |
| network | JSON object | Contains the initial networking configuration of Safeguard for Privileged Sessions. | |
| license | string |
Your Safeguard for Privileged Sessions license as a string. You can download your license from support portal. Replace the line-breaks in the license file with \n characters, for example: "license": "Product: Shell Control Box\nEdition: Single\n[...]", Note that you can complete the Welcome Wizard without uploading a license. In this case, Safeguard for Privileged Sessions will start in demo mode. To skip uploading the license, use the null value: "license": null, To upload a license file, see Manage the Safeguard for Privileged Sessions license. | |
| certificates | JSON object | Contains the initial certificates used on Safeguard for Privileged Sessions: 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"
}, | |
| JSON object |
Contains the SMTP server to use, and the e-mail address of the Safeguard for Privileged Sessions administrator. For example: "email": {
"smtp_server": "smtp.example.com",
"admin_email": "psm-administrator@example.com"
}, | ||
| datetime | JSON object |
Contains the timezone of Safeguard for Privileged Sessions 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 Safeguard for Privileged Sessions. | |||
| hostname | string |
Name of the machine running Safeguard for Privileged Sessions. 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 Safeguard for Privileged Sessions (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.
| |||
| vlantag | string |
The VLAN ID of interface 1 (or EXT). Optional, use null if it is not set. For example: "vlantag": null,
| |||
| initial_address | 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 Safeguard for Privileged Sessions. The key must be in PKCS-1 PEM format. You need the certificate and the private key as well. Encrypted private keys are not supported. The attributes of the POST message that contain the certificate and the private key must be a single line, enclosed in double-quotes. Replace line-breaks in the PEM certificate with \n The certificate and the certificate chain must be valid, Safeguard for Privileged Sessions will reject invalid certificates and invalid certificate chains. 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 Safeguard for Privileged Sessions's internal Certificate Authority.: | |
| webserver | JSON object |
The SSL certificate of Safeguard for Privileged Sessions's web and REST interface. | |
| tsa | JSON object |
The certificate of Safeguard for Privileged Sessions'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 Using the Safeguard for Privileged Sessions REST API.
| Code | Description | Notes |
|---|---|---|
| 401 | WebGuiOrRpcApiConfigInProgress |
Web based or RPC API configuration is in progress — another client is connected to Safeguard for Privileged Sessions. 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 Safeguard for Privileged Sessions. {
"error": {
"details": {
"path": "/api/setup"
},
"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
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, Safeguard for Privileged Sessions requires a special license. Also, depending on the number of your users and sessions, the performance and sizing of Safeguard for Privileged Sessions 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-Safeguard for Privileged Sessions>/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, Safeguard for Privileged Sessions requires a special license. Also, depending on the number of your users and sessions, the performance and sizing of Safeguard for Privileged Sessions 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 Manage the Safeguard for Privileged Sessions license.
-
Open a transaction.
For details, see Open a transaction.
-
Change the enabled option to true.
PUT the enabled option with the true value as a JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/local_services/analytics/ endpoint. For example:
curl -H "Content-Type: application/json" -d '{ "enabled": true}' -X POST https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/local_services/analytics/ -
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 |
|---|---|---|
| 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. |
| 401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
| 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-Safeguard for Privileged Sessions>/api/configuration/policies/analytics/
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 analytics policies configured.
curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/analytics/
The following command retrieves the properties of a specific policy.
curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/analytics/<policy-key>
Response
The following is a sample response received when listing analytics policies. For details of the meta object, see Introduction.
{
"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"
"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:
|
| fis | string | |
| hostlogin | string | |
| keystroke | string | |
| logintime | string | |
| windowtitle | string |
Add an analytics policy
To add an analytics policy, complete the following steps.
-
Open a transaction.
For details, see Open a transaction.
-
Create the JSON object for the new analytics policy.
POST the JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/analytics endpoint. You can find a detailed description of the available parameters listed in Configure One Identity Safeguard for Privileged Analytics.
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" } } -
Commit your changes.
For details, see Commit a transaction.
Modify an analytics policy
To modify an analytics policy, complete the following steps.
-
Open a transaction.
For details, see Open a transaction.
-
Modify the JSON object of the analytics policy.
PUT the modified JSON object to the https://<IP-address-of-Safeguard for Privileged Sessions>/api/configuration/policies/analytics/<policy-key> endpoint. You can find a detailed description of the available parameters listed in Configure One Identity Safeguard for Privileged Analytics.
-
Commit your changes.
For details, see Commit a transaction.
Delete an analytics policy
To delete an analytics policy, complete the following steps.
-
Open a transaction.
For details, see Open a transaction.
-
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-Safeguard for Privileged Sessions>/api/configuration/policies/analytics/<policy-key>. For details on how to delete an object, see Using the Safeguard for Privileged Sessions REST API.
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" } } -
Commit your changes to actually delete the object from Safeguard for Privileged Sessions. For details, see Using the Safeguard for Privileged Sessions REST API.
Status and error codes
The following table lists the typical status and error codes for this endpoint. 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 | 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. |
| 401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
| 404 | NotFound | The requested object does not exist. |