REST API for Administering Oracle NoSQL Database

Authentication

Before you use REST API calls to administer Oracle NoSQL Database, ensure the following prerequisites are met.

Ensure that you have the appropriate log-in credentials for accessing Oracle NoSQL Database.
Ensure that the admin-web-port in the Oracle NoSQL Database is configured and the admin web service is started. See makebootconfig in Oracle NoSQL Database Administrator's Guide.

Use the following URL for security login:

/V0/nosql/admin/login

You must provide basic login information encoded in base64 in the authorization header. Note that Basic is used as prefix here: Authorization:Basic base64_encode(user_name:password)

An example of a login token is shown below. The string inside the token parameter is a sample login token.

"returnValue" :
      {      "token" :
        "ACED00057722001900000177B4AE29670102105DB5C6928D2CC2C5615627E1BC5C68B10500000001" }

Data Encryption

While connecting to a secure KVStore, you must provide the certificate information obtained from the client.trust file. The client.trust file is created under the security folder of the storage node while you configure a secure KVStore. This client.trust file is specifically used for the client to access the KVStore.

Create a certificate file in PEM format using the client.trust file provided by the KVStore. Below is an example of using the certificate information from the client.trust file:
```
keytool -exportcert -rfc -keystore KVROOT/security/client.trust -alias mykey \
-file /tmp/client_security_dir/security/client.pem
```
Modify the /etc/hosts file to match the target NoSQL server machine's host name as specified in the server certificate, which defaults to "NoSQL". Since the cURL command uses default host name verifier, the host name entity in client.pem file is NoSQL by default. If you are using cURL or other tool with no capability of setting customized host name verifier, you must modify the /etc/hosts to match the target NoSQL server machine's host name to NoSQL
```
#/etc/hosts file
127.0.0.1    localhost  NoSQL
```
Note:
The value NoSQL is added in the /etc/hosts file here as the certificate generated by the makebootconfig command specifies NoSQL in the certificate. if you are using a user-supplied certificate, this value will be different.

Ensure that the admin-web-port is configured and the admin web service is started. Access the login interface to acquire the login token.

curl -i "https://NoSQL:port/V0/nosql/admin/login" -u username:password \
--cacert /tmp/client_security_dir/security/client.pem --tlsv1

For anonymous login from the machine where admin service is running, use the cURL command like below:

curl -i "https://NoSQL:port/V0/nosql/admin/login" \
--cacert /tmp/client_security_dir/security/client.pem --tlsv1

Security Session

The admin web service shares the same security session parameter as the existing RMI based NoSQL security parameter. The following parameter controls the timeout of a security session:

sessionTimeout = 24 hours

Response to the login request

The example response to the login request is as shown below:

HTTP/1.1 200 OK
access-control-allow-origin: *
content-type: application/json
content-length: 221

{
   "operation" : "login",
   "returnCode" : 5000,
   "description" : "Operation ends successfully",
   "returnValue" : {
      "token" : "ACED00057722001900000177B4AE29670102105DB5C6928D2CC2C5615627E1BC5C68B10500000001"
   }
}

Security of the Login Token

The login token returned above is equivalent to user credentials. The token expires on log out or after the expiration time period. You must protect the login token during its validity to ensure unauthorized access.

After you retrieve the login token, you must set the token in the Authorization header before making a request on the admin web service. Note that Bearer is used as prefix here:

Authorization:Bearer 
"ACED00057722001900000177B4AE29670102105DB5C6928D2CC2C5615627E1BC5C68B10500000001"

The admin web service checks for authentication and authorization for access control every user request.

Logout using REST API

Use the following URL to log out:

/V0/nosql/admin/logout

After executing the requests, log out of the session. To log out of an existing session, provide the login token within the Bearer prefix. For example:

curl -i "https://NoSQL:port/V0/nosql/admin/logout" \
--cacert /tmp/client_security_dir/security/client.pem \
-H "Authorization:Bearer login_token_in_hex_string" --tlsv1

The example response to the logout session is a s shown below.

{ 
    "operation" : "logout", 
    "returnCode" : 5000,   
    "description" : "Operation ends successfully",  
    "returnValue" : null
}

Workflow while using REST API calls

Lets consider an example of executing the show topology command using REST API calls.

Bearer authentication is an HTTP authentication scheme that involves security tokens called bearer tokens. The bearer token allows access to a certain resource or URL, and is an encrypted string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to the protected resources.

Here is an example of how to login, use the login token to access security resources, and then log out.

Obtain Login token: Access the login interface to acquire the login token.

$ curl -i "https://NoSQL:port/V0/nosql/admin/login" -u <userName:password> \
--cacert "/tmp/client_security_dir/security/client.pem" --tlsv1

The example login response is as shown below.

HTTP/1.1 200 OK
access-control-allow-origin: *
content-type: application/json
content-length: 221
{
  "operation" : "login",
  "returnCode" : 5000,
  "description" : "Operation ends successfully",
  "returnValue" : {
  "token" : "ACED00057722001900000177B4AE29670102105DB5C6928D2CC2C5615627E1BC5C68B10500000001"
  }
}

The login token returned in the above code is equivalent to user credentials. The token expires on log out or after the expiration time period.

Issue command to administer Oracle NoSQL Database: The admin web service checks for authentication and authorization for access control every user request. The show topology request is issued using the login token generated in the above step.

$ curl -i -X POST "https://hostname:port/V0/nosql/admin/topology" \-d
      '{"command":"show"}' --cacert "/tmp/client_security_dir/security/client.pem"
      \-H "Authorization:Bearer ACED00057722001900000177B4AE29670102105DB5C6928D2CC2C5615627E1BC5C68B10500000001"
      --tlsv1

The example response of the show topology command is as shown below:

HTTP/1.1 200 OK
access-control-allow-origin: *
content-type: application/json
content-length: 1001
{
   "operation" : "show topology",
   "returnCode" : 5000,
   "description" : "Operation ends successfully",
   "returnValue" : {
   "storeName" : "mystore",
   "numPartitions" : 20,
   "sequenceNumber" : 24,
   "zns" : [ {
      "resourceId" : "zn1",
      "name" : "1",
      "repFactor" : 1,
      "type" : "PRIMARY",
      "allowArbiters" : false,
      "masterAffinity" : false
   } ],
   "sns" : [ {
      "resourceId" : "sn1",
      "hostname" : "localhost",
      "registryPort" : 20000,
      "zone" : {
         "resourceId" : "zn1",
         "name" : "1",
         "repFactor" : 1,
         "type" : "PRIMARY",
         "allowArbiters" : false,
         "masterAffinity" : false
     },
     "capacity" : "1",
     "rns" : [ {
        "resourceId" : "rg1-rn1"
      } ],
     "ans" : [ ]
     } ],
     "shards" : [ {
         "resourceId" : "rg1",
         "numPartitions" : 20,
         "rns" : [ {
           "resourceId" : "rg1-rn1",
           "snId" : "sn1"
          } ],
         "ans" : [ ]
     } ]
  }
}

Logout of the session: After executing the requests, log out of the session.

$ curl -i "https://hostname:port/V0/nosql/admin/logout" \--cacert /tmp/client_security_dir/security/client.pem
        \-H "Authorization:Bearer 
          ACED00057722001900000177B4AE29670102105DB5C6928D2CC2C5615627E1BC5C68B10500000001"
        --tlsv1

The example response to the logout session is as shown below.

{
   "operation" : "logout",
   "returnCode" : 5000,
   "description" : "Operation ends successfully",
   "returnValue" : null
}