Basic Access Authentication

This page offers guidelines for managing Authentication with the Context Services.

About Basic Authentication

Wikipedia Basic Access Authentication states that:

In the context of an HTTP transaction, the basic access authentication is a method designed to allow a web browser, or other client program, to provide credentials – in the form of a user name and password – when making a request.

The Context Services provides support for basic access authentication once enabled in the authentication section of your configuration.

• If basic access authentication is enabled, the REST requests must contain a valid username and password in the HTTP/HTTPS header. As a result, the Context Services sends descriptive error messages if it receives an incorrect username/password combination.
• If basic authentication is disabled, the Context Services ignores any username or password passed in HTTP/HTTPS header.

If the authentication is enabled and valid information is not provided, the Context Services returns the HTTP response 401 Unauthorized. In that case, you should resubmit the request with the proper authentication header.

Base64 Encoding

The authentication string to transmit is the result of the concatenation of the username and password separated by a colon (username:password). It must then be encoded with the Base64 algorithm. For example, if the username is 'kent' and the password 'superman', the string to encode is kent:superman and results in the string 'a2VudDpzdXBlcm1hbg=='.

If you are using a framework, it may provide the Base64-encoding transparently. If your framework does not include the Base64-encoding feature then you must encode your string. The following code snippet shows how to proceed with a Restlet application:

final Request request = new Request(); 
String url = "http://" + host + ":" + port + "/server/status"; 
request.setResourceRef(url); 
request.setMethod(Method.GET); 
final Client myClient = new Client(Protocol.HTTP); 
ChallengeResponse authentication = new ChallengeResponse(ChallengeScheme.HTTP_BASIC, "kent", "superman"); 
request.setChallengeResponse(credential); 
Response response = client.handle(request);

Important

Additional examples of Base64 encoding are available in Wikipedia Basic Access Authentication.

Request Flow and Returned Errors

The following sequence diagrams show the protocol request and answer flow when basic access authentication is enabled.

If the request returns the 401 Unauthorized error, your application should retry with a correct HTTP header. The Context Services returns 401 Unauthorized error due to authentication issues in the following scenarios:

• The authentication is enabled and the request is not authorized.
• The request provides the correct header for authentication, but wrong credential information (the username or the password is wrong).