Product Selector

Fusion 5.11
    Fusion 5.11

    User Access Request Parameters

    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"}