Enterprise Knowledge Platform Single Sign-On Integration with Windows
Document Information Document ID: EN136 Document title: EKP Single Sign-On Integration with Windows Version: 1.3 Document date: 19 January 2010 This document may be revised from time to time. Please check NetDimensions Support site at www.netdimensions.com/support for updates to this and other documents or send an e-mail to support@netdimensions.com to request the most recent version. Please report any errors or feedback with this document by sending an e-mail to support@netdimensions.com. Copyright Information Copyright 2000-2009 by NetDimensions Ltd. All Rights Reserved. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement, and it may be copied only in accordance with the terms of that agreement. No part of this publication may be reproduced, transmitted, or translated in any form or by any means without the prior written permission of NetDimensions Ltd. All company and product names used herein may be trademarks or registered trademarks of their respective companies unless stated otherwise. How to Contact NetDimensions Support +852 2122 4588 1 866 206 6698 US toll-free number +852 2122 4588 support@netdimensions.com www.netdimensions.com/support General Enquiries +852 2122 4500 +852 2122 4588 info@netdimensions.com www.netdimensions.com
Table of Contents Description...1 SSO Integration...2 Integrated Windows Authentication... 2 Limitations... 2 Seamless integration... 2 SSO Login Process... 2 Login Process... 2 Sample Configuration...4 Configure the Microsoft IIS Web Server... 4 Configure EKP to Use Windows SSO... 5 Enabling ASP.NET v2.0... 6 ASP.NET Configuration... 6 Protecting Web.config... 7 EKP Configuration... 8 Troubleshooting...9 Internet Explorer... 9 Firefox... 9
Description About This Guide Single Sign-On (SSO) service enables users to enter user ID and password information once, and to subsequently use other applications without being required to enter this information again. The Enterprise Knowledge Platform (EKP) is able to participate in SSO environments, thus simplifying application use for the users, and minimizing the burden placed upon administrators. SSO functionality is a desirable capability in most corporate environments as it eliminates the need for the user to remember multiple user Ids and passwords for different application systems, and makes it easier for administrators to manage since a central repository maintains basic user ID data. SSO may be implemented using a variety of techniques and may be based upon authentication software services from a variety of suppliers. The interfaces to many of these systems are proprietary. Hence, the solution is unique to the specific SSO vendor environment. The focus in this paper is a description of the configuration requirements for Microsoft Integrated Windows Authentication. The set-up described in the document is applicable to EKP5.7 and later versions. If You Need Help If you cannot resolve a configuration problem using this guide or the online help, or if you should have any queries related to the technology employed within EKP, your first line of contact should be as described in your Technical Support Contract. For other queries, or if you are not sure whom to contact, NetDimensions Ltd. may be contacted at info@netdimensions.com. Please also refer to the support section of the NetDimensions web site at www.netdimensions.com for the latest information regarding various services. 1
SSO Integration Integrated Windows Authentication EKP provides basic SSO capability by leveraging the integrated Windows authentication provided by Microsoft Internet Information Server (IIS). Thus, it imposes some limitations in the SSO implementation. Limitations 1. Integrated Windows authentication is only supported in Microsoft IIS. 2. Only Microsoft Internet Explorer 2.0 or later supports this authentication method. 3. Integrated Windows authentication does not work over HTTP proxy connections and firewalls. 4. This solution is only suitable for intranet and IIS web server environments where the client machines are in the same Windows domain. Seamless integration SSO is tightly integrated with Windows servers and it doesn t require any extra software for implementation. This solution is a good fit for Windows centric organizations. SSO Login Process To enable SSO, there is a special login page ekpsso.aspx used for this purpose. This login page is not visible to the end-user but the administrator should create an entry link to EKP using this page or set this page as the default front page of the site. Login Process 1. From some internal web site, link to the EKP Windows SSO start page (e.g. http://<hostname>/ekp/ekpsso.aspx, assuming the default site context is ekp) 2. The code within ekpsso.aspx is able to determine the Windows user ID of the current user. By making use of settings in the configuration file Web.config, it creates an encrypted 2
authentication token which is passed to EKP. The same encryption key resides in Web.config and in EKP s ekp.properties 3. If EKP can decrypt the information sent from ekpsso.aspx, it can safely assume that the user ID is genuine and login the user. 3
Sample Configuration Configure the Microsoft IIS Web Server 1. Add virtual directory ekp to the web server. Important Note The name must match the application context name. The default ekp will be used throughout this example. Run Computer Management by clicking Start on the Windows desktop, and then selecting Control Panel > Administrative Tools > Computer Management. Select Services and Application and expand Internet Information Services. Select Default Web Site and do a right mouse click and then select New > Virtual Directory. Input ekp as the Virtual Directory Alias. Choose the EKP document root (Default: <tomcat_home>\webapps\ekp) as the Web Site Content Directory. Click Next to accept default for Access Permissions. 2. Set the directory security of ekp. Warning If the Integrated Windows authentication is not set, it is equivalent to disabled security checking. Select ekp virtual directory and set it to use Integrated Windows authentication by doing a right mouse click and then select properties. Choose the Directory Security tab folder and click Edit. Uncheck anonymous access and check the Integrated Windows authentication. Note Make sure the Integrated Windows authentication is checked. 4
Figure 1: Authentication Methods Configure EKP to Use Windows SSO 1. To enable SSO, change the logon page from (default) http://<hostname>/ekp/index.html to http://<hostname>/ekp/ekpsso.asp Note If the application context name is not the default (ekp), the redirect URL in ekpsso.asp has to be changed accordingly. 5
Enabling ASP.NET v2.0 Version 2.0 of the.net framework needs to be installed. Even if it has already been installed previously, it should be done again after the installation of IIS to prevent possible errors. 1. Open up the Command Prompt and enter the following commands: cd %WINDIR%\Microsoft.Net\Framework\v2.0.50727 aspnet_regiis i 2. Now, in the IIS console, right-click on Default Web Site and select Properties. Click on the ASP.NET tab and for the ASP.NET version field, choose version 2.0. ASP.NET Configuration A configuration file called Web.config accompanies ekpsso.aspx and should be updated accordingly, e.g. <configuration> <appsettings> <add key= ekpdefaulturl value= http://<hostname>/ekp/servlet/ekp/pagelayout /> <add key= authenticationkey value= mysecretkey12345 /> <add key= authenticationurl value= http://<hostname>/ekp/servlet/ekp?tx=authenticationtokenverifier /> <add key= authenticationdigestalgorithm value= MD5 /> </appsettings> </configuration> The keys in the configuration file have the following meaning: ekpdefaulturl the page the user will be redirected to after authentication, if the user accesses ekpsso.aspx directly to reach EKP authenticationkey a secret key used for generating the encrypted authentication token. This must match the value of authentication.key within ekp.properties authenticationurl once ekpsso.aspx has generated the encrypted authentication token, the user is sent to this EKP URL for authentication and login authenticationdigestalgorithm used for generating the encrypted teokn. This can take one of two values: MD5 or SHA. Must match the value of authentication.digestalgorithm within ekp.properties. 6
Protecting Web.config As Web.config contains sensitive information, it should not be viewable by the public and IIS, by default, will not serve files with the.config extension. As an added protection, it is standard practice to encrypt sections of the configuration file that contain sensitive data. The.NET framework has a function to carry this out and will automatically decrypt through ASP.NET as and when necessary. To do the encryption, the aspnet_regiis.exe tool should be used. This is located in the Microsoft.NET directory corresponding to the ASP.NET version being used, e.g. cd C:\%WINDIR%\Microsoft.NET\Framework\v2.0.50727 aspnet_regiis.exe pe appsettings app /ekp prov DataProtectionConfigurationProvider The arguments are: -pe: the section of the configuration file to be encrypted -app: the IIS virtual directory which contains Web.config to be encrypted -prov: the name of the encryption provider. The DataProtectionConfigurationProvider uses a machine-based encryption key. Once encrypted, Web.config will look something like: <configuration> <appsettings configprotectionprovider= DataProtectionConfigurationProvider > <EncryptedData> <CipherData> <CipherValue>AQAAANCMnd8BFdERjHoAwE/C1...YEHzqk8kLInCH16mFAAAAAGDGIEk4309 d</ciphervalue> </CipherData> </EncryptedData> </appsettings> </configuration> To undo the encryption: aspnet_regiis.exe pd appsettings app /ekp The upshot of an encrypted Web.config file is that even if the file should end up in the wrong hands, the authentication key will not be accessible. 7
EKP Configuration In ekp.properties, the following configurations must be set, e.g. authentication.key=mysecretkey12345 authentication.service.url=http://<hostname>/ekp/ekpsso.aspx authentication.digestalgorithm=md5 The parameters have the following meaning: authentication.key secret key used to validate the encrypted authentication token. This must match the value of authenticationkey within Web.config authentication.service.url if the user who has not yet logged in attempts to access a secure EKP page which requires a login session, the user is redirected to this URL where an encrypted authentication token would be generated and passed back to EKP authentication.digestalgorithm used for validating the encrypted authentication token. This can take one of two values: MD5 or SHA. This must match the value of authenticationdigestalgorithm within Web.config To enable SSO, change the login page from (default) http://<hostname>/ekp/index.html to http://<hostname>/ekp/ekpsso.aspx 8
Troubleshooting The web browser always brings up an authentication box when accessing ekpsso.aspx. Internet Explorer Internet Explorer will only pass credentials if the website/domain is designated as a Local Intranet Zone, i.e. no.com,.net,.org, etc. This is a security restriction with Windows/IE. Your PC will need to be configured to properly pass across the credentials. Locally on your PC: 1. In IE, click Tools -> Options -> Security 2. Select the zone of Local Intranet 3. Press the Sites button and then Advanced 4. Now add the EKP URL, e.g. http://<hostname> Firefox NTLM authentication must be enabled in Firefox: 1. In Firefox, type about:config in the address bar 2. In the Filter field, type network.automatic-ntlm-auth.trusted.uris 3. Double-click the name of the preference that we just searched for 4. Enter the EKP URL, e.g. http://<hostname>. If there is more than one URL you want to add, the URLs need to be comma-separated. 9