Create!archive 6.2.1 Copyright Bottomline Technologies (de), Inc. 2007.
S
INGLE
S
IGN
-O
N
S
ETUP
This Technical Note contains the following sections:
• Summary
• Create!archive Web Portal SSO Solution
• Create!archive Web Portal URL Search Criteria
Product: C r e a t e ! a r c h i v e 6 . 2 . 1 Last modified: O c t o b e r 5 , 2 0 0 7 1 2 : 0 3 p m Created by: D e v e l o p m e n t
Inside this note:
It is possible to enable users who are listed in the Microsoft Active Directory to log on to the Web Portal without having to reenter their logon credentials. This is known as single sign-on (SSO).
Enabling SSO involves configuring the Create!archive Server to access the Active Directory domain controller, then you can import users from the Active Directory. The Web Portal does not synchronize itself with an Active Directory server, so changes made to the directory are not reflected in the Web Portal until you reimport users.
Create!archive Web Portal SSO
Solution
The Create!archive Web Portal SSO solution satisfies the following requirements:
• It Provides a means to import Active Directory users into the Create!archive user database.
• It Provides a way for an authenticated NT user to login to the Web Portal without having to reenter their credentials.
• It uses existing and proven technologies to accomplish the two previous requirements.
Active Directory Integration Setup
To setup SSO, you will need access to a privileged account that can execute read-only LDAP queries. Since the account's information is stored in a plain text file, we recommend that you create an account with limited access to the network (e.g. guest account).
To set up Active Directory Integration
1 Once the account has been created you will need the following information to proceed:
• Name of the Active Directory server.
• The port that the Active Directory server is running on (by default it is 389).
• The fully qualified domain for the Active Directory server. (e.g. comp01.abc-inc.com)
• (Limited) User account created in the above step.
5 Once opened, you will need to modify the following fields: • Host=[Your Active Directory Host Name]
• Domain=[The domain you will be importing users from (can be a root or an Organizational Unit
• Port=[Almost always 389]
• User=[Name of the User account for executing (read-only) LDAP Queries]
• Password=[Password for the aforementioned account]
• (Optional) domainOverride = [Name of the domain to use when importing users].
Note
This field may not appear in your “server.properties” file. If it does not, use the following text to add it: “domainOverride=<your domain>”.
6 Save and close the file.
7 Restart the Create!archive Web Portal service. Open a command prompt and enter the following commands, hitting the return key after each command. • Net stop “Create!archive Application Server” (please be sure to use the
quotation marks)
• Net start “Create!archive Application Server” (please be sure to use the quotation marks)
Single Sign-On Setup
In order for authenticated NT-Domain users to gain access to the Create!archive Web Server using their domain principals, you must configure the application with the following information:
• Domain Controller
To enable NT-User authenticaton at the application level
1 Using Windows' Explorer, navigate to the application's install directory. In most cases is should be located at: %Program Files%\CreateForm\CA Web Portal
2 Next, navigate to: apache-tomcat-5.5.15\webapps\CAWebClient\WEB-INF 3 With Notepad (or any other plain text editor) open web.xml.
4 Within the file, you should see the following line near the top:
<filter> <filter-name>BTSSOFilter</filter-name> <filter-class>com.bt.cf.ca.authentication.sso.BTSSOFilter</filter-class> <init-param> <param-name>jcifs.http.domainController</param-name> <param-value>BT-PSM-DCS01</param-value> </init-param> </filter> <filter-mapping> <filter-name>BTSSOFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> -->
• Remove the two lines starting with <!-"; next remove "
• Edit the line that contains the value BT-PSM-DCS01; change its value to the domain controller used to authenticate users. Please contact your system administrator for additional help (if needed).
5 Save the file.
• Net start “Create!archive Application Server” (please be sure to use the quotation marks).
At this stage, users are still not able to access the Create!archive Web Portal using their NT credentials-to accomplish this we must import users into the database. Please read on to get an overview of how this is accomplished.
Importing Active Directory Users
This section should only be used as a quick reference guide to Active Directory integration. For details on creating Users, Groups and more please refer to the Create!archive Web Portal User's Guide.
Before continuing the following are assumed to be true:
• You are able to login to the Web Portal using the admin account.
• You are able to perform administrative tasks such as creating / modifying Users and Groups.
• You have already created a group or you are modifying an existing one. To begin importing users from an Active Directory proceed to the Groups/ Users section located under the administration tab. Once there, click Import User List. At this point you will have two options to import a User: select Import Users from an Active Directory option.
Within Import Users From An Active Directory page you will see: • Active Directory integration parameters (e.g. Host, Domain and Port) • Available Users, Groups and Organizational Units (or OUs)
Initially, the lists containing Available Groups and Available Users will be pre-populated with: all Users, Groups and Organizational Units in the specified domain by the value used to set the domain property in the Active Directory Integration Setup.
Note
Organizational Units are listed within the Available Groups and Assigned Groups list boxes.)
• By selecting a Group, all Users in that Group will be imported • By selecting an Organizational Unit, all Users under that unit will be
imported
• By selecting one or more Users, only those Users selected will be imported If the Available Users list is large you may want to run a query to reduce its size and thus make it more manageable. This document does not provide a comprehensive tutorial on writing LDAP queries, however in the process of explaining the interface we will provide some common queries that can be used on most Active Directories.
Importing Rules
When importing Users the following rules are applied:
• New Users duplicated as a result of belonging to a Group or Groups as well as being individually selected in the Available User list will be imported as one User (i.e duplicates are eliminated prior to the import process)
• Importing a User (or an entire group) that has already been imported into the system will update his/her account information
• If a previously imported group is imported again, any User that was originally in the group but removed prior to running the second import WILL NOT be removed from the system. You must remove Users from the group within the Create!archive Web Portal; this can be done in either the Group or the User administration sections.
Running an LDAP Query
From within the Import User From An Active Directory, under the Available Users and Groups section you will find a small form for entering Base and Filter values. These fields represent the lexical values used to construct an LDAP query. For example, let's say we want a list of all the users that belong to the marketing group-that query would look like this:
dc=mycompany,dc=com -s subtree
configuration. It takes the domain name: MyCompany.com and it builds dc=mycompany,dc=com. You may add to the base by specifying values in the Base field, but for now we'll keep it simple. The argument -s subtree indicates that the query should search subtrees, and for the end-users convenience that is always set in the query. The last part of our example query is the filter and that is pre-constructed with the following values: objectClass=Person, CN=Users, and DC=[your domain]. All that leaves for you to fill in to get a list of users that belong to the marketing group is: memberOf=CN=Marketing. It is this value, you'd enter into the Filter field to complete and run the query.
Please remember when entering base and filter criteria you must observe proper LDAP query syntax-which includes comas and parentheses wherever needed. For example, if you wish to query for all users in the Marketing group whose user account names started with 'M', you'd enter the following in the Filter field: (memberOf=CN=Marketing)(sAMAccountName=M*). It is also important to note that whatever is entered into the Filter is logically AND'ed to the pre-constructed filter.
Troubleshooting Your LDAP Queries
To a non-seasoned IT staffer attempting to run a query that does not yield expected results use the following template when attempting to troubleshoot result issues:
{Additional Base Arguments},dc={Your Domain},dc=com -s subtree (&(objectClass=Person)({sub-query})(CN-Users,DC={Your Domain},DC=com
Create!archive Web Portal URL
Search Criteria
Some customers may have existing web applications that they wish to provide links into the Create!archive Web Portal to display the results of a search based on certain criteria. These results could be displayed in another browser, or in an HTML IFrame. Whatever the case may be, the customer should have Single Sign-On as the primary mode of authentication. Otherwise, you will have to login to the application to get to the results from your search.
The list of parameters that can be used to define a search are finite and these rules apply:
• Any archive variable defined in the view definition assigned to that user's group can be used in a search.
• The parameter documentType is always required; all other parameters are optional.
To construct a URL with search criteria, use the following template:
http://[host]:[port]/home/document/list.do?documentType=[Document Type]
Note
That your installation may be using SSL and therefore you would change “http” to “https”.
All fields within brackets should be changed to their proper values. Consider the following example:
http://sales:8080/home/document/list.do?documentType=Purchase Order
In the above example, [host] was replaced with the value sales, [port] was replaced with the value 8080 and [Document Type] was replaced with the value Purchase Order; this search would yield a list of all Purchase Orders a given user is allowed to view.
To refine the search apply the search criteria by appending: &search=[variable1]=[criteria]|[variable2]=[criteria]|… Each variable is specified and delimited by a pipe (i.e. "|"). You may add an infinite number of variables.
