Returning a 401 status

This section was originally part of a blogpost in my LotusScript REST API series. Since this is an interesting topic and also relevant for other REST API solutions, I decided to create a separate blogpost on this topic.

When you browse to a Domino hosted website and authentication/authorization is required; you get a login page. This page is HTML and with status 200. This is not ideal when hosting a webservice on your site. First of all; the API client does not expect a 200 status when it is not authorized and second; it probably expects JSON instead of an HTML page.

Both issues can be solved. But you better make sure you have a good relationship wit the Domino administrator 🙂 .

Authentication and authorization issue

401 status

First of all, since Domino R9.0.1 FP10, it is possible to force the server to return a 401 status on the login page. This is done via a notes.ini setting.
DOMINO_FORCE401_WITH_HTML_LOGIN_PAGE=1

If set to 1, this will force your server to return a 401 status on the login page. Note that this is a server-wide setting; so if you configured multiple internet sites; they will all return 401.

Return JSON instead of HTML

A REST client probably does not know how to handle a login page. Therefore it is of no use returning an HTML login page when the client is not authorized to access your api.

However, you can return a meaningfull json message instead. To do so, we are going to create a custom login form in the Web Server Configuration Database. (Check out the HCL documentation for more information on this topic).

Open the Web Server Configuration Database (domcfg.nsf) in the designer and create a new form called ‘jsonUnauthorized’.

In the second tab of the Form properties; set the content type to ‘application/json’

Use the following text as content for the form:

{
	"status":"401",
	"error":"You are not authorized to perform that operation"
}

Save the form.

Now you have to configure your website tot use this form instead of the default login form.

Open the database in the Notes Client and click ‘Add Mapping’ to create a new mapping document.

Use the following settings to direct your API to the jsonUnauthorized form.

Use the host name address that will be used to address your REST APIs.

Note that I configure the mapping for a specific website/virtual server. If you select ‘All Websites/Entire server’; people will get the jsonUnauthorized form instead of a proper login form and therefore won’t be able to login on your server.

If you have a Domino Server that will be used for both browser interaction and REST applications, it is best to configure a separate Internet Site (with dedicated hostname).

This was the last episode of these series (for now). I hope you enjoyed it and are able to create your own REST APIs using LotusScript.