How to Enable a RAD Remote Client Connection

The rad:remote service must be enabled, and the RAD server's certificate must be trusted on the client.

Enable the rad:remote instance.
```
# svcadm enable rad:remote
```
Ensure that the RAD server's certificate will be trusted.

Perform this procedure once per client. Choose the steps for your certificate source.
- RAD server is using a self-signed certificate.
  1. From the client, safely copy the server certificate to the client.
```
RADclient # scp user@RADserver:/etc/certs/localhost/host-ca/hostca.crt /etc/certs/CA
```
  2. Restart the ca-certificates service on the client.
```
RADclient # svcadm restart ca-certificates
```
- RAD server is using a CA certificate.
  1. Ensure that the certificate for the issuing CA is in the /etc/certs/CA directory on the client.
```
RADclient # ls /etc/certs/CA
...
Example-Security_EV_RootCA1.pem
Example-Security_RootCA2.pem
Example-Security_Root_CA.pem
...
```
  2. If necessary, restart the ca-certificates service.
```
RADclient # svcadm restart ca-certificates
```

Example 3-8 RAD Authenticating Using Version 1.0 of the Authentication Module

This example shows how to use the authentication module version 1.0 to connect to a remote server.

Establish a session and generate a token.

# 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/

If the username and password credentials are valid, you will get a response similar to the following:
```
Set-Cookie: _rad_instance=26368; Path=/api; Max-Age=3600
Set-Cookie: _rad_token=9432a53c-8034-4729-8cac-fb713a56827b; Path=/api;Max-Age=3600

{
        "status": "success",
        "payload": {
                "href": "/api/com.oracle.solaris.rad.authentication/1.0/Session/_rad_reference/2304"
        }
}
```
As the Set-Cookie implies, to resume a session, a client must present this cookie in the HTTP header as part of each future request. Because the Set-Cookie directive instructs the client to include this cookie in future requests, the session resumes automatically. In this example, invoking the curl command again with the same cookiejar file and a new request would result in RAD processing the new request as part of the initial session.
For subsequent requests, you would use the token, as shown in the following example:
```
# curl -v -X GET -c cookiejar -b cookiejar \
https://radserver.example.com/api/com.oracle.solaris.rad.zonemgr/1.0/Zone?_rad_detail
```
The _rad_token cookie contains a string token that is the external representation of the session. If the token needs to be directly accessed, you can obtain the string token by reading the session's token property. This value may be used to later gain access to the session by writing the token to the session's token property.

Only the owner of a session may delete and thus invalidate the session.

Note that a session token can be used across multiple connections, which allows an authenticated client to make multiple concurrent requests.

Example 3-9 RAD Authenticating Using Version 2.0 of the Authentication Module

This example shows how to use the authentication module version 2.0 to connect to a remote server.

Establish a session and generate a token that is sent back to the client in the form of an HTTP cookie.

# curl -b cookiejar -c cookiejar -X POST -H 'Content-Type:application/json' \
--data '{"username":"jdoe", "preserve":true}' \
https://radserver.example.com/api/authentication/2.0/Session/

The HTTP cookie is similar to the following:

Set-Cookie: _rad_token=9432a53c-8034-4729-8cac-fb713a56827b; Path=/api;Max-Age=3600

{
    "status": "success",
    "payload": {
            "href": "/api/com.oracle.solaris.rad.authentication/2.0/Session/_rad_reference/2560"
    }
}

Unlike the version 1.0 API, the session is not authenticated at this point. The server expects further interaction with client and user.

To determine the session state on the server, the client inspects it as follows:
```
# curl -b cookiejar -c cookiejar -X GET \
https://radserver.example.com/api/com.oracle.solaris.rad.authentication/2.0/Session/_rad_reference/2560/state
```
Sample response:
```
 {
    "status": "success",
    "payload": {
            "scheme": "PAM",
            "pam": {
                    "state": "CONTINUE",
                    "messages": [
                            {
                                    "style": "PROMPT_ECHO_OFF",
                                    "message": "Password: "
                            }
                    ],
                    "responses": null
            },
            "error": null,
            "generation": 1
    }
}
```
This response tells the client that the server (PAM) expects to continue the authentication conversation (string CONTINUE in the JSON structure). Note that the string is under the keys payload, pam, and state. Also, under the key messages, the server tells the client application to display the message "Password: " and to hide the user response "style":"PROMPT_ECHO_OFF".

The messages key can contain multiple messages. The client application must collect and respond to all of those in one subsequent HTTP request.

The possible values for "state" are:

CONTINUE

Server will send another set of messages to process

SUCCESS

Server successfully authenticated the session

ERROR

An error occurred when authenticating the session

The possible values for style are:
- PROMPT_ECHO_OFF
- PROMPT_ECHO_ON
- TEXT_INFO
- ERROR_MSG
For more information, see the pam_start(3PAM) man page.

The client application gathers the requested user input:

# curl -b cookiejar -c cookiejar -X PUT -H "Content-type: application/json" \
--data '{"value": {"pam": {"responses": ["secret"]}, "generation": 1}}' \
https://radserver.example.com/api/com.oracle.solaris.rad.authentication/2.0/Session/_rad_reference/2560/state

The client responds to the server by updating the state resource similar to the following:

{
      "status": "success",
      "payload": {
              "scheme": "PAM",
              "pam": {
                      "state": "SUCCESS",
                      "messages": null,
                      "responses": null
              },
              "error": null,
              "generation": 2
      }
}

Note that the server sends a generation number with each of its JSON payload responses. The client must repeat the same key and value in any of its subsequent requests to update the state resource.

This example shows that the RAD server used PAM to authenticate the user successfully in just one generation. However, because of the configuration of the PAM stack, the client must repeat the GET and PUT loop: (GET ... /state, gather the user's unput and PUT ... /state) for as long as the value of the state key remains CONTINUE.

Example 3-10 Interacting With RAD by Using the REST Authentication Module 2.0

Create a new authentication session.

# curl -b cookiejar -c cookiejar -X POST --header 'Content-Type:application/json' \
--data '{"username":"jdoe", "preserve":true}' \
https://radserver.example.com/api/authentication/2.0/Session/

Sample response:

{
     "status": "success",
     "payload": {
          "href": "/api/com.oracle.solaris.rad.authentication/2.0/Session/_rad_reference/2560"
     }
}

The preceding command creates a new authentication session for user jdoe, as shown in the response. Along with the response, the server sends HTTP cookies for the client to store and send back with every subsequent request to the server during this particular session.

Determine the state of the session.

The state key shows that PAM requires more input for successful session authentication.

# curl -b cookiejar -c cookiejar -X GET \
https://radserver.example.com/api/com.oracle.solaris.rad.authentication/2.0/Session/_rad_reference/2560/state

Sample response:

{
     "status": "success",
     "payload": {
             "scheme": "PAM",
             "pam": {
                     "state": "CONTINUE",
                     "messages": [
                             {
                                     "style": "PROMPT_ECHO_OFF",
                                     "message": "Password: "
                             }
                     ],
                     "responses": null
             },
             "error": null,
             "generation": 1
     }
}

For information about the meaning of the response, see RAD Authenticating Remote Clients.

In this example, PAM is configured for password-based authentication. Therefore, the client needs to send to the server the password that the client program gathered from the user:

# curl -b cookiejar -c cookiejar -X PUT -H "Content-type: application/json" \
--data '{"value": {"pam": {"responses": ["secret"]}, "generation": 1}}' \
https://radserver.example.com/api/com.oracle.solaris.rad.authentication/2.0/Session/_rad_reference/2560/state

Sample response:

{
        "status": "success",
        "payload": {
                "scheme": "PAM",
                "pam": {
                        "state": "SUCCESS",
                        "messages": null,
                        "responses": null
                },
                "error": null,
                "generation": 2
        }
}

The SUCCESS value of the state key indicates that the session is fully authenticated and the client can proceed with sending other requests to interact with different modules. Further success depends on the client sending back the session cookie(s), and the session cannot have expired.

If your system has non-global zones, send the following request.

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

Sample response:

{
     "status": "success",
     "payload": [
             {
                     "href": "api/com.oracle.solaris.rad.zonemgr/1.6/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.6/Zone/testzone2",
                     "Zone": {
                             "auxstate": [],
                             "brand": "solaris",
                             "id": 2,
                             "uuid": "358b43ba-32f9-4f27-9efa-de15ae4100a6",
                             "name": "testzone2",
                             "state": "running"
                     }
             }
     ]
}