User Access Request Parameters

Table of Contents

Per-Request Authentication
Session Cookies

Fusion requests must come from a known user, i.e., a user with a unique user id (UUID). Fusion’s ZooKeeper registry tracks all users across all realms. Usernames must be unique within a realm. Fusion creates a globally unique user ID for all users based on the combination of username and realm.

All requests to the Fusion REST API require either a username, password, and security realm name, or the session cookie which contains the unique user ID.

Per-Request Authentication

To pass authentication information with each request, the realmName is specified as a query parameter on the request itself:

curl -u joe.smith:password123 "http://www.acme.com:8764/api/collections?realmName=acmeLDAP"

The default realmName parameter is "native", so for native authentication, this parameter can be omitted.

Session Cookies

The Fusion UI service endpoint "api/session" can be used to generate a session cookie which contains the unique user id via a POST request whose body consists of a JSON object which contains the username, password information. For users belonging to a realm other than the native realm, the request parameter "realmName" must be specified. The command to generate a session cookie for the admin user with password "password123" is:

curl \
 -c cookie -i -X POST -H "Content-type:application/json" -d @- \
 http://localhost:8764/api/session?realmName=native \
<<EOF
 { "username" : "admin" , "password" : "password123" }
EOF

The curl command takes any number of specialized arguments, followed by the URL of the request endpoint. The arguments used here are:

-c : filename of cookies file. If it exists, cookies are added to it. You can use -c - which writes to the terminal window (std out).
-i : include the HTTP-header in the output. Used here to see the cookie returned with the response.
-X : request method, in this case POST
-H : request header. The api/session endpoint requires Content-type:application/json.
-d : Pass POST body as part of the command-line request. To get ready the body from a file, use the syntax -d @<filename>. The argument -d @- reads the data from stdin.

The header output shows the cookie information:

HTTP/1.1 201 Created
Set-Cookie: id=996e4adf-bd04-4058-a926-8ea8ca08c05a;Secure;HttpOnly;Path=/api
Content-Length: 0
Server: Jetty(9.2.11.v20150529)

Once the session cookie file has been created, it can be sent along in all subsequent requests to the REST API. For the curl command-line client, the -b flag is used to send the contents of the cookie file to the server along with the request.

The following command sends a GET request to the Fusion REST API Collections service to check the status of the system_logs collection. The -b flag sends in a freshly generated session cookie.

> curl -b cookie -i http://localhost:8764/api/collections/system_logs

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Encoding: gzip
Vary: Accept-Encoding, User-Agent
Content-Length: 278
Server: Jetty(9.2.11.v20150529)

{
  "id" : "system_logs",
  "createdAt" : "2016-03-04T23:29:47.779Z",
  "searchClusterId" : "default",
  "commitWithin" : 10000,
  "solrParams" : {
    "name" : "system_logs",
    "numShards" : 1,
    "replicationFactor" : 1
  },
  "type" : "METRICS",
  "metadata" : { }
}

If the session cookie has expired, the system returns a 401 Unauthorized code:

> curl -b cookie -i http://localhost:8764/api/collections/system_logs

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 31
Server: Jetty(9.2.11.v20150529)

{"code":"session-idle-timeout"}