Looking for the old site?

How To

Browse By

  • Objective

  • Products

  • User Role

    How To
    Documentation
      Learn More

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