Trust stores serve as local certificate storages where users can store the certificate chains of trusted Certificate Authorities (CAs). These certificates are then used to ensure secure communication between external parties and the SPS.
There are two types of trust stores: built-in and custom.
The built-in trust store has well known root CAs (such as Google, Microsoft, Verisign, etc.), and it is not modifiable.
Before establishing secure communication (TLS), SPS verifies the certificate of the other party using the assigned trust store. Only certificates signed by any of the CAs in the trust store are accepted.
NOTE: CRL URLs must be listed explicitly in the appropriate field, as those CRL URLs that are embedded in the extensions of the certificates, will be ignored.
URL
GET https://<IP-address-of-SPS>/api/configuration/trust_stores
Cookies
| 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 with the trust_stores endpoint include:
| Create a trust store |
POST |
/api/configuration/trust_stores |
The name of the trust store must be unique. |
| List trust stores |
GET |
/api/configuration/trust_stores |
Users who were not given read access to the trust_stores endpoint explicitly, are still able to retrieve information from it, if they have access to other /configuration related endpoints, which reference trust stores.
Examples of trust store referrer ACL (read access):
- /pages/starlingjoin
- /config/xcb/aaa/settings
- /config/scb/pol_ldaps
|
| Query a trust store |
GET |
/api/configuration/trust_stores/<id of the trust store> |
|
| Query the built-in trust store |
GET |
/api/configuration/trust_stores/-7001 |
|
| Update a trust store |
PUT |
/api/configuration/trust_stores/<id of the trust store> |
Users who were not given access to the trust_stores endpoint explicitly, but are still able to retrieve information from it because they have access to configuration endpoints which reference trust stores, are unable to modify trust stores.
With the exception of /config/xcb/management, where the same access level is granted to the trust stores for the user as they have for /config/xcb/management. |
| Delete a trust store |
DELETE |
/api/configuration/trust_stores/<id of the trust store> |
|
Elements of the response message body include:
| items |
|
object array |
List of JSON objects available from the current endpoint. |
|
| |
key |
string |
The ID of the trust store. |
Each trust store has a unique key.
The built-in trust store's ID is "-7001". |
| |
meta |
string (uri) |
The href field contains the URL of the trust store. |
|
| |
body |
|
|
|
| body |
|
object |
Top level element. |
|
| |
name |
string |
The name of the trust store. |
The name field is set by the user and it must be unique.
For example:
"name": "My_Custom_Trust_Store".
The built-in trust store's name is "Built-in". |
| |
authorities
|
|
|
|
| |
crl_urls |
string array |
The crl_urls field contains the list of CRL web addresses (HTTP or HTTPs URLs) used for revocation check. |
If a trust store that uses certificate revocation lists (CRLs) does not work properly, it might be due to invalid or inaccessible CRL URLs. Troubleshooting can involve checking whether all URLs of the CA CRL URL list are valid, and can be accessed from the SPS via the Basic Settings / Troubleshooting / Connect to TCP port function in the Web UI. |
|
|
revocation_check |
enum |
The type of the revocation check. |
Possible values: "full", "leaf", "none".
"full" - The crl_urls field must contain CRL URLs for all of the CAs that are part of the chain of a given certificate which is being verified.
"leaf" - The crl_urls field must contain at least the CRL URL of the CA which signed the certificate which is being validated.
"none" - The crl_urls field must be empty. |
|
|
trust_store_type |
enum |
The type of the trust store. |
Possible values: "built-in", "custom".
The built-in trust store comes with the operation system. This type of trust store is read-only. There is no CRL check involved, and it cannot be removed. |
| authorities |
|
array |
List of Certificate Authorities. |
|
| |
fingerprint |
|
|
|
| |
issuer
|
string |
The name of the entity that signed the certificate. |
|
| |
pem |
string |
The certificate in PEM format. |
|
|
|
subject |
string |
The subject of the certificate. |
|
| fingerprint |
|
|
A two-piece byte sequence consisting of a hash algorithm and a message digest. |
|
| |
digest |
string |
The string of digits produced by the hash algorithm. |
|
| |
hash_algorithm
|
string |
The name of the hash algorithm. |
|
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.
| 400 |
SyntacticError |
A value to be set is not accepted syntactically. The details section contains the path that was found to be invalid.
Possible syntactic error messages related to trust store:
- The user is not allowed to create a built-in trust store or edit or delete the existing one.
- When revocation_check is set to "none", the crl_urls field must be empty. The user cannot add any element to crl_urls.
- When revocation_check is set to "full" or "leaf", the crl_urls cannot be empty.
|
| 400 |
SemanticError |
The configuration contains semantic errors, inconsistencies or other problems that would put the system into an unreliable state if the configuration had been applied. The details section contains the errors that were found in the configuration.
Possible semantic error messages related to trust store:
- The name of the trust stores must be unique.
- The authorities of a trust store must be unique.
- The CRL URLs of a trust store must be unique.
|
| 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. |
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
| 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:
| 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:
-
-
Open a transaction.
For more information, see Open a transaction.
-
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.txt 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:
| 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 |
-
-
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:
| 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:
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.
The /api/starling/join/status endpoint returns the status of the services required for One Identity Starling join.
URL
GET https://<IP-address-of-SPS>/api/starling/join
Cookies
| 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:
|
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.txt 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:
| 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:
|
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.
|
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.
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/status
Cookies
| 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.txt https://<IP-address-of-SPS>/api/starling/status
Response
The following is a sample response.
For more information on the meta object, see Message format.
{ |
"internet_connection": {"status": true, "error": "N/A"}, |
"meta": { |
"href": "/api/starling/status", |
"parent": "/api/starling", |
"remaining_seconds": 593 |
}, |
"proxy": true, |
"starling_status": { |
"STS API": "healthy", |
"Microsoft Graph API": "healthy", |
"Salesforce API": "healthy", |
"Database": "healthy" |
}, |
"verdict": true |
} |
Elements of the response message body include:
| internet_connection |
object |
Indicates whether or not the SPS appliance can connect to the status endpoint (https://accountsupervisor.cloud.oneidentity.com/heartbeat?checkdependencies=true). |
| 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 endpoint.
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 join-related services and their current status. |
|
verdict |
boolean |
The value is true if SPS can connect to the status page and the relevant service(s) are healthy. |
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.
