Authentication

1. Basic authentication

When logging in the user, a request containing the header Authorization must be included. The content of this header must have the following format:

Basic base64StringOfUsernameAndPassword

The Base64String must decode to the following format:

{username}:{password}

Example: if the user has the username 'user' and the password 'password' then you must encode in Base64 the string user:password. The result of the encoding is dXNlcjpwYXNzd29yZA==. Therefore, the content of the Authorization header must be Basic dXNlcjpwYXNzd29yZA==.

How does the API use this?

The API will check for the existence of an Authorization header with that exact content for every single request made. It is recommended to make a request to the dummy action 'Authentication' of the controller 'Users' for security and client compliance reasons (see example for exact URL). The action can only be called via the 'POST' method.

If the correct header is found, the credentials will be extracted and the confirmed against the on-campus LDAP server. If the user is not on campus, not using Jacobs VPN, not using a secure connection (i.e. https protocol), and / or the credentials don't check out, an according message will be returned by the API.

However, if everything is fine with the connection and the credentials do check out, then a unique sessionId of type GUID will be returned to the client. Every subsequent call to the API must not contain the Authorization header anymore.

To learn how to properly embed the sessionId in the subsequent API calls, please refer to the Authorization section of this Wiki.

Example of how to get and store the sessionId (Javascript):

var sessionId = "";
var url = "api/Users/Login";
var headers = new Array();
headers["Authorization"] = "Basic" + " " + btoa($("input#username").val() + ":" + $("#password").val()); //Base64 encoding
 
$.ajax({
        url: url,
        type: "POST",
        headers: headers,
        success: function (data) {
             sessionId = data;
             // LET THE USER KNOW THAT HE CHECKS OUT
         },
         error: function (jqXhr, textStatus, errorThrown) {
             // ERROR HANDLING
         }
    });

2. SSH Key

** WORK IN PROGRESS **