Personal favorites lotuser advanced series-use dsapi to customize user name and password authentication for Domino Web users

This article describes how to use the domino network server application ProgramThe Domino Web Server Application Programming Interface (dsapi) is used to customize user name and password authentication for Web users. A simple example is provided to describe how to use the interface on Windows, use Visual C ++ 6.0 to develop dsapi and how to register dsapi filters on the Domino server.

The World Wide Web uses the Hypertext Transfer Protocol (HTTP ). The HTTP protocol includes a simple name-and-password authentication mechanism. It uses the simple challenge/response protocol and requires the user to enter the user name and password, and verify the correctness of the password by comparing the user name and password saved on the server, to restrict user access to a specific page.

Set user name and password authentication on the Lotus Domino server. Generally, you need to create a personal document for each Web user and save the user name and password in the personal document. Personal documents can be stored in the Domino Directory, the secondary Domino Directory, or the external LDAP directory. Users without personal documents can only access anonymous servers and databases.

However, user names and passwords are not stored in personal documents. For example, user names and passwords are stored in external files or in other systems, and you do not want or cannot re-create personal documents for these users; or you want to adopt your own authentication solution. At this time, we can use the Domino Web Server Application Programming Interface (dsapi) to customize user name and password authentication for Web users.

Dsapi Introduction

Dsapi is a C-language application programming interface that allows you to write your own extensions for the Domino server ). During HTTP request processing, dsapi extensions, or dsapi filters, are triggered whenever a special event occurs.

Dsapi can be used to implement almost any user name and password authentication standard, regardless of whether the user name and password in the domino directory or the external LDAP directory are used, or the user name stored in the cookie, or other mechanisms.

In addition, you can use dsapi to control access to protected resources on the Domino server. Dsapi does not directly change the domino access control ). However, it allows you to directly set the user name authorized by the user, which can be used to access protected resources. In this way, dsapi developers can fully control the conversion or ing of login user names to a different user name, thus implementing access control for protected resources on the Domino server.

Back to Top

Dsapi filter operation process

The running process of a dsapi filter is as follows:

Running process of a dsapi Filter

1. event registration

A dsapi filter allows you to customize the HTTP request processing process. However, the server will send the event to the dsapi filter only if the dsapi filter has declared that this event is supported. Therefore, dsapi filters must first register events declared by themselves.

Currently, a total of 13 events can be captured by the dsapi filter. The number of events supported by a dsapi filter depends on your design and implementation. Theoretically, it supports any number of events. The implementation of the dsapi depends on the event declared by the filter. For various events, see Lotus C api reference (in Lotus c api toolkits ).

2. http request

The Web client initiates an HTTP request to the Domino HTTP server.

3. Event Notification

When the Domino server receives an HTTP request, it determines the type of the Request event. If a dsapi filter has declared that it supports this event, the server will send this HTTP event to this dsapi filter for processing. In this way, when a user accesses a resource on the server, you can use a custom authentication process to replace the normal Domino Web authentication process.

Back to Top

Main Entry functions (entry point) and structures

Dsapi provides multiple portal functions for the Domino server. Any dsapi filter must at least implement the following two entry functions:

1) initialize the Function

When the Domino HTTP service is started, the dsapi filter is loaded. After the filter is loaded, the initialization function is called. The initialization function is defined as follows:

Unsigned int filterinit (filterinitdata * filterinitdata)

Filterinitdata is a pointer to the filterinitdata structure. The filterinitdata structure contains several parameters required for dsapi filter initialization, which are defined as follows:

• Serverfilterversion: the input parameter. The server version of the filter.
• Appfilterversion: output parameter. Filter version. Set this parameter to kinterfaceversion.
• Eventflags: output parameter. Declares the type of event that the filter wants to process.
• Initflags: Not used currently.
• Filterdesc: output parameter. Brief description of the filter.

2) Event Notification Functions

The event notification function implements the filter function. When an event declared as supported by the filter appears, the event notification function is called. When the Domino server calls the event notification function, it passes the corresponding information in the HTTP request to this function, and the event notification function determines whether to process the given event. The event notification function is defined as follows:

Unsigned int httpfilterproc (filtercontext * pcontext, unsigned int eventtype, void * peventdata)

Where:

• Pcontext is a pointer to the filtercontext structure. Data in the filtercontext structure includes HTTP request information, server callback function pointer, and a pointer pointing to the data context of the filter.
• Eventtype indicates the current event.
• Peventdata is a pointer to a structure. The specific type of this structure depends on the eventtype type. Different events correspond to different event data structures.

In addition, there are some optional entry functions, including the entry functions used to process suspensions and the entry functions used to process threads. You can choose to implement these entry functions as needed. For more information, see Lotus C api reference.

All entry functions return an unsigned int status code. The possible values are as follows:

• Kfilterhandledrequest: indicates that the HTTP request has been completely processed. The response has been sent to the client, and the HTTP stack can stop processing the request.
• Kfilterhandledevent: indicates that the event has been processed. Others can further process HTTP requests.
• Kfilternothandled: indicates that the filter has not handled the event.
• Kfiltererror: indicates that the filter encountered an error during event processing. In this case, the HTTP stack stops processing requests and sends an error message to the user.

Back to Top

Dsapi programming example

Below is a simple example to illustrate how to use dsapi to customize user name and password authentication for Web users. User names and passwords are stored in an external file. Only web users with the correct usernames and passwords can access protected databases on the Domino server. This example is developed on the Windows platform and Microsoft Visual C ++ 6.0 is used as the development tool. RoutineSource codeSee the attachment npauth. C. The entire process includes four steps:

• Dsapi Filter Implementation
• Domino server configuration
• Database Access Control Configuration
• Run dsapi Filter

1. dsapi Filter Implementation

In UNIX, The dsapi filter is compiled into a shared library, while in Windows, it is compiled into a dynamic Connection Library. Dsapi is supported by all Domino server platforms. Dsapi functions are included in Lotus c api toolkits, which can be downloaded from the URL below: http://www.ibm.com/developerworks/lotus/downloads/toolkits.html

First, we use visual c ++ to create a project and complete the relevant configuration:

• Use Visual C ++ to create a Win32 dynamic Connection Library Project
• Set the corresponding path, including the header file path and Lib file path of Lotus c api. You can find the corresponding path in the downloaded Lotus c api toolkits.

In this example, we only need to implement the two most basic entry functions.

1) initialization

Unsigned int filterinit (filterinitdata * filterinitdata) {/* This is requiredCodeTo specify the interface version */filterinitdata-> appfilterversion = kinterfaceversion;/* to declare the supported event types to the server. Kfilterauthenticate indicates that the filter processes * user name and password authentication. When the HTTP stack is in the authentication stage, the kfilterauthenticate event appears. * If the filter supports multiple events, use "|" to merge them. * For example, kfilterauthenticate | kfilterrewriteurl. */Filterinitdata-> eventflags = kfilterauthenticate;/* filter Description */strcpy (filterinitdata-> filterdesc, "file system authentication filter"); Return kfilterhandledevent ;}

2) Event Notification

Unsigned int httpfilterproc (filtercontext * pcontext, unsigned int eventtype, void * peventdata) {/* The structure type of the kfilterauthenticate event is filterauthenticate, * For details, see the routine Description */filterauthenticate * authdata = NULL;/* determine whether the event is supported by the filter. In the filterinit () function, * We declare that the event type supported by the filter is kfilterauthenticate. */If (eventtype! = Kfilterauthenticate) return kfilternothandled;/* converts peventdata to the corresponding data structure */authdata = (filterauthenticate *) peventdata according to the event type;/* authdata-> If foundincache is true, indicates that the user has discovered it in the internal cache of Domino. * If the filter is not processed, kfilternothandled is directly returned. * The Domino server authenticates the user based on the information in the cache */If (! Authdata | authdata-> foundincache) return kfilternothandled;/* Verify the user password */If (authdata-> username & authdata-> password) {char * Password = NULL; /* obtain the password from an external file based on the user name. It is flexible and flexible to obtain the password from where and * and how to obtain the password. * You can implement this function on your own. */If (0 = getuserpassword (pcontext, (char *) authdata-> username, & password) {/* copy the user name to authname, this is the format required by dsapi */strncpy (char *) authdata-> authname, authdata-> username, authdata-> authnamesize ); /* compare whether the Password Matches */If (strcmp (authdata-> password, password) = 0)/* the password is verified successfully */authdata-> authtype = kauthenticbasic; else/* password Verification Failed */authdata-> authtype = knotauthentic; return kfilterhandledevent ;}} return kfilternothandled ;}

First, the program needs to determine whether the event type is supported. Based on different events, peventdata is converted into different structures. The structure type of the kfilterauthenticate event is filterauthenticate. The definition of this structure can be found in the header file dsapi. h. The important variables include:

• Username: the input parameter. User name.
• Password: the input parameter. Password entered by the user.
• Authname: the input parameter. A pointer pointing to the authorized user name. We can use this variable to control Domino access control.
• Authtype: output parameter. Indicates whether the authentication is successful.

L

Foundincache: input parameter. If the user already exists in the internal cache of Domino, the variable will be set to true. This variable allows us to authenticate authenticated users without repeating the authentication.

We can verify the input user name and password against the saved user name and password. This process is flexible and free. The username and password can be stored in the Domino Directory, in the database, in an external file, or in the cache. This depends entirely on our design. Therefore, we can implement a custom Password Authentication Scheme and the Single Sign-On function (SSO ).

2. Domino server configuration

We will compile the code and copy the DLL file obtained after the link is successful to the program directory of the Domino server. Note that it is not the data directory of the Domino server. Then register the dsapi filter on the Domino server.

• Open the directory database (names. nsf) on the Domino server and select the server document.
  
• Select Internet protocols-HTTP ". Enter the User Name of the DLL file in "dsapi filter file names.
  

3. Database Access Control Configuration

To allow authenticated users to access protected resources in the database, we need to implement database access control. There are two methods to achieve this:

• Create personal document for authorized users

  we can use the domino administrator tool to register a new user account on the Domino server. Note: The short name of the new user account must be consistent with the user name to be authorized. For example, if the username to be authorized is myuser, register a user account on the Domino server. The short name must be "myuser ". Then, open the database ACL management and add myuser to the database ACL. In this way, the authorized user name in the database is the same as the authenticated user name in dsapi. After dsapi authentication is successful, users can access the protected database.

• using dsapi programming

  if we do not want to create a personal document for users, we can use programming to control access permissions. The variable authname in the structure filterauthenticate is used to store the authorized user name. Therefore, even if we do not create a separate personal document for the user, we can also grant the user the permission to access protected resources. The implementation method is very simple, as long as you set the authname to a user name with permissions. For example, the database ACL contains the 'notes id' with the permission: myuser/China/mycom. This ID may not exist in any Domino Directory. In the httpfilterproc () function, we can rewrite the italic bold code into the following code:

  strncpy (char *) authdata-> authname, "cn = myuser/ou = China/o = mycom", authdata-> authnamesize)

4. Run the dsapi filter.

Restart the Domino server. The following information is displayed on the server console:

Dsapi file system authentication filter loaded successfully.

Enter the URL <Domino-Server>/<Domino-server-database> on IE to open the database on the Domino server. <Domino-Server> is the username or IP address of the Domino server. <Domino-server-database> is the username of the database. For example, myserver/npauth. nsf. Then, in the pop-up user name and password dialog box, enter the user name and password to access the restricted database.

Conclusion

Dsapi allows us to expand the Domino server and customize user name and password authentication for Web users. It provides greater flexibility for integrating domino into the existing environment and generating Single Sign-On (SSO.