1. Session Module: session.xq

The optional Module session.xq provides simple RESTful services enabling you to perform Authentication at the Application Level instead of other methods such as HTTP Digest or HTTP Basic Authentication.

The library serves as a starting point to you building your own custom Authentication mechanism for your users.

2. Register the RESTXQ module

If you're using the XQRS Gradle Plugin then this module is already installed and ready to go under the ml-modules/root/xqrs/optional-libraries directory. If you're not using Gradle, download the session.xq module and add an import statement to it in your xqrs.xqy file, e.g.

import module namespace session =
  "http://xmllondon.com/xquery/session" at
  "optional-libraries/session.xq";

There are 3 RESTful Services

3. User Log-in with /session/login

You can submit a POST request containing the user credentials in either XML or JSON format.

<auth>
  <user>john.smith</user>
  <password>password123</password>
</auth>

{
  "user" : "john.smith",
  "password" : "password123"
}

The service will respond with either a 200 - Success status and a Cookie such as SessionID=6045388ef271f4e7; path=/ meaning that you have successfully logged in, or it will respond with a 401 - Unauthorized status in which case there was an Authentication issue.

The Session Cookie issued upon a successful login is the token you must to send back on all subsequent RESTful requests so that MarkLogic Server knows who you are.

All RESTful requests executed with the Session token happen within the context of the user's active session.

4. Checking status with /session/status

This service will tell you which user you are logged in as and which roles it has, it will give either a XML or JSON response depending on what the client prefers (Content Negotiation).

<info>
  <user>john.smith</user>
  <roles>
    <role>custom-write</role>
    <role>custom-read</role>
    <role>custom-execute</role>
  </roles>
</info>

{
  "user" : "john.smith",
  "role" : [ "custom-write",
             "custom-read",
             "custom-execute" ]
}
  
  

5. Logging out with /session/logout

Sending a request to this service logs the user out and will delete the Session Cookie which was originally issued on the first log-in. This service should always respond with a 200 - Success status.