Authentication

The API uses HTTP Basic Authentication to secure the API endpoints. Passing an authentication header over a secure communication protocol (HTTPS) is better than passing the username/password in the URL.

Basic Authentication Strategy

All endpoints starting with /api/repositories/{repository name}/ will be protected using Basic Authentication strategy, meaning users who access RESTful APIs will have to login (as detailed below) rather than their passing username/password within the URL.

Before you access any of the protected endpoints, you must first get the list of Repositories from the server.

To do this, you first need to access the Repositories endpoint, which does not require any authentication and will not prompt you for a username and password. The server returns a list of repositories in JSON format.

The first request to return the list of Repositories can be run in a browser. Thereafter, security is configured for the current session and any JSON application requests to protected endpoints should be made from a Restful client, such as Postman. Results are easier to view in a Restful client and Restful clients support more requests than browsers, which only issue GET requests.

Once you know the repositories available on the server, you can access endpoints supported for a given Repository by accessing any endpoint beginning with /api/repositories/{repository name}/ whilst also passing the basic authentication header (username/password) with the request. If the user authentication is successful, you should get back JSON formatted data for the given endpoint.

The API has several different ways to authenticate using an authentication header. You can format the authentication header as required to login using different user credentials as follows:

Login using username/password

Supply username and password.

Parameter	Type	Example
username	string	joe
password	string	bloggs

Login using new security (Windows/LDAP Security)

Supply username and password (as JSON formatted string containing session and sid).

Parameter	Type	Example
username	string	joe
password	string	{"session": "68aa8c73-87b5-495d-b38f-8addffc9c546", "sid": "1234"}

Login using old security

Supply username and password (as JSON formatted string containing session).

Parameter	Type	Example
username	string	joe
password	string	{"session": "68aa8c73-87b5-495d-b38f-8addffc9c546"}

Authentication Failures

If authentication fails, the server will respond as follows:

Response Code	Reason
401	Unauthorized.

Accessing APIs via Internet Browsers

When accessing any API endpoint starting with /api/repositories/{repository name}/ from any browser, it will prompt the user to enter their username and password via a dialog box (if not already authenticated).

Once successfully logged in, the browser caches this information and automatically includes the authentication header with any follow-on request made to the server.

Accessing APIs via RESTful Client

To access any API endpoint starting with /api/repositories/{repository name}/ from a RESTful client, an Authorization header must be created and added to the request.

The Authorization header is constructed as follows:

• Username and password are combined into a string joe:bloggs.
• The resulting string is then encoded to base64.
• The authorization method and a space is then put before the encoded string (i.e. “Basic ”)

For example, if the username is joe and password is bloggs, the header is formed as follows:

Authorization: Basic am9lOmJsb2dncw==

RESTful Client Login Page Support

A RESTful Client can authenticate a user via a login page before allowing them access to the rest of the application. This can be achieved by accessing the following endpoint whilst passing in the authentication header with the request.

GET /api/repositories/(string: repository)/login

GET /api/repositories/test/login

Parameter	Type	Purpose
repository	string	The name of the Repository to access

The request will result in one of the following status codes:

Response Code	Reason
200	Client successfully authenticated
400	Failed to authenticate the client

Code Examples

Here are some code examples showing how to add authentication headers to a request when using different NPM modules.

Using ‘request’ NPM module

var request = require("request");
var username = 'joe';

// Login using normal password
var password = 'bloggs';

// or

// Login using new security, set password string as follows
var passwordObject = {};
passwordObject.session = '68aa8c73-87b5-495d-b38f-8addffc9c546';
passwordObject.sid = '1234';
var password = JSON.stringify(passwordObject);

// or

// Login using old security, set password string as follows
var passwordObject = {};
passwordObject.session = '68aa8c73-87b5-495d-b38f-8addffc9c546';
var password = JSON.stringify(passwordObject);

// Once the password string is created

// - set the authentication header as follows:
request.auth(username, password, false).get('https://localhost:3000/api/repositories/test/');

// or

// - set the authentication header as follows:
request.get('https://localhost:3000/api/repositories/test/', {
    'auth': {
        'user': username,
        'pass': password,
        'sendImmediately': false
    }
});

Using ‘https’ NPM module

var https = require("https");

var username = 'joe';

// Login using normal password
var password = 'bloggs';

// or

// Login using new security, set password string as follows
var passwordObject = {};
passwordObject.session = '68aa8c73-87b5-495d-b38f-8addffc9c546';
passwordObject.sid = '1234';
var password = JSON.stringify(passwordObject);

// or

// Login using old security, set password string as follows
var passwordObject = {};
passwordObject.session = '68aa8c73-87b5-495d-b38f-8addffc9c546';
var password = JSON.stringify(passwordObject);

// Once the password string is created

// - set the authentication header as follows:
var options = {
   host: 'localhost',
   port: 3000,
   path: '/api/repositories/test/',
   // authentication headers
   headers: {
      'Authorization': 'Basic ' + new Buffer(username + ':' + password).toString('base64')
   }
};

// create a request using above options
var req = https.get(options, function(res){
    //....
});