Secure crawls of Lotus Notes with SharePoint
I recently had to prove SharePoint's ability to search Lotus Notes databases including honoring security. This meant that a user who did not have access to the Notes database should not see search result items in SharePoint. After having to dig through several how-to guides, knowledge base articles, and hotfixes, I finally got the solution to work and thought that I would post my configuration and include a lot of screen shots that I thought were lacking in other materials.
The POC Environment
With my "proof-of-concept", I had a medium SharePoint Server Farm of 2 front-end servers, an index server, and a SQL backend. Security and "locking down" of the servers was not a priority of the POC, I simply had to show that I could honor the user security settings of Notes in a SharePoint Search. For SharePoint, my server were running under a domain account: dodagency\spsservice. My default content access account was dodagency\spsindex. My Lotus Notes server was verion 6.5. I later found out that Microsoft technically only supports 4.5 and R5 versions of Lotus Notes. I did however get this to work successfully anyway. My SharePoint Portal Servers were running Windows Server 2003 SP1 before SharePoint was installed. And I made sure that I had SP1 of both WSS and SPS before I started configuring the Notes indexing.
Just a note that I used Paint to replace some of the text names of the accounts just so my customer would be protected. So if you notice the funny font or an off character size that is why.
Preparing Lotus Notes
- Create a Notes account for the default access account (spsindex)
Lotus Accounts Screen Shot - Make sure this account has read access to the server's directory (names.nsf database)
- Make sure this account has read access to the database you wish to search. This can be done by using the ACLs on the Notes database:
Lotus ACL Screen Shot - Ultimately, we will need a view of the names.nsf database that has the NotesID (Owner) column and a column with the Windows Active Directory account. To store the domain\username string representing the WIndows AD account, I used the already created Comments Field. You could use any field or create a new one, but I went for the easy path.
Comments Field Screen Shot - Now Create a new shared view in the server's directory (names.nsf) database. The view needs two columns: NotesID and WindowsID. The NotesID column needs to map to the Owner field of the names.nsf database and the WindowsID column maps to the Comments field in my configuration. The view should only include individual user accounts and not groups. Therefore the view filters for Type="Person". Despite the screen shot below, the view should be sorted on the NotesID column in ascending order. (It was too difficult to paste everything in when I modified the text). The first screen shot is the definition of the view, and the second is what the resulting view should look like.
Definition of View screen Shot
View Screen Shot
Configuring SharePoint's Index Server
This next session documents the steps I took to configure the index server. The steps here are about configuring the server not content sources and indexes. Those steps follow this section.
- On my index server, I had to make both the dodagency\spsservice and dodagency\spsindex accounts members of the Local Administrator group. I originally had just the spsservice account as a local admin, but found that my indexing process caused the Notes client to hang. I figured that this must have been a permissions issue with the automation script. Making the spsindex account (my default content access account) a local admin fixed this just fine. Again, I was interested in locking down my environment, just gettting it to work!
- On the index server, you must install and configure a R5 Notes client (I used 5.0.11). This is despite the fact that we are searching a R6 Notes server. The protocol handler is coded against the R5 API. When installing the client, choose a nice easy name for the installation folder and place it in the root of the drive. C:\Lotus\Notes works just fine. Avoid special characters and even spaces as it may cause problems.
- After the installation creates this directory, go back and grant the SPS_WPG full control to the Lotus directory and all sub-items.
- With your client, you should configure the UserID so that you can log into the client with the SharePoint account you created in the previous section. Be sure to note the password you are using as you will need to re-enter that in the config of the protocol handler. It is important to remember that once you have everything configured, you should never open the Notes client on the index server. Doing so could mess up your config and may require a reboot to get the planets to align again.
- Not all client installations add the Lotus directory to the machine's PATH. Modify the machine's environment variables to include the C:\Lotus\Notes value. Note that this modification will not be presented to running services until after a reboot. So reboot!
- It turns out that before configuring SharePoint's Notes protocol handler, you need to obtain a dll from IBM that it uses. Download the following zip file (ftp://ftp.software.ibm.com/software/lotus/fixes/domino/5.x/Dols\_iis.zip) and extract the lcppn201.dll file from it. This file needs to be placed in the C:\Program Files\SharePoint Portal Server\Bin folder.
- Run NotesSetup.exe. This is the setup program for SharePoint's Notes protocol handler. It is located in the C:\Program Files\SharePoint Portal Server\Bin folder. The following screen shots walk you through the wizard:
Notes Setup Screen 1: specify the location you installed the Notes ini file and the client (C:\Lotus\Notes\notes.ini and C:\Lotus\Notes). My system detected this settings. Then enter the password for the Notes UserID. Since we want to honor security, do not check the checkbox at the bottom of the screen.
Notes Setup Screen 2: specify the configuration infromation of where the protocol handler will find our mapping view. For my settings, I entered the name of the server (dodlotus), the name of the address book (names.nsf), the name of the view (NotesToWindows), and then the column names (NotesID and WindowsID). - It is likely that you may experience timeouts by the protocol hander when connecting to the Lotus Notes system. The following KB article describes the hotfix: https://support.microsoft.com/?id=841363
Configuring SharePoint Search
This next session documents the steps I took to configure the search within SharePoint. The steps here are about configuring the content sources and indexes.
- I first setup a dedicated brand new index in the index server for my Lotus Notes content sources. This isn't a requirement, but made it easy for my to flush the index and debug by looking at the gatherer logs. I called this new index "Lotus" which you will see in some of the following screen shots.
- With the index created, it was now time to setup the content source. The following screen shots walk you through that wizard:
Content Source Screen 1: Select your index and choose Lotus Notes as the source type.
Content Source Screen 2: For the name of the server, I went with selecting the ability to type the name in so I could enter a fully qualified name instead of the server's name.
Content Source Screen 3: Select which database you you want to search.
Content Source Screen 4: You can then choose which Notes fields should be treated as the subject and author fields. Since my database was a discussion I selected Subject and From. You must have a title field.
Content Source Screen 5: Lastly just specify the source group. - So you think you are done... well if your database is web enabled you are. Unfortunately if you want the search resuilt items to open in the think Notes client you are not (remember not to test this with the client installed on the Index Server). This is because the Urls that SPS will place in the search results will start with https:// not notes:// which is what you want for the thick client to load. To translate the Urls you will need to create a Server Display Map (Screen Shot).
- You will need to rebuild the index for the server display map to have an affect.
- In my environment I thought that would be it as well. Unfortunately, the link in the search results screen though it had the right text, only had a blank space for the url. Interestingly, the item details page actually had the right text and Url. This was corrected after applying a hotfix. I couldn't find the public KB article for it, but when you contact Premier Support for the hotfix, just cite SR: SRQ050714601269.
References