One Identity Safeguard for Privileged Sessions 7.0.5.1 LTS

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

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:

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

Response

The response is a regular meta object.

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

Basic settings > 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

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.

{
   "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
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

Basic settings > Managing Starling Join > 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

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.

{
   "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.