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.
URL
GET https://<IP-address-of-SPS>/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 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.
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.oneidentity.com/legal/sta.aspx",
"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 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. Example: "license": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><LicenseFile><Licenses><License Generator=\"File\" GeneratorVersion=\"3.0\" Signature=\"FEEDCAFE\"><Enterprise>true</Enterprise><LicenseNumber>123-456-789</LicenseNumber><LicenseType>Perpetual</LicenseType><ProductName>Safeguard for Privileged Sessions</ProductName><ProductVersion>7</ProductVersion><Property Name=\"Basic Proxies\">999999</Property><sudo-iolog>0</sudo-iolog><Analytics>True</Analytics></License></Licenses></LicenseFile>" 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. NOTE: Do not use IP addresses that fall into the following ranges:
| |||
| 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. TIP: 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. | |
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.
| Code | Description | Notes |
|---|---|---|
| 401 | WebGuiOrConsoleConfigInProgress |
Web-based or console 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 console configuration is in progress.",
"type": "WebGuiOrConsoleConfigInProgress"
},
"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": {
"message": "The configuration of the system is already initialized.",
"type": "ConfigurationAlreadyInitialized"
},
"meta": {
"href": "/api/setup",
"parent": "/api",
"remaining_seconds": 0
}
} |