Unlike in Oracle Solaris 11.3, RAD in Oracle Solaris 11.4 accepts REST connections locally with the rad:local SMF instance and remotely with the rad:remote SMF instance.
The rad:remote SMF instance is delivered disabled by default. When enabled, rad:remote expects RPC connections on port 12302 and HTTP/REST connections on port 6788. All remote communications with RAD are transported over TLS/HTTPS.
The rad:remote service must be enabled, and the RAD server's certificate must be trusted on the client.
# svcadm enable rad:remote
Perform this procedure once per client. Choose the steps for your certificate source.
RADclient # scp user@RADserver:/etc/certs/localhost/host-ca/hostca.crt /etc/certs/CA
RADclient # svcadm restart ca-certificates
RADclient # ls /etc/certs/CA ... Example-Security_EV_RootCA1.pem Example-Security_RootCA2.pem Example-Security_Root_CA.pem ...
RADclient # svcadm restart ca-certificates
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 54 RAD Authenticating Using Version 2.0 of the Authentication ModuleThis 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:
Server will send another set of messages to process
Server successfully authenticated the session
An error occurred when authenticating the session
The possible values for style are:
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 55 Interacting With RAD by Using the REST Authentication Module 2.0Create 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"
}
}
]
}