The credential store plugins used on SPS. To upload or update a plugin, see Upload a plugin.
GET https://<IP-address-of-SPS>/api/configuration/plugins/credentialstore
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 that 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). |
The following command lists the credential store plugins stored on SPS.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/plugins/credentialstore
The following command retrieves the properties of a specific plugin.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/plugins/credentialstore/<plugin-id>
The following is a sample response received when listing the credential store plugins used on SPS.
For details of the meta object, see Message format.
{ "items": [ { "key": "2534221015734bb18aaf32", "meta": { "href": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32" } } ], "meta": { "first": "/api/configuration/plugins/aa", "href": "/api/configuration/plugins/credentialstore", "last": "/api/configuration/plugins/ticketing", "next": "/api/configuration/plugins/ticketing", "parent": "/api/configuration/plugins", "previous": "/api/configuration/plugins/aa", "transaction": "/api/transaction" } }
When retrieving the endpoint of a specific plugin, the response is the following.
{ "body": { "api": "1.0", "description": "Demo credentialstore plugin for demonstration purposes", "name": "DemoCredentialStorePlugin", "path": "/opt/scb/var/plugins/credentialstore/DemoCredentialStorePlugin", "version": "0.0" }, "key": "2534221015734bb18aaf32", "meta": { "first": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32", "href": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32", "last": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32", "next": null, "parent": "/api/configuration/plugins/credentialstore", "previous": null, "transaction": "/api/transaction" } }
Element | Type | Description | |
---|---|---|---|
key | string | Top level element, contains the ID of the plugin. | |
body | Top level element (string) | Contains the properties of the plugin. | |
api | string | The API version of the plugin. | |
description | string | The description of the plugin. This description is also displayed on the SPS web interface. | |
name | string | The name of the plugin. This name is also displayed on the SPS web interface. It cannot contain whitespace. | |
path | string | The path where the plugin is stored on SPS. | |
version | string | The version of the plugin. |
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 |
---|---|---|
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. |
Credential Stores offer a way to store user credentials (for example, passwords, private keys, certificates) and use them to login to the target server, without the user having access to the credentials. That way, the users only have to perform gateway authentication on SPS with their usual password (or to an LDAP database), and if the user is allowed to access the target server, SPS automatically logs in using the Credential Store.
GET https://<IP-address-of-SPS>/api/configuration/policies/credentialstores
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 that 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). |
The following command lists the credential stores.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/policies/credentialstores
The following command retrieves the properties of a specific credential store.
curl --cookie cookies https://<IP-address-of-SPS>/api/policies/credentialstores/<policy-id>
The following is a sample response received when listing credential stores.
For details of the meta object, see Message format.
{ "items": [ { "key": "1580973975727acedd51b2", "meta": { "href": "/api/configuration/policies/credentialstores/1580973975727acedd51b2" } }, { "key": "935272738572bc2ec1dbdd", "meta": { "href": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd" } } ], "meta": { "first": "/api/configuration/policies/audit_policies", "href": "/api/configuration/policies/credentialstores", "last": "/api/configuration/policies/usermapping_policies", "next": "/api/configuration/policies/indexing", "parent": "/api/configuration/policies", "previous": "/api/configuration/policies/content_policies", "transaction": "/api/transaction" } }
When retrieving the endpoint of a specific credential store, the response is the following.
{ "body": { "name": "API_LOCAL", "type": { "authenticator_name": "auth_server_name", "default_namespace": "{HOST}", "dns_servers": { "primary": "192.168.56.1", "secondary": "192.168.56.2" }, "domain_mappings": [ { "domain": "domain", "host": { "selection": "fqdn", "value": "host" } } ], "login_mode": { "password": { "key": "e0ecbe98-bd17-4805-ba5d-17fb789f3971", "meta": { "href": "/api/configuration/passwords/e0ecbe98-bd17-4805-ba5d-17fb789f3971" } }, "selection": "fixed", "username": "fixed_username" }, "proxy_server": "http://192.168.56.201:9999", "selection": "local", "server_certificate_check": { "enabled": true, "trusted_ca": { "key": "12269547065727ad6e79d9e", "meta": { "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e" } } }, "web_interface_url": "http://erpm_address" } }, "key": "935272738572bc2ec1dbdd", "meta": { "first": "/api/configuration/policies/credentialstores/1580973975727acedd51b2", "href": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd", "last": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd", "next": null, "parent": "/api/configuration/policies/credentialstores", "previous": "/api/configuration/policies/credentialstores/1580973975727acedd51b2", "transaction": "/api/transaction" } }
Element | Type | Description | ||
---|---|---|---|---|
key | string | Top level element, contains the ID of the credential store. | ||
body | Top level element (string) | The configuration elements of the credential store. | ||
name | string | The name of the credential store. This name is also displayed on the SPS web interface. It cannot contain whitespace. | ||
type | Top level item | All elements for the configured type of credential store. | ||
authenticator_name | string | If your ERPM setup is configured to use an external authentication method, enter the name of the Authentication Server (Authenticator Source) set on your ERPM server. If empty, SPS uses the [Explicit] authenticator. | ||
default_namespace | string | The default namespace of the accounts (for example, [Linux], [LDAP], [IPMI], W2003DOMAIN). | ||
dns_servers | Top level item | The IP addresses of the DNS servers to use for resolving the hostnames provided in domain_mappings. | ||
domain_mappings | Top level list |
Use for RDP connections only. In a domainless environment, use default_namespace. | ||
encryption | Top level item | Configures the encryption key for the local credential store. | ||
login_mode | Top level item | Configures the account SPS uses to login to the ERPM server. | ||
plugin | string |
Must be used if the selection element is set to external_plugin. References the Credential Store plugin. You can find the list of available plugins at the /api/configuration/plugins/credentialstore/ endpoint. To modify or add a plugin, use the value of the returned key as the value of the plugin element, and remove any child elements (including the key). Plugins can only be uploaded using the web interface of SPS. | ||
proxy_server | string | The IP address and port of the proxy server. Use the http:// or https:// prefix. | ||
selection | string |
Configures the type of the credential store. Possible values are:
| ||
server_certificate_chec | Top level item | To verify the certificate of the ERPM server, configure server_certificate_check. | ||
web_interface_url | string | Name of the DN of the ERPM server. Use the http:// or https:// prefix. |
Elements of dns_servers | Type | Description |
---|---|---|
primary | string | The IP address of the primary DNS server. |
secondary | string | The IP address of the secondary DNS server. |
Elements of domain_mappings | Type | Description | |
---|---|---|---|
domain | string | The domain name used for Domain/Host mapping. | |
host | Top level item | The host name or address of the domain controller used for Domain/Host mapping. | |
selection | string |
Declares if the value element contains an IP or an FQDN. Possible values are:
| |
value | string | The IP address or hostname of the domain controller. |
Elements of encryption | Type | Description |
---|---|---|
selection | string |
Defines the encryption of the local credential store. Possible values are:
|
Elements of login_mode | Type | Description |
---|---|---|
password | string |
Must be used if the selection element is set to fixed_username. References the password SPS uses to authenticate on the ERPM server. You can configure passwords at the /api/configuration/passwords/ endpoint. To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key). |
selection | string |
Possible values are:
|
username | string |
Must be used if the selection element is set to fixed_username. The username SPS uses to authenticate on the ERPM server. |
Elements of server_certificate_check | Type | Description |
---|---|---|
enabled | boolean | Set to true to verify the ERPM server's certificate. |
trusted_ca | string |
Must be used if server certificate checking is enabled. References the list of trusted Certificate Authorities. You configure trusted CAs at the /api/configuration/policies/trusted_ca_lists/ endpoint. To reference a trusted CA list, use the value of the returned key as the value of the trusted_ca element, and remove any child elements (including the key). |
|
NOTE:
The following example is response only. Credential stores can only be configured using the web interface of SPS. |
Use a credential store plugin.
{ "name": "API_PLUGIN", "type": { "plugin": { "key": "2534221015734bb18aaf32", "meta": { "href": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32" } }, "selection": "external_plugin" } }
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 |
---|---|---|
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. |
The Welcome Wizard helps you complete the initial configuration of SPS. Starting with version 5 F4, you can complete the Welcome Wizard using REST as well.
GET https://<IP-address-of-SPS>/api/setup
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.
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 Request body.
curl -H "Content-Type: application/json" -d @body.json -X POST https://<IP-address-of-SPS>/api/setup/
|
NOTE:
The request automatically fails if there are any other clients connected to the REST or the web interface of SPS. |
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.oneidentity.com/legal/sta.aspx", "href": "/api/setup", "parent": "/api", "remaining_seconds": 0 }, "status": "completed" }
Element | Type | Description | |
---|---|---|---|
accept_eula | boolean | Indicates that you have read and accept the terms of the Software Transaction, License and End User License Agreements. Must be true to complete the Welcome Wizard. | |
network | JSON object | Contains the initial networking configuration of SPS. | |
license | string |
Your SPS 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, SPS will start in demo mode. To skip uploading the license, use the null value: "license": null, To upload a license file, see Upload a new license. | |
certificates | JSON object | Contains the initial certificates used on SPS: 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 SPS administrator. For example: "email": { "smtp_server": "smtp.example.com", "admin_email": "psm-administrator@example.com" }, | ||
datetime | JSON object |
Contains the timezone of SPS 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 SPS. | |||
hostname | string |
Name of the machine running SPS. 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 SPS (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,
| |||
gateway | 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 SPS. 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, SPS 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 SPS's internal Certificate Authority.: | |
webserver | JSON object |
The SSL certificate of SPS's web and REST interface. | |
tsa | JSON object |
The certificate of SPS's internal Timestamping Authority. |
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 |
---|---|---|
401 | WebGuiOrRpcApiConfigInProgress |
Web based or RPC API configuration is in progress — another client is connected to SPS. 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 SPS. { "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 } } |
© 2024 One Identity LLC. ALL RIGHTS RESERVED. Feedback Terms of Use Privacy Cookie Preference Center