RESTful Interface and RAD

The RESTful interface can be accessed by any HTTP client that supports either normal TCP (or TLS) connections or UNIX domain sockets. Two RAD SMF service instances provide the access:

rad:local

Enables communication with local HTTP clients that can communicate over UNIX domain sockets. Enabled by default. For more information, see the --unix-socket option in the curl(1) man page.

rad:remote

Enables communication over normal TCP sockets with HTTPS clients. Disabled by default.

Oracle Solaris 11.4 introduces RAD HTTP authentication API version 2.0. This updated API exposes the entire PAM (Pluggable Authentication Module) conversation. Developers can take advantage of the exposed PAM conversation to improve the user experience. The Oracle Solaris Analytics Web UI application uses this updated API.

Note:

Communication with RAD over HTTP uses the application/json content type only. The RAD server will refuse to communicate if a request states a payload content type or an Accept content type from the client that is not application/json.

The following example illustrates the REST interaction with RAD. Interacting With RAD by Using the REST Authentication Module 2.0 is a similar example that uses the API that handles multiple authentication requests, such as requests from an OTP application. These examples assume that you have installed the web/curl developer package.

For more information about the two distinct authentication APIs, see RAD Authenticating Remote Clients.

Example 3-1 Interacting With RAD by Using the REST Authentication Module 1.0

This example assumes that you have installed the web/curl developer package. The example illustrates a password-based PAM authentication stack, and shows how you can use RAD with non-global zones.

1. Create a new authentication session.

   Replace the username and password with values for any user on your system.

   # curl -X POST -c cookiejar -b cookiejar \
   --header 'Content-Type:application/json'
   --data '{"username":"username","password":"password","scheme":"pam","timeout":-1, "preserve":true}' \
   https://radserver.example.com/api/com.oracle.solaris.rad.authentication/1.0/Session/

2. Request a list of all the zones running on your system.

   # curl -H 'Content-Type:application/json' -X GET -b cookiejar \
   https://radserver.example.com/api/com.oracle.solaris.rad.zonemgr/1.0/Zone?_rad_detail

   Sample response:

   {
           "status": "success",
           "payload": [
                   {
                           "href": "api/com.oracle.solaris.rad.zonemgr/1.2/Zone/testzone1",
                           "Zone": {
                                   "auxstate": [],
                                   "brand": "solaris",
                                   "id": 1,
                                   "uuid": "b54e20c1-3ecb-407f-ad26-befed9221860",
                                   "name": "testzone1",
                                   "state": "running"
                           }
                   },
                   {
                           "href": "api/com.oracle.solaris.rad.zonemgr/1.2/Zone/testzone2",
                           "Zone": {
                                   "auxstate": [],
                                   "brand": "solaris",
                                   "id": 2,
                                   "uuid": "358b43ba-32f9-4f27-9efa-de15ae4100a6",
                                   "name": "testzone2",
                                   "state": "running"
                           }
                   }
           ]
   }

Example 3-2 Mapping the Connection to the root User

Create a Python script to connect to RAD, map the connection to the root user, and list all non-global and kernel zones that are present on the specified system, hostname. Run the script as the root user.

Note that the map_host_certificate_to_root property value must be true. See Configuring RAD Transports to Accept X.509 Client Certificates.

Ensure that your script contains the following Python 3 example code fragment:

import requests
import json
from pprint import pprint
r = requests.get('https://hostname>:6788/api/com.oracle.solaris.rad.zonemgr/1.8/Zone?_rad_detail', cert=('/etc/certs/localhost/host.crt', '/etc/certs/localhost/host.key'))
pprint(json.loads(r.text))

Note:

RAD over HTTP/REST permits a client to provide a certificate and hence permits it to perform non-interactive authentication. This behavior requires that the HTTP client support the sending of TLS client certificates.