ShowTable of Contents
Overview of Domino Web Server Authentication
Whether you are building a web site, a native mobile application, or some other type of application,
Domino Access Services (DAS) is a good choice for integrating with Domino. DAS is a growing family of REST services including the data service, the calendar service and more. Creating, reading, updating and deleting resources on a Domino server is as simple as sending an HTTP request to a DAS service.
Most Domino resources, of course, are protected from anonymous access. When your application makes a DAS request, it usually must authenticate the request. So the question is: how do you authenticate a request to the Domino web server? The answer is, "It depends on how the Domino administrator has configured the server."
The Domino web server supports different authentication schemes including:
-
Basic authentication
-
Session authentication
-
SPNEGO (single sign-on with Windows)
-
SAML (available since Domino 9.0)
-
Various third-party single sign-on (SSO) extensions (for example, CA SiteMinder)
In other words, before your application can authenticate a DAS request you, the developer, must first know how the target Domino server is configured. This article explores both the Basic and Session authentication schemes in considerable detail. It does not cover SPNEGO, SAML or third-party SSO, however.
Comparison of Basic and Session Authentication
Basic authentication is a standard supported by all web browsers and HTTP servers. When you install a Domino server, Basic authentication is on by default, but an administrator can often change the configuration to use Session authentication instead. You can see if Basic authentication is enabled by using a browser to open names.nsf on the server. For example, if your host name is server.acme.com, open the following URL:
http://server.acme.com/names.nsf
Figure 1. shows the Basic authentication prompt displayed by Firefox. If you see a dialog like this, the server has Basic authentication enabled.
Figure 1. Firefox Basic Authentication Prompt
On the other hand, if you see a form-based prompt displayed, the server has Session authentication enabled. Figure 2. shows the default Session authentication form, but your Domino server could be configured to display a different form. Customers sometimes implement their own company branded, authentication form.
Figure 2. Form-based Session Authentication Prompt
IBM usually recommends Session authentication to Domino customers. This method is the best choice for traditional web applications. Unfortunately, Session authentication is not always ideal for other applications using REST services. To understand why, let us look at the technical details of both authentication schemes.
Basic Authentication Details
Let us assume your Domino server has both the calendar service and Basic authentication enabled. You can also assume your server includes a database named dlawson.nsf in the mail folder. To read a page of calendar events in dlawson.nsf, you can open the following URL in a browser:
http://server.acme.com/mail/dlawson.nsf/api/calendar/events
Figure 3. shows how the request is authenticated.
Figure 3. Basic Authentication Sequence Diagram
-
Assuming the initial GET request does not include an Authorization header, the Domino web server is unable to open dlawson.nsf. It returns HTTP 401 (Unauthorized) to the browser.
-
As a result, the browser displays the Basic authentication prompt (see Figure 1.).
-
When you enter the credentials, the browser encodes the user name and password in an Authorization header and then repeats the GET request. Now the Domino web server is able to authenticate the request. Assuming the credentials are valid, the web server forwards the request to the calendar service and the browser receives a JSON representation of the calendar events.
For most REST client applications, Basic authentication is much simpler to handle than Session authentication. However, Basic authentication has a major drawback for browser-based applications. Once a browser has authenticated with a server, it continues to send the Authorization header for each request to that server. As a result, there is no way for the user to log out except by closing all browser windows.
Session Authentication Details
Now let us assume your Domino server has Session authentication enabled. Again, to read a page of calendar events in dlawson.nsf, you can open the following URL in a browser:
http://server.acme.com/mail/dlawson.nsf/api/calendar/events
Figure 4. shows the flow for session authentication.
Figure 4. Session Authentication Sequence Diagram
-
Assuming the initial GET request does not include a DomAuthSessId cookie, the Domino web server is unable to open dlawson.nsf. As a result, it returns HTTP 200 to the browser. The response also includes an HTML authentication form (see Figure 2.).
-
When you enter the credentials, the browser sends them to the web server in a POST request. Assuming the credentials are valid, the web server returns an HTTP 302 code to the browser. This second response also includes a Location header (redirecting the browser to the original /mail/dlawson.nsf/api/calendar/events URL) and a Set-Cookie header with a DomAuthSessId cookie.
-
Finally, the browser repeats the GET request, this time with a valid session token in the DomAuthSessId cookie. The web server forwards the request to the calendar service and the browser receives a JSON representation of the calendar events.
Session authentication has two distinct advantages over Basic. First, the session ID has a time limit (usually 30 minutes). When the session expires, the user must authenticate again to establish a new session. Second, a well-written web application can provide a log out action to delete the session ID cookie.
Session authentication is not always ideal for applications using REST services, however. Since the session ID can expire at any time, virtually any request to a DAS service can result in a form-based authentication challenge. It can be difficult to distinguish such a challenge from a good DAS response because both have a status code of HTTP 200. Also, form-based authentication challenges work best in a browser-based web application. For example, a native mobile application is not as well suited to handling the challenge as a web browser is.
Authenticating a DAS Request from a Web Application
This article has shown how a DAS request is authenticated when you directly open the URL in a web browser. Of course, in an actual web application, a DAS request is usually sent when your JavaScript code calls the
XHR send method. The good news is the browser takes care of propagating all relevant Authorization and Cookie headers inside the XHR
send method. In other words, authentication is transparent as long as the web application has already authenticated with the Domino server.
However, you need to understand what happens when the XHR request results in an authentication challenge. This is particularly important for Session authentication. If Basic authentication is enabled, the browser will prompt for the user name and password inside the XHR request. On the other hand, if Session authentication is enabled, the HTTP response will be status code 200 followed by an HTML form. Your JavaScript code is expecting a JSON response, but instead it receives an HTML form -- not very intuitive!
One way to handle the difficulty of authentication challenges inside XHR is to completely avoid it. In other words, your application could require Basic authentication. This may sound tempting, but this article has already mentioned the drawbacks of Basic authentication in web applications. Instead, you should seriously consider supporting Session authentication.
Whenever your application makes an XHR request to a DAS service it should be prepared to receive an HTML form instead of a normal response. This article cannot be prescriptive about exactly how your application should handle the HTML form response. That will depend on your application framework (XPages, Dojo, jQuery, etc.), but your application needs to recognize the authentication challenge, display (or redirect to) a login prompt, restore application state (if necessary), and then retry the request.
Authenticating a DAS Request from Other Types of Applications
DAS is meant to be used by all sorts of applications -- not just browser-based, web applications. For example, if you are building a native mobile application, you are neither using XHR nor are you constrained by the way the browser handles Basic authentication. You can manage the user's credentials yourself and provide a way for the user to log out. In this case, you should consider using Basic authentication for all DAS requests.
The good news is Basic authentication works even when the Domino server is configured for Session authentication. You can send a valid Authorization header with each request and the Domino web server will use it in lieu of a DomSessAuthId cookie. This means a single Domino server can host both traditional web applications using Session authentication and native mobile applications using Basic authentication for DAS requests.
Of course, there is one potential problem. When your native mobile application uses Basic authentication against a Domino server configured for Session authentication, you cannot necessarily expect the web server to return HTTP 401 when the credentials are invalid. Usually, it will return HTTP 200 followed by an HTML form. A Domino administrator can change this behavior by creating a web site rule.
For example, Figure 5. shows a web site rule that forces the web server to use Basic authentication for all URLs matching */api/*.
Figure 5. Override Session Authentication Rule
If it is possible for your native mobile application to require such a web site rule, your application never needs to handle a Session authentication challenge. Before establishing this requirement, you should make sure that you and the administrator understand the potential side-effects for web application that use the same server for DAS requests.
Encrypting DAS Requests
This article has focused on authenticating DAS requests using the HTTP protocol. While you are developing an application in a private network, it is easiest to use the HTTP protocol, but you should consider requiring HTTPS when your application is deployed to a production environment. Whether you are using Basic or Session authentication, user credentials are sent as clear text over HTTP. The HTTPS protocol encrypts requests and responses, thereby protecting user credentials from network sniffers.
Conclusion
This article has discussed the benefits and drawbacks of both Basic and Session authentication. It has described the technical details of both authentication schemes and recommended some best practices including the following:
-
Web application developers making DAS requests should assume Session authentication and be prepared to handle a form-based authentication challenge inside each XHR request.
-
Developers of other applications (including native mobile applications) should use Basic authentication, securely manage user credentials, and understand the use of the Override Session Authentication rule.
-
In production, all DAS requests should ideally be encrypted over HTTPS. This protects user credentials and other sensitive data from network sniffers.