ShowTable of Contents Terminology
- IBM Lotus Quickr
- http://www-01.ibm.com/software/lotus/products/quickr/
- IBM Lotus Quickr connectors
- http://www-01.ibm.com/software/lotus/products/quickr/connectors.html
- Authentication Extension Mechanism
- A newly introduced software programmability mechanism since 8.1.1 release of IBM Lotus Quickr connectors, which is used for authentication process customization from IBM internal or external parties
- Authentication Extension Framework
- An implementation of the authentication extension mechanism from within IBM Lotus Quickr connector.
- Authentication Extension
The typical contribution unit in authentication extension mechanism, which usually represents a specific authentication process customization.
- Sign-on Token
The authentication identification defined in the authentication extension mechanism.
Java Connectors (Notes and Sametime)
1. Design Assumption
- The authentication extension framework for Java side is designed to be able to be leveraged by Lotus Quickr connectors which are built based on Eclipse, including connectors for Lotus Notes, Lotus Sametime.
- The authentication extension framework is built in terms of Eclipse technologies, including plug-in, extension point, extension, etc.
2. Component Design
- Authentication extension framework is provided as a plug-in, com.ibm.documents.connector.auth, which exposes an extension point, com.ibm.documents.connector.authentication, for dynamical integration of authentication extensions.
- Authentication extensions are implemented in terms of plug-ins, such as com.ibm.documents.connector.auth.sam/tam, which are acting as extensions of the above extension point.
3. Extension Point Design
<element name="authentication">
<complexType>
<attribute name="id" type="string" use="required">
</attribute>
<attribute name="class" type="string" use="required">
<annotation>
<appInfo>
<meta.attribute kind="java" basedOn="com.ibm.documents.connector.auth.api.IAuthenticationModule"/>
</appInfo>
</annotation>
</attribute>
</complexType>
</element>
- Every extension extends this extension point is required to provide a unique id, which will be used to uniquely identify an authentication extension by the authentication extension framework.
- Besides that, each extension is required to implement com.ibm.documents.connector.auth.api.IAuthenticationModule, which is a Java interface specified in the extension point definition.
4. Class and Interface Design
- IAuthenticationModule
An abstraction of the authentication extension, which is defined as a Java interface.
The login interface provide an entry for the module to authenticate against the specified server URL with the user id and password, the process of which results with a valid or null ISignonToken for consequent server requests depends on the returned boolean value of the login interface.
- ISignonToken
An abstraction of the sign-on token, which is the security token to be used by authentication extension framework to authenticate and identify the current sign on user.
Extending from javax.security.auth.Refreshable/Destroyable makes API clients to be able to easily control the lifecycle of the sign on token.
- AuthenticationModuleManager
A singleton manager class, who is in charge of managing all the contributed authentication extensions by providing operations to register, un-register and query extension modules.
5. Step by Step Implementation
- Development Environment Requirements
- Eclipse 3.0 or later versions.
- http://www.eclipse.org/downloads
- Lotus Expeditor Toolkit 6.1.2
- Lotus Sametime 7.5.1 or Lotus Notes 8.0 or later versions.
- Lotus Quickr connector 8.1.1
- Follow the specific developer guide for Sametime or Notes to setup the development environment.
- Verify the development environment by choosing Eclipse menu “Window->Preferences->Plug-in Development->Target Platform” to ensure that the plug-in named com.ibm.documents.connector.auth is in the list of “Plug-ins” tab.
- Initiate a Plug-in Project for Authentication Module
- Launch the “New Project” wizard.
- Choose the “Plug-in Project” creation template to create the project.
- Double click the MANIFEST.MF file to edit the “Dependencies” tab and ensure the com.ibm.documents.connector.auth is in the list of required plug-ins.
- Extend from Extension Point
- Navigate to the “Extensions” tab of the manifest editor to add an extension.
- Choose the extension point of com.ibm.documents.connector.authentication and “Finish”.
- An extension id and a Java class are required to complete the extension contribution.
- The specified Java class in the extension must implement the Java interface com.ibm.documents.connector.auth.api.IAuthenticationModule.
- Alternatively, com.ibm.documents.connector.auth.api.BaseAuthenticationModule can be extended directly.
- Both IAuthenticationModule and BaseAuthenticationModule are defined or implemented in the plug-in of com.ibm.documents.connector.auth.
An Example:
<plugin>
<extension
id="com.ibm.documents.connector.auth.sam.authentication"
point="com.ibm.documents.connector.authentication">
<authentication
class="com.ibm.documents.connector.auth.sam.module.SAMAuthModule"
id="com.ibm.documents.connector.auth.sam.authentication">
</authentication>
</extension>
</plugin>
- Implement Customized Authentication Process
- Provide implementation of com.ibm.documents.connector.auth.api.IAuthenticationModule to implement customized authentication process.
- public boolean login(String serverUrl, String userId, String password);
- Provide customized authentication process implementation.
- Result with a valid com.ibm.documents.connector.auth.api.ISignonToken instance if login success or null if login failed.
- The serverUrl is the Quickr server url, the userId/password are the credential data for a valid sign on token.
- public ISignonToken getSsoTokens();
- A valid com.ibm.documents.connector.auth.api.ISignonToken instance can be queried by invoking this interface if login successfully. Otherwise, it should return null.
- public boolean isDefault();
- True or false indicates the authentication extension framework that it is the default authentication extension or not.
- Authentication extension framework decides the only one default extension if multiple extensions with true returned from this interface.
- A valid ISignonToken instance should be ready for querying after success login the server.
- An implementation of ISignonToken must be provided by extension contributors for carrying the sign-on token data back to the API callers.
- The Refreshable and Destroyable interfaces inherited from its parent should provide implementation to refresh and destroy the sign-on token on demands of API callers.
- public String[] getCookies();
- The cookie strings composed in the way of “name=value”, without the double quotation marks, should be returned through the string array. For example, {“cookie_name=cookie_value“, “cookie_name=cookie_value”}.
- public String getUserId();
- The user id should be returned, in case it was changed over the customized authentication process.
- Get Implementation Source Codes for Reference
- Source Codes Zip
- SAMAuthExtension.zip\Java
- Image Logo
- SAMAuthExtension.zip\Java\com.ibm.documents.connector.auth.sam\icons\logo_dupont.jpg
- Resource Files
- SAMAuthExtension.zip\Java\com.ibm.documents.connector.auth.sam\icons\UIMessages_xx.properties
MS Windows Native Connectors (MS Explorer, Office, Outlook)
1. Design Assumption
- The authentication extension framework for Native side is designed to be able to be leveraged by Lotus Quickr connectors which are built on C++, including DI and connectors for MS Office.
- The authentication extension framework for Native side is built in terms of Component Object Model (COM) Technologies.
- COM should be registered during installation process, and the class ID (CLSID) should be added to an specific location in registry, so that Lotus Quickr connectors could load the COM correctly:
- HKEY_LOCAL_MACHINE\SOFTWARE\IBM\Lotus Quickr\Desktop Integration\Servers\AuthExt
2. Component Design
- TZT.dll is designed as a COM, which will be registered during the installation process.
- logo.jpg is the logo picture, which will be loaded dynamically at the top of dialog.
- AuthRes.dll is the resource file for English, which contains all static strings and dialog layout, it will be loaded dynamically based on the locale setting of client machine.
- AuthResXX.dll is the resource files for other languages, it will be loaded dynamically based on the locale setting of client machine.
3. Extension Point Design
- One interface will be exposed to DI, and totally 4 methods could be used:
-InitializeExt (BSTR locale, DWORD flags)
-GetName (BSTR* text)
-GetDescription (BSTR* text)
-Authorize (HWND parentCtl, BSTR szURL, BSTR szUserid, BSTR szPwd, DWORD flags, DWORD httpCode, BSTR* cookies, BSTR* userIdRtn )
- Each extension should include 2 header files offered by DI, one is CLBCOM.h, which defines the interface, the other one is Guids.h, which defines the ID of interface (IID).
- Each extension is required to implement the 4 methods defined in CLBCOM.h
4. Class and Interface Design
- IQHttpAuthorizationExt – Interface, defined by DI, each extension should implement it.
- CTZTAuthenticator – Main class, which implements IQHttpAuthorizationExt interface and those 4 methods, it will use CAuthTransport and CAuthLoginDlg.
- CAuthTransport - Class, which is used for HTTP requests transport.
- CAuthLoginDlg – Class, which inherits from CDialog class, and is used for dialog layout.
5. Step by Step Implementation
- Development Environment Requirements
- Microsoft Visual Studio 2005
- Lotus Quickr connector 8.1.1 or above
- 2 header files offered by DI (CLBCOM.h and Guids.h)
- Step I - Create an empty COM from .NET wizard
- Open VS.NET 2005 and select File -> New -> Project
- Select Visual C++ -> ATL -> ATL Project
- Need to choose “DLL” as server type and “Support MFC” as additional options in ATL Project Wizard
- Step II - Extend from Extension Point
- Close VS.NET and copy CLBCOM.h and Guids.h to the directory where the project resides.
- Open the project and select Project -> Add Class.
- Select Visual C++ -> ATL -> ATL Simple Object.
- Finish the wizard.
- In TZTAuthenticator.h, make following changes:
-Include two header files
#include "CLBCOM.h"
#include "Guids.h"
-CTZTAuthenticator should implement IQHttpAuthorizationExt, which defines in "CLBCOM.h”.
-Change the interface to the one defined in "CLBCOM.h”.
BEGIN_COM_MAP(CTZTAuthenticator)
COM_INTERFACE_ENTRY(IQHttpAuthorizationExt)
END_COM_MAP()
-Define 4 methods
STDMETHODIMP Authorize(…);
STDMETHODIMP InitializeExt(…);
STDMETHODIMP GetName(…);
STDMETHODIMP GetDescription(…);
- Step III - Implement Customized Authentication Process
- Provide implementation of those 4 methods in TZTAuthenticator.cpp
-Authorize(HWND hwnd, BSTR szURL, BSTR szUserid, BSTR szPwd, DWORD flags, DWORD httpCode, BSTR* cookies, BSTR* retUserid)
hwnd - The handle of the parent UI control.
szURL - The url that has been redirected.
szUserid - The credential login id.
szPwd - The credential login password.
flags - Reserved
httpCode - The error code of the first trying to connect the server. It should be 302 in DuPon senario.
cookies - The output cookies, which is the result of this authentication process.
userIdRtn - The output user id, which may be changed during the authentication process.
->Authorize is the primary function of authentication process, the logic should be implemented here, including call HTTP requests, analyze HTTP responses, prompt login dialog, and return correct cookie value
-GetName(BSTR* text)
text - The name of the authentication module.
-GetDescription(BSTR* text)
text - The description of the authentication module
-InitializeExt(BSTR locale, DWORD* flags)
locale - indicates which locale will be applied, extension should load resource based on it.
flags - reserved.
->InitializeExt should be called first for initialization.
- Step IV - Get Implementation Source Codes for Reference
- Source Codes Zip
- SAMAuthExtension.zip\Native
- Tip: The demo project is built on ATL 2.1, if you are using ATL 3.0, maybe you will get an error message when building the project (no GUID has been associated with this object…). The solution is: open project property dialog, and select C/C++ -> Preprocessor, add “_ATL_NO_UUIDOF” to Preprocessor Definitions column.
- Image Logo
- SAMAuthExtension.zip\Native\Dupont302\Image\logo.jpg
- Resource Files
- SAMAuthExtension.zip\Native\Dupont302\Resources\nls\resources_xx.rc
|
|
|
|
| Version 74 |
November 16, 2010 |
2:51:58 PM |
by James A Riel  |
|
|