webui-service - Oracle Solaris WebUI service
svc:/system/webui/server:default
The WebUI SMF service is an Apache instance that runs a WSGI application called the coordinator over HTTPS. By default, the WebUI listens on port 6787. To listen on port 443 and then redirect requests to port 6787, see Example 1, “Listen on Port 443.”
Self signed certificates are automatically generated at start time. Certificates can also be delivered during deployment, and shown in Example 2, “Setting up SSL Certificates.”
The coordinator is a minimal web application middleware that provides the following services for web applications:
User authentication
User session and RAD token protection
RAD-Rest request redirection
Authenticated file serving
These services are available through the REST API using the following namespace:
Reserved for the WebUI framework and all its applications. If the user is authenticated, it redirects to the dashboard application, otherwise, it redirects to the login page.
REST API used for user authentication
A POST request that contains in its body the following JSON payload will initiate a new PAM authentication conversation for the provided username:
{ "username": "username" "inactivity_timeout": timeout in minutes }
This request is processed through the RAD authentication module.
The username can be omitted. In that case, PAM will likely prompt you for the username, depending on its configuration. The username is a normal Oracle Solaris username.
The inactivity_timeout also is optional. The default value is 24h.
Upon success, a JSON payload is returned along with an auth-token cookie in its header.
Upon failure, an HTTP Unauthorized (401) error is returned.
The user session token validity is dependent on:
The session inactivity timeout specified in the request body
The absolute timeout, which can be modified through the coordinator/absolute_timeout SMF property
The associated hidden RAD token validity
This cookie can be reused to subsequently access RAD REST interfaces using the WebUI, and it also serves as a user session for the WebUI framework.
The returned JSON body has the following components:
The state component has one of the following values:
Authentication completed successfully
You are in the middle of an authentication conversation, and more information is needed to continue.
You need to process the messages fields appropriately.
An unexpected error occurred in the RAD/REST Authentication module
The messages component is a list of JSON objects that contain messages to be presented to the user interface. Messages have two elements: the message to be printed, and the style, which can be one of the following and requires specific behavior as described below:
Gather input from the user, enabling echoing of the response; for example, when PAM needs to know the username.
Gather input from the user, disabling echoing of the response; for example, asking for the password.
Display information to the user. Whether you need to acknowledge this or not depends on the UI being presented.
Display an error to the user. Whether you need to acknowledge this or not depends on the UI being presented.
The following is an example message:
{ "state": "CONTINUE", "messages": [ { "style": "PROMPT_ECHO_OFF", "message": "Password: " } ] }
A PUT request is used to continue the conversation that was initiated with the POST request, and feed back updates to the WebUI server.
The body of the request must contain at least the gathered response data, and looks like:
{ "responses": [ "password" ] }
If there were no responses you may replace the array with a NULL value in the JSON (as in the POST example above).
This might be the case if there were no prompts for data; for example, if it was just a TEXT_INFO message, not requiring a response.
On a successful submission of the responses, you will get a JSON payload that is like the case of the POST above, with a state and more messages if any more prompting is required.
On a successful completion, you will get a state value of SUCCESS. In this case you will get additional values in the payload as outlined in GET request below.
On a failed authentication, you will get an HTTP error code of 401 (Unauthorized).
A GET request that contains an auth-token cookie in its header will return a JSON payload if the cookie is valid.
If you are in the middle of a PAM authentication conversation, you will receive the same payload as you would from a POST or PUT when the state has a value of CONTINUE.
If you have a valid session that has been fully authenticated, then you will get a payload with the state value set to SUCCESS, and there will be some additional values in the JSON:
The username that is authenticated
An HTTP Unauthorized (401) error is returned if the cookie is invalid.
A DELETE request that contain an auth-token cookie in its header will attempt to delete both the user session and its associated RAD connection. Upon success, the following JSON payload is returned:
{ username: username }
On failure, an HTTP Bad request 400 error is returned.
RAD/Rest URL access point. Allows you to process a RAD query using REST over HTTPS.
Redirects a RAD-REST request with its JSON body payload to the internal rad-http daemon for processing.
For additional payload format information, see the RAD REST Developer Guide.
Dashboard application landing page
Analytics application landing page
Unauthenticated directory used to store js framework files (JET)
The rest of the namespace can be used by other WSGI applications.
The following configuration properties are members of the conf property group of the webui/server:default service:
List of ip:port strings conforming to Apache Listen directive format. If no value is specified, the web server listens on all available IP addresses using the default port.
The default Certificate file location
The default Certificate Key file location
The default CA Certificate path location
Value to be used as ServerName in the Apache configuration that the server uses to identify itself
Absolute maximum user session duration in minutes
String that contain the relative namespace a user will be redirected to when requesting https://hostname:6787/
Boolean value to determine whether Apache should redirect the root URL (/) to the Solaris Dashboard application
Boolean value to determine whether the service should listen on port 443 and then redirect requests to port 6787
Ciphers used by Apache
Security protocols used by Apache
The webui/server SMF service will import specifically formatted files in to the preferences system on startup and refresh. These files are defined by the applications installed; for example, the analytics(7) WebUI application provides an import format document in analytics(5).
If the import fails for any reason, the webui/server service will enter a degraded state to flag that the import failed. For details on the failure, see the webui/server SMF logs.
By default, the WebUI listens on port 6787. To listen on port 443 and then redirect requests to port 6787, set the value of the conf/redirect_from_https property to true.
$ svccfg -s webui/server:default svc:/system/webui/server:default> listprop conf/redirect_from_https conf/redirect_from_https boolean false svc:/system/webui/server:default> setprop conf/redirect_from_https=true svc:/system/webui/server:default> listprop conf/redirect_from_https conf/redirect_from_https boolean true svc:/system/webui/server:default> refresh svc:/system/webui/server:default> exit $ svcprop -p conf/redirect_from_https webui/server:default trueExample 2 Setting up SSL Certificates
Oracle Solaris 11.4 provides a self-signed certificate for use with the default webui/server configuration. Customers who have a properly signed certificate from a Certificate Authority (CA) might want to use that certificate instead.
To replace the self-signed certificate configuration, use the following procedure, substituting appropriate filenames:
# SVC=svc:/system/identity:cert # svccfg -s $SVC setprop certificate/cert/pem_value \ = astring: "$(cat /path/to/signed/certificate.crt )" # svccfg -s $SVC setprop certificate/cert/private_key/pem_value \ = astring: "$(cat /path/to/signed/certificate.key )" # svccfg -s $SVC setprop certificate/ca/pem_value \ = astring: "$(cat /path/to/issuer/certificate.crt )" # svcadm refresh $SVC # svcadm restart -sr $SVC
Restarting svc:/system/identity:cert results in svc:/system/webui/server also being started, due to SMF dependencies.
sstore(1), libsstore(3LIB), analytics(5), analytics(7), attributes(7), ssid(7), sstore(7), sstoreadm(1), svcadm(8)
Use the svcadm command to perform administrative actions on the sstored service, such as enabling, disabling, or restarting the service.