T ECHNICAL NOTE Product: Create!archive 6.2.1 Last modified: October 5, 2007 12:03 pm Created by: Development SINGLE SIGN-ON SETUP This Technical Note contains the following sections: Summary Create!archive Web Portal SSO Solution Create!archive Web Portal URL Search Criteria Inside this note: Setting up Single Sign- On. Create!archive 6.2.1 Copyright Bottomline Technologies (de), Inc. 2007. All Rights Reserved, Printed in the United States of America Every effort has been made to ensure the accuracy of this manual. Information in this document is subject to change without notice and does not represent a commitment on the part of Bottomline Technologies. Bottomline Technologies makes no warranties with respect to this documentation and disclaims any implied warranties of merchantability or fitness for particular purpose. All software described in this manual is furnished under a license agreement or nondisclosure agreement, and may only be used in accordance with the terms of this agreement. Create!archive 6.2.1 licensee(s) may reproduce Create!archive 6.2.1 instructional documentation as needed for distribution to users of the licensed Create!archive 6.2.1 software. The licensee(s) agrees not to modify, adapt, translate, or otherwise alter the documentation prior to distribution.
2 TECHNICAL NOTE CA2 Summary 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. This document provides the details on how to set up and manage Create!archive SSO.
TECHNICAL NOTE CA2 3 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. 2 Using Windows Explorer, navigate to the application's install directory. In most cases is should be located at: %Program Files%\CreateForm\CA Web Portal. 3 Next, navigate to: apache-tomcat-5.5.15\webapps\cawebclient\web- INF\config.
4 TECHNICAL NOTE CA2 4 Here you will find the file server.properties. Open the file with Notepad or any other plain-text editor. 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) 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 Perform the following steps to enable NT-User authentication at the application level.
TECHNICAL NOTE CA2 5 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. 6 Restart the Create!archive Web Portal by performing these tasks:
6 TECHNICAL NOTE CA2 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). 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.) From these lists you may import any combination of Users, Groups and OUs and the following rules will apply:
TECHNICAL NOTE CA2 7 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 (&(objectclass=person)(memberof=cn=marketing,cn=users,dc=mycompany,dc=com))
8 TECHNICAL NOTE CA2 The form greatly simplifies this query by filling in several distinct parts to the above query. The base defaults to the domain you specified in the 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 You should also consult with your system administrators whenever possible.
TECHNICAL NOTE CA2 9 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. For example, to refine our above list of Purchase Orders, let's search for a list of POs that have a status of Approved. http://localhost:4880/home/document/ list.do?documenttype=purchase%20order&search=arc_status=approved
10 TECHNICAL NOTE CA2