Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

webui-service(7)

Name

webui-service - Oracle Solaris WebUI service

Synopsis

svc:/system/webui/server:default

Description

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:

/solaris

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.

/solaris/api/login

REST API used for user authentication

POST request

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:

state

The state component has one of the following values:

SUCCESS

Authentication completed successfully

CONTINUE

You are in the middle of an authentication conversation, and more information is needed to continue.

You need to process the messages fields appropriately.

ERROR

An unexpected error occurred in the RAD/REST Authentication module

messages

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:

PROMPT_ECHO_ON

Gather input from the user, enabling echoing of the response; for example, when PAM needs to know the username.

PROMPT_ECHO_OFF

Gather input from the user, disabling echoing of the response; for example, asking for the password.

TEXT_INFO

Display information to the user. Whether you need to acknowledge this or not depends on the UI being presented.

ERROR_MSG

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: "
    }
  ]
}
PUT request

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.


Note - There must be exactly as many items in the “responses” list as there were PROMPT_ECHO_ON and PROMPT_ECHO_OFF messages.

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).

GET request

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:

username

The username that is authenticated

An HTTP Unauthorized (401) error is returned if the cookie is invalid.

DELETE request

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.

/solaris/api/rad

RAD/Rest URL access point. Allows you to process a RAD query using REST over HTTPS.

POST request

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.

/solaris

Dashboard application landing page

/solaris/analytics

Analytics application landing page

/solaris/js

Unauthenticated directory used to store js framework files (JET)

The rest of the namespace can be used by other WSGI applications.

Options

The following configuration properties are members of the conf property group of the webui/server:default service:

listen_addresses

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.

cert_file

The default Certificate file location

cert_key_file

The default Certificate Key file location

ca_cert_path

The default CA Certificate path location

server_name

Value to be used as ServerName in the Apache configuration that the server uses to identify itself

absolute_timeout

Absolute maximum user session duration in minutes

default_landing_page

String that contain the relative namespace a user will be redirected to when requesting https://hostname:6787/

redirect_root_url

Boolean value to determine whether Apache should redirect the root URL (/) to the Solaris Dashboard application

redirect_from_https

Boolean value to determine whether the service should listen on port 443 and then redirect requests to port 6787

cipher_suite

Ciphers used by Apache

protocol

Security protocols used by Apache

IMPORT FORMATS

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.

Examples

Example 1 Listen on Port 443

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
true
Example 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.

See Also

sstore(1), libsstore(3LIB), analytics(5), analytics(7), attributes(7), ssid(7), sstore(7), sstoreadm(1), svcadm(8)

Notes

Use the svcadm command to perform administrative actions on the sstored service, such as enabling, disabling, or restarting the service.