Skip to main content link. Accesskey S
  • Help
  • HCL Logo
  • HCL Notes and Domino Application Development wiki
  • THIS WIKI IS READ-ONLY. Individual names altered for privacy purposes.
  • HCL Forums and Blogs
  • Home
  • Product Documentation
  • Community Articles
  • Learning Center
  • API Documentation
Search
Community Articles > Developing Applications > Using Domino REST Services > Authenticating Domino REST Service Requests
  • Share Show Menu▼
  • Subscribe Show Menu▼

Recent articles by this author

Create your own Domino REST service using DAS

Domino Access Services (DAS) is a framework for adding REST services to Domino. This article explains how you can implement your own REST service using DAS. The article assumes you are comfortable writing software in the Java programming language and are willing to learn about advanced topics like ...

Authenticating Domino REST Service Requests

Domino Access Services (DAS) is a family of REST services that provides access to Domino resources over HTTP and HTTPS. As a developer you can now integrate with Domino from virtually and web browser, device or OS. It's easy to get started with DAS, but before you can develop a practical ...

Password statistics resource

Provides access to password statistics for an authenticated user.

Nonce resource

Provides access to a token used in subsequent requests for CSRF protection.

Core service reference

This reference specifies and provides examples for resource methods that access core services on Domino® servers.
Community articleAuthenticating Domino REST Service Requests
Added by ~Helga Nimkivitchoden | Edited by ~Maria Reponeterikle on February 24, 2014 | Version 21
  • Actions Show Menu▼
expanded Abstract
collapsed Abstract
Domino Access Services (DAS) is a family of REST services that provides access to Domino resources over HTTP and HTTPS. As a developer you can now integrate with Domino from virtually and web browser, device or OS. It's easy to get started with DAS, but before you can develop a practical application, you must understand how the Domino web server authenticates REST requests. This article describes both Basic and Session authentication and recommends best practices for your application.
ShowTable of Contents
HideTable of Contents
  • 1 Overview of Domino Web Server Authentication
  • 2 Comparison of Basic and Session Authentication
  • 3 Basic Authentication Details
  • 4 Session Authentication Details
  • 5 Authenticating a DAS Request from a Web Application
  • 6 Authenticating a DAS Request from Other Types of Applications
  • 7 Encrypting DAS Requests
  • 8 Conclusion

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

 

 

  1. 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.  
  2. As a result, the browser displays the Basic authentication prompt (see Figure 1.).  
  3. 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

 

 

  1. 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.).  
  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.  
  3. 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.

  • Actions Show Menu▼


expanded Attachments (0)
collapsed Attachments (0)
Edit the article to add or modify attachments.
expanded Versions (1)
collapsed Versions (1)
Version Comparison     
VersionDateChanged by              Summary of changes
This version (21)Feb 24, 2014, 6:13:38 PM~Maria Reponeterikle  
expanded Comments (0)
collapsed Comments (0)
Copy and paste this wiki markup to link to this article from another article in this wiki.
Go ElsewhereStay ConnectedAbout
  • HCL Software
  • HCL Digital Solutions community
  • HCL Software support
  • BlogsDigital Solutions blog
  • Community LinkHCL Software forums and blogs
  • About HCL
  • Privacy
  • Accessibility