Login request and response using REST API

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)

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

Data Encryption

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

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

{ 
    "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.

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

2. 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" : [ ]
        } ]
     }
   }

3. 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
   }