Chat now with support
Chat mit Support

One Identity Safeguard for Privileged Sessions 7.0.4 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

Enabling One Identity Safeguard Remote Access without Starling Join

Enable the One Identity Safeguard Remote Access (SRA) feature of One Identity Starling without Starling Join information.

NOTE: You cannot configure Starling Join through the resource configuration endpoint (/api/configuration/starling), only through the dedicated /starling/join endpoint.

URL
GET https://<IP-address-of-SPS>/api/configuration/starling
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 more information 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 /starling endpoint include:

Operation HTTP method URL

Notes

Query One Identity Starling Join without a join to One Identity Starling GET /api/configuration/starling

The value of the join_info field is null.

Query One Identity Starling Join after join GET /api/configuration/starling

The values of the join_info field are environment, product_instance, and product_tims.

Enable SRA PUT /api/configuration/starling

SRA can be enabled only if the node is joined to One Identity Starling. Use the starling/join endpoint to join to One Identity Starling.

Disable SRA PUT /api/configuration/starling

To disable SRA to One Identity Starling, the enabled field must be set to false.

Enable SRA

To enable SRA with the use of the /starling endpoint, you have to:

  1. Open a transaction.

    For more information, see Open a transaction.

  2. Set the enabled parameter of remote_access to true.

    Sample request

    The following command enables SRA to join to One Identity Starling.

    curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/starling
    {
       "join_info": {
         "environment": "prod",
         "product_instance": "starling-joiner-11111111-1111-1111-1111-111111111111",
         "product_tims": "123-456-789"
       },
       "remote_access":
       {
         "enabled": true
       }
    }
    				

    Elements of the request message body include:

    Elements Type Description

    Notes

    join_info object
    join_info.environment string

    The environment of the product.

    Possible values: prod.

    join_info.product_instance string

    The instance of the product.

    join_info.product_tims string

    The TIMS license of the product.

    remote_access  

    To disable SRA to One Identity Starling, the enabled field must be set to false.

    remote_access.enabled boolean

    Enables or disables SRA to One Identity Starling.

    Possible values: true, false

    key Possible values: starling
  3. Commit your changes.

    For more information, see Commit a transaction.

Response

The response is a regular meta object.

For more information on the meta object, see Message format.

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.

Endpoint-specific HTTP response codes for this request:

HTTP response code Status / Error Description
403 RemoteAccessDependsOnStarlingJoinError SRA to One Identity Starling can only be enabled, if the node is joined to One Identity Starling. Use the /starling/join endpoint to join to One Identity Starling.
403 StarlingJoinInfoIsReadOnlyError You cannot join or unjoin from One Identity Starling at the resource configuration endpoint (/api/configuration/starling), as the One Identity Starling join_info field is read-only. Use the /starling/join endpoint to join or unjoin from One Identity Starling.

Standard HTTP response codes for this request:

Managing Starling Join

NOTE: You cannot manage Starling Join through the resource configuration endpoint (/api/configuration/starling), only through the dedicated /starling/join endpoint.

Retrieving One Identity Starling Join information

Check whether your SPS appliance is joined to the One Identity Starling platform.

If you are interested which One Identity Starling services are available to you, you can list them at the Retrieving the status of services related to Starling Join/Unjoin endpoint.

URL
GET https://<IP-address-of-SPS>/api/starling/join
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 more information 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

HTTP GET operations with the /starling/join endpoint include:

Operation HTTP method URL

Notes

Querying Starling Join endpoint from a browser without TIMS

GET

 

 

 

/api/starling/join

 

 

 

Headers to be used: Accept: text/html.

 

 

 

Querying Starling Join endpoint when joined from a browser without TIMS

Querying Starling Join info without TIMS

Querying Starling Join info when joined without TIMS

Querying Starling Join endpoint from a browser with TIMS

GET

 

 

 

/api/starling/join?product_tims=<TIMS value>

 

 

 

Example of TIMS value: product_tims=222-333-444 .

 

 

 

Querying Starling Join endpoint when joined from a browser with TIMS

Querying Starling Join info with TIMS

Querying Starling Join info when joined with TIMS

Sample request

The following command queries the /starling/join endpoint when joined from a browser without TIMS.

curl --cookie cookies https://<IP-address-of-SPS>/api/starling/join
Response

The following is a sample response.

For more information on the meta object, see Message format.

{
   "body":
   {
     "joined": true,
     "product_instance": "starling-joiner-11111111-1111-1111-1111-111111111111",
     "product_name": "Safeguard",
     "product_tims": "123-456-789"
   }
}
		

Elements of the response message body include:

Elements Type Description

Notes

joined boolean

Displays whether or not the user is joined to One Identity Starling or unjoined from it.

product_instance string

The instance of the product.

product_name string

The name of the product.

product_tims string The TIMS license of the product.

NOTE: While it is possible to send a POST HTTP request to the /starling/join endpoint, if you want to join your SPS appliance to One Identity Starling, visit the SPS web interface and initiate the join process under Basic Settings > Starling Integration > Start join.

Unjoining SPS from One Identity Starling

Use the /starling/join endpoint to unjoin your SPS appliance from One Identity Starling.

URL
DELETE https://<IP-address-of-SPS>/api/starling/join
Operations

HTTP DELETE operations with the /starling/join endpoint include:

Operation HTTP method URL

Notes

Unjoining One Identity Starling

DELETE

/api/starling/join

Unjoining One Identity Starling in a regular way is not possible while One Identity Safeguard Remote Access (SRA) is enabled. To unjoin One Identity Starling, first you must disable SRA.

Force unjoining One Identity Starling

DELETE

/api/starling/join?force=true

The Force Unjoin functionality works even when SRA is enabled.

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

MissingCredentialStringError

The mandatory credential_string parameter is not specified for One Identity Starling Join.

400

MissingProductInstanceError

The mandatory product_instance parameter is not specified for One Identity Starling Join.

403

OpenTransactionError

The attempt to join to One Identity Starling was unsuccessful, as the transaction was still open. To join to One Identity Starling, you must first close the previous transaction.

403

ForbiddenActionError

Forbidden action. To unjoin from One Identity Starling, use the /starling/join endpoint.

403

StarlingJoinIsInUseByRemoteAccessError

Unjoining One Identity Starling is not allowed while One Identity Safeguard Remote Access (SRA) is in use. Disable SRA in the configuration before unjoining from One Identity Starling.

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

Retrieving the status of services related to Starling Join/Unjoin

Use the /status endpoint to retrieve information about the availability of the services needed for Starling Join, or Starling Unjoin.

URL
GET https://<IP-address-of-SPS>/api/starling/join/status
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 more information 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 returns information about the availability of the services needed for Starling Join, or Starling Unjoin .

curl --cookie cookies https://<IP-address-of-SPS>/api/starling/join/status
Response

The following is a sample response.

For more information on the meta object, see Message format.

{
   "internet_connection": {
     "error": "N/A",
     "status": true
   },
   "meta": {
     "href": "/api/starling/status",
     "parent": "/api/starling",
     "remaining_seconds": 593
   },
   "proxy": true,
   "starling_status": {
     "Account Email Notifications": "operational",
     "Account Services Portal": "operational",
     "Active Roles On Demand": "operational",
     "CertAccess": "operational",
     "Connect": "operational",
     "Database Service": "operational",
     "Hybrid Subscription": "operational",
     "Identity Manager On Demand": "operational",
     "Job Service": "operational",
     "One Identity Starling": "operational",
     "Password Manager On Demand": "operational",
     "Safeguard On Demand": "operational",
     "Safeguard Remote Access": "operational",
     "Safeguard for Privileged Passwords On Demand": "operational",
     "Safeguard for Privileged Sessions On Demand": "operational",
     "Subscription and Billing": "operational",
     "Two-Factor Authentication": "operational",
     "Web UI": "operational"
   },
   "verdict": true
}
		

Elements of the response message body include:

Elements Type Description

Notes

internet_connection object

Indicates whether or not the SPS appliance can connect to the status endpoint (oneidentitycloud.statuspage.io).

internet_connection.error string

The description of the error. If no error occurred, the value is N/A.

internet_connection.status boolean

The value is true, if the SPS appliance could connect to the status page.

The value is false, if there is no Internet connection.

proxy boolean Indicates whether or not a proxy server is configured.

starling_status

enum

Enumeration of the different One Identity Starling-related services and their current status.

NOTE: starling_status lists all available One Identity Starling-related services, however, to Starling Join/Unjoin to work, only the status of the One Identity Starling service is relevant.

verdict

boolean

The value is true if SPS can connect to the status page, a proxy is enabled, and the relevant service(s) are operational.

 

HTTP response codes

Standard HTTP response codes for this request:

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

User management and access control

Topics:
Verwandte Dokumente

The document was helpful.

Bewertung auswählen

I easily found the information I needed.

Bewertung auswählen