WIXLIB

Configuring Netegrity SiteMinderFigure 1-7 Agent Properties Dialog Box5. In the Name field, enter the name of the new Agent. This name is case-insensitive, andmust be 7-bit ASCII characters, in the range 32-127.6. In the Description field, enter a short description of the Agent. This is optional.7. Select the Support 4.x agents check box. A further set of controls specific to 4.x Agenttypes appears in the lower part of the dialog box.8. In the Agent Type group box, select the SiteMinder option button, and from thedrop-down list, select Web Agent.9. In the IP Address or Host Name field, enter the IP address or the host name where K2is installed.10.In the Shared Secret field, enter an alphanumeric shared secret that the K2 Agent usesto decrypt data sent by the Policy Server. The secret must be between 1 and 255characters in length and contain no embedded spaces.11.In the Confirm Secret field, re-enter the shared secret.12.Click OK to save the changes and return to the SiteMinder Administration window.Your new Agent is added to the Agent List.Netegrity SiteMinder Integration Technical Note11

Configuring Netegrity SiteMinderAdding the K2 Agent to an Agent GroupThe new K2 Agent must now be added to an Agent group, and the Agent group must beassigned to the realm that K2 will index. An Agent group is a collection of Agents of thesame type grouped together for common resource protection. By adding the K2 Agent tothe Agent group, the K2 Agent adopts the global policy of the group.To add the K2 Agent to an Agent group, follow these steps:1. Click the System tab in the SiteMinder Administration window. If you do not seeAgent Groups listed in the System Configuration pane, click the View menu, andselect Agent Groups.2. Click the Agent Groups object in the System Configuration pane.Figure 1-8 Agent Group List3. Double-click the Agent group to which you want to add the K2 Agent. The AgentGroup Properties dialog box opens.12Netegrity SiteMinder Integration Technical Note

Configuring Netegrity SiteMinderFigure 1-9 Agent Group Properties Dialog Box4. Click Add/Remove. The Available Agents and Groups dialog box opens.Figure 1-10 Available Agents and Groups Dialog Box5. Select the K2 Agent from the Available Members list.6. Click the Left Arrow to move the K2 Agent to the Current Members list.Netegrity SiteMinder Integration Technical Note13

Configuring Netegrity SiteMinder7. Click OK. The K2 Agent should be listed in the Group Members group box in theAgent Group Properties dialog box.8. Click OK in the Agent Group Properties dialog box.Now you must ensure the Agent group containing the K2 Agent is assigned to therealm(s) that K2 will index. If a realm’s properties contains an Agent name, replace theAgent name with the Agent group name:1. Click the Domain tab in the SiteMinder Administration window.2. Expand the policy domain, and double-click the realm you want to modify. The RealmProperties dialog box opens.Figure 1-11 Realm Properties Dialog Box3. In the Resource group box, enter the Agent group name in the Agent field, and clickOK.14Netegrity SiteMinder Integration Technical Note

Configuring Netegrity SiteMinderConfiguring the Web Agent Configuration ObjectAny Web Agent protecting a resource that will be indexed or searched by K2 must acceptSMSESSION cookies generated by a Custom Agent (the Verity gateway), and include theSiteMinder user variable in the HTTP header. By default, the user variable is included inthe header, and this setting does not normally need to be changed. Both parameters aredefined in an Agent’s configuration object.To specify these settings, follow these steps:1. Click the System tab in the SiteMinder Administration window.2. Select the Agent Conf Objects object in the System Configuration pane.Figure 1-12 Agent Configuration Object List3. In the Agent Conf Object List, double-click the configuration object for the Agent youwant to modify. The Agent Configuration Objects Properties dialog box opens.Netegrity SiteMinder Integration Technical Note15

Configuring Netegrity SiteMinderFigure 1-13 Agent Configuration Object Properties Dialog Box4. In the Agent Configuration Object Properties dialog box, select the parameteracceptTPCookie. If the value is set to no, click Edit. The Edit Parameter dialog boxopens.Figure 1-14 Edit Parameter Dialog Box5. In the Edit Parameter dialog box, type yes in the Value field, and click OK.6. In the Agent Configuration Object Properties dialog box, select the parameterDisableUserVars.If the value is set to yes, click Edit, type no in the Value field, and click OK. Otherwise,proceed to step 7.7. In the Agent Configuration Object Properties dialog box, click OK.16Netegrity SiteMinder Integration Technical Note

Configuring Netegrity SiteMinderDefining a HEAD Web Agent Rule ActionK2 Spider uses the HTTP HEAD Web Agent rule action to retrieve information about adocument without actually downloading the document. SiteMinder by default does notallow HEAD actions, so it must be defined for any Web Agent monitoring a repositorythat is indexed by K2 Spider. Rule actions are defined in the Agent type and areassociated with a realm’s rules. The default actions are GET, POST, and PUT.To ensure the Web Agent type includes a HEAD action, follow these steps:1. Click the System tab in the SiteMinder Administration window. If you do not seeAgent Types listed in the System Configuration pane, click the View menu, and selectAgent Types.2. Click the Agent Types objects in the System Configuration pane.Figure 1-15 Agent Type List3. From the Agent Type List, double-click the Web Agent type you want to modify. TheAgent Type Properties dialog box opens.Netegrity SiteMinder Integration Technical Note17

Configuring Netegrity SiteMinderFigure 1-16 Agent Type Properties Dialog Box4. If HEAD is not listed under Actions, then click Create, type HEAD, and click OK.5. In the Agent Type Properties dialog box, click OK to save the changes and return to theSiteMinder Administration window.Next, verify that your policy rule contains the updated list of actions:6. In the SiteMinder Administration window, click the Domains tab.18Netegrity SiteMinder Integration Technical Note

Configuring Netegrity SiteMinderFigure 1-17 List of Rules and Realms7. Expand the Domain object and click Realms to show the rules applied to each realm. Arealm is a Netegrity Policy Server object that identifies a group of resources. Realmstypically define a directory or folder and possibly its subdirectories.8. To enable the HEAD action in a rule, double-click the rule. The Rule Properties dialogopens.Netegrity SiteMinder Integration Technical Note19

Configuring Netegrity SiteMinderFigure 1-18 Rule Properties9. Select HEAD in the Web Agent Action list. Click OK.Defining the Authentication SchemeSiteMinder supports a variety of authentication schemes; however, K2 only supportsbasic (user name/password) authentication and HTML forms-based authentication.Authentication schemes are assigned to realms. When a user tries to access a resource in arealm, the authentication scheme of the realm determines the credentials that a user mustsupply in order to access the resource. Any realm that will be accessed by K2 must useone of the supported schemes.To change the authentication scheme of a realm, follow these steps:1. Click the Domains tab in the SiteMinder Administration window.2. Expand the Domain object and double-click the realm you want to modify. The RealmProperties dialog box opens.20Netegrity SiteMinder Integration Technical Note

Configuring Netegrity SiteMinderFigure 1-19 Realm Properties Dialog Box3. From the Authentication Scheme drop-down list, select an authentication scheme thatuses the Basic Template or HTML Form Template authentication scheme type. ClickOK.Netegrity SiteMinder Integration Technical Note21

Integrating the K2 ApplicationIntegrating the K2 ApplicationA typical non-single sign-on K2 application includes a JSP/ASPx page with a form thatgathers user credentials and subsequently calls K2 APIs that login the user. In aSiteMinder single sign-on system, the K2 application must retrieve the SMSESSIONcookie, and the user ID variable from the HTTP headers and pass them to the K2credentials. The single sign-on login process is as follows:1. The SiteMinder Web Agent challenges the user for credentials.2. The SiteMinder Web Agent sends the credentials to the SiteMinder Policy Server.3. The Policy Server returns authorization to the Web Agent.4. The Web Agent creates a SMSESSION cookie on the client’s browser. This cookiecontains SMSESSION which is the session ID for the user’s session, and SM USERwhich is the user’s ID.5. The K2 application retrieves the SMSESSION and SM USER from the Web header andpasses them to the K2 credentials.6. The K2 application passes the credential information to the K2 Ticket Server.7. The Ticket Granting Login module (k2lmtg) issues a ticket and passes the ticket to theK2 application.8. The K2 ticket is kept in memory until the ticket expires.With SiteMinder, the K2 application must retrieve the following user variables from theWeb header, and pass them to the K2 credentials:Table 1SiteMinder User VariablesEnvironmentUser variableSession variableWindows ASPxHTTP SM USERSMSESSIONWindows JSPSM USERSMSESSIONUnix platformsm-userSMSESSIONThe user variable is passed through the USERNAME KEY, and the session variable ispassed either through the EXTENSION KEY or the USER PARAMS key.22Netegrity SiteMinder Integration Technical Note

Integrating the K2 ApplicationEXTENSION KEY and USER PARAMS KeyThe EXTENSION KEY and USER PARAMS key contain extended user data in the form ofname/value pairs enabling pre-authenticated access into the gateway. Withpre-authentication, the gateway does not authenticate the user, but simply validates theSMSESSION cookie. When the SMSESSION cookie is passed through theEXTENSION KEY or USER PARAMS keys pre-authentication mode must be enabled inthe gateway and the K2 Ticket Server. See “Enabling Pre-Authentication in the K2 TicketServer” on page 38 and “Configuring the Gateway” on page 40.You would typically use the EXTENSION KEY to pass user data when the collections youare searching have pre-authentication enabled, are protected by SiteMinder, and accessHTTP repositories only. You would typically use the USER PARAMS key when thecollections you are searching have pre-authentication enabled, are protected bySiteMinder, and access different types of repositories, such as Documentum, Lotus Notes,and HTTP.To set the EXTENSION KEY, define the key name as SMESESSION, and the value ofSMSESSION using the VSearch.setExtensionCredential (String key,String value) method. See the VSearch Javadoc for more information.To set the USER PARAMS key, use theVSearch.addUserParamCredential(userParams) method. See the VSearchJavadoc for more information. The format of the USER PARAMS key is as follows:USER PARAMS HTTP NETG:smsession value where HTTP NETG is the gateway-specific pre-authentication key, andsmsession value is the SMSESSION cookie. Use a tab character (\t) to separatemultiple session cookies.Netegrity SiteMinder Integration Technical Note23

Integrating the K2 ApplicationExample %@ page import "java.net.*" % %@ page import "com.verity.search.*" % String serverSpec "localhost:9948";VSearch vs new VSearch();vs.setServerSpec(serverSpec);//Retrieve the header information passed after authenticating tothe JSP page:String sm user null;String smsession null;String sm user request.getHeader("SM USER");String smsession request.getHeader("smsession value");//Alternatively, you can retrieve the cookie usingrequest.getHeader(“cookie”), and process the cookie until youreach SMSESSION and its value.//Set k2UserName and pass the SMSESSION. The following exampleuses the USER PARAMS key:String userParams null;vs.setK2UserName(sm user);userParams " HTTP NETG:" smsession " lue("user",sm user);ticket vs.k2Login();//Set k2UserName and pass the SMSESSION. The following exampleuses the EXTENSION KEY:String extensionKeyname null;String extensionKeyvalue null;extensionKeyname "SMSESSION";extensionKeyvalue smsession value;vs.setExtensionCredential(extensionKeyname, extensionKeyvalue);vs.setK2UserName(sm user)ticket vs.k2Login();//Put the ticket as the session variable:sess.putValue("ticket", ticket);24Netegrity SiteMinder Integration Technical Note

Integrating the K2 ApplicationYou can also retrieve the header information and set the credentials through the LoginAPIs provided by the remote context. For example: %@ page import "java.util.*" % %@ page import "com.verity.search.*" % %@ page import "java.net.*" % %@ page import "com.verity.rpc.*" % StringStringStringStringStringStringserverSpec "localhost:9948";sm user null;smsession null;extensionKeyname null;extensionKeyvalue null;userParams null;String sm user request.getHeader("SM USER");String smsession request.getHeader("smsession value");RemoteContext ctx new enticationProperties props new AuthenticationProperties();//Set username and pass the SMSESSION. The following example usesthe USER PARAMS key:userParams " HTTP NETG:" smsession " ";props.setUserParam(userParams);Ticket g objTicket ctx.login("sm user",null,props);ticket g objTicket.toString();//Set username and pass the SMSESSION. The following example usesthe EXTENSION KEY:extensionKeyname "SMSESSION";extensionKeyvalue smsession value;props.setExtensionCredential (extensionKeyname,extensionKeyvalue);Ticket g objTicket ctx.login("sm user",null,props);ticket g objTicket.toString();Netegrity SiteMinder Integration Technical Note25

Integrating the K2 ApplicationComponent FrameworkTo set credential information using the Component Framework, follow these steps:1. Before the login component is drawn, set AutoLogin to TRUE through the applicationconfig.xml or the setParam() method in the VComponents API. For ,"true");2. Forward the SM USER and SMSESSION to the login component page and pass theSM USER and SMSESSION to the EXTENSION KEY or USER PARAMS key through thesetParam() method of the VComponents API.The following example passes the credential information through theEXTENSION KEY:java.util.Properties p new put("value","smsession ey",p);The following example passes the credential information through the USER PARAMSkey:java.util.Properties p new java.util.Properties();String userParams " HTTP NETG:" smsession " ial",userParams);3. Draw the Login component. If the login is successful, the component redirects thebrowser to the refer page. If the login fails, the component is drawn with an errormessage.4. The K2 application passes the credential information to the K2 Ticket Server which,using the Ticket Granting Login module (k2lmtg), issues a ticket and passes the ticketto the K2 application. The K2 ticket is kept in memory until the ticket expires.Note26For more information on the Component Framework, see the VerityComponent Framework Developer Guide.Netegrity SiteMinder Integration Technical Note

Integrating the K2 ApplicationExample Using the Component Framework//Set the AutoLogin option to TRUE through either the applicationconfig.xml or the setParam() method of the VComponents API.//To set AutoLogin in the application config.xml: LoginComponent Name "loginBox" Xsl "loginBox.xsl" DefaultReferPage index.jsp /DefaultReferPage AutoLogin true /AutoLogin IgnoreRequestRefer true /IgnoreRequestRefer MaximumRetries 3 /MaximumRetries /LoginComponent //To set AutoLogin using the setParam() method of the VComponentsAPI in the JSP page: %@ page import "com.verity.component.VComponents" % %@ page import "java.util.*" % %@ page import "java.net.*" % % VComponents components VComponents.getInstance(pageContext,"search");% % components.draw("logoffButton")% );components.setParam("loginBox","User","sm user");//Set SMSESSION through either the EXTENSION KEY or theUSERPARAMS key:java.util.Properties p new java.util.Properties();//Set SMSESSION through the EXTENSION KEY:p.put("key","SMSESSION");p.put("value"," smsession ey",p);//Set SMSESSION through the USERPARAMS key:String userParams " HTTP NETG:" smsession " ial",userParams);String loginStr components.draw("loginButton");% Netegrity SiteMinder Integration Technical Note27

Integrating the K2 ApplicationManaging Expired SessionsTo manage an expired session, call the checkK2Ticket method in VSearch to checkwhether the ticket issued by K2 Ticket Server is still valid. If the ticket is not valid, call thek2Login method to re-issue the login request to get a new ticket.If the SMSESSION cookie expires, but the K2 ticket is valid, a search request returns amessage indicating the user is invalid, and requests gateway credentials. To handle thissituation, the JSP/ASPx code should log out the user, re-issue a new login, retrieve a newK2 ticket, and re-send the search request. The new login credentials would contain a newvalid SMSESSION cookie retrieved from the Web headers.Managing Cross-Site Scripting (XSS) DetectionNetegrity SiteMinder has a feature intended to prevent malicious users from submittingCross Site Scripting (XSS) attacks through Web applications. When XSS checking(referred to as CSS checking in SiteMinder) is enabled, the Web Agent will not accept aVerity Query Language (VQL) search containing escaped and unescaped versions ofcharacters that are defined i

Overview of Netegrity SiteMinder Integration Verity developed the SiteMinder/K2 integration in partnership with Netegrity. The joint solution enables K2 to index, search, and view content on a Web server based on SiteMinder's authorization policies. K2 supports integrations with SiteMinder versions 5.5 and 6.0.