Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade...

20
Enterprise Knowledge Platform Talent Suite Upgrade Guide

Transcript of Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade...

Page 1: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

Enterprise Knowledge Platform Talent Suite Upgrade Guide

Page 2: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

1

Document Information

Document ID: EN8002 Upgrade Guide Document title: TS 8.0 Upgrade Guide Version: 1.1 Document date: 3 February 2012 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 [email protected] to request the most recent version. Please report any errors or feedback with this document by sending an e-mail to [email protected].

Copyright Information

Copyright 2000-2011 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 [email protected] www.netdimensions.com/support

General Enquiries

+852 2122 4500 +852 2122 4588 [email protected] www.netdimensions.com

Page 3: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

2

About This Guide

In This Document This guide explains how to upgrade the NetDimensions Enterprise Knowledge Platform™ (EKP) learning management system from version 7.3 to 8.0. Earlier versions of EKP (e.g. 4.6, 5.0) must first be upgraded to EKP 6.0, then 6.1, 6.2, 6.3, 7.0, 7.1, 7.2 followed by 7.3 before being upgraded to TS 8.0. Please consult the appropriate version of Upgrade Guides for detailed instructions.

Should You Need Help If you cannot resolve an installation problem using this guide or the online help, or should you have any queries related to an installation, the relevant party or parties to contact are described in your Technical Support Contract. For other queries, or if you are not sure whom to contact, you may contact NetDimensions Ltd. at [email protected]. Please also refer to the support section of the NetDimensions web site at www.netdimensions.com for the latest information regarding various services. Sales enquiries should be directed to [email protected].

Document Errors If you find errors or inconsistencies in this or any other EKP document; or feel that any sections are unclear, please email your comments to [email protected]

Page 4: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

3

Before You Start

Check Your EKP Version Make sure the current version of EKP is 7.3 by doing the following:

1. Login to EKP using an account with administrator role 2. Go to System Administration Manager 3. Choose System Activity Statistics

The LMS version should show something like: Release 7.3.0.1 STANDARD

If you are running an earlier version of EKP (e.g. 6.3 or 7.0) then please contact NetDimensions support ([email protected]) for additional information.

Install JDK 5.0 TS 8.0 requires JDK 5.0 or later. This upgrade kit doesn’t include the JDK 5.0 install and setup, but

you can download it from the Oracle website (http://www.oracle.com/technetwork/java).

Obtain a New EKP License File Typically, EKP license files are version specific. In order to proceed with the upgrade, you need to obtain a new license file for a major upgrade. For example, this is REQUIRED for an upgrade from 5.x to 6.x, from 6.x to 7.x, or from 7.x to 8.x. The important point is that 5.x, 6.x, 7.x license files cannot work with TS 8.x.

Prepare a Maintenance Page When you stop EKP in order to perform the upgrade your users will not be able to connect to EKP, and may get an unexpected and unfriendly error message, unless you have prepared a “System Maintenance” page in advance. The EKP login page is, by default, static HTML, and is served by the web server without the use of the application server or Servlet engine. If you leave the web server running with your usual login page, anyone attempting to log in will receive an “Internal Server Error” when the login “post” fails to reach EKP. If you bring your web server down, then your users will see a “404 Page not found” error, generated by their browser, when they try to access the login page. In order to best serve your users, you may wish to leave the web server running, but temporarily replace your EKP login page (index.html in the default EKP installation) with a “Maintenance in Progress” page, done in static HTML, telling your users that EKP is being upgraded, and when they should expect service to resume.

Page 5: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

4

Inform Your Users about the Upgrade Since many EKP installations, especially those accessible over the Internet, are in use round the clock, you may need to give your users advance notice of the upgrade. In addition, since the upgrade may contain new features (or modifications to existing features) that some of your users may notice (notably those with some administration rights), you may wish to warn them in advance of the upgrade. The best way to do this is to prepare a news article and push it out to all EKP users a week or two in advance, using the EKP News Manager. The article can be set to automatically expire the day of/after the upgrade is to be done. This article can tell users when to expect EKP to be off line for the upgrade, and when to expect it to be available again. It can also summarize new EKP features that certain groups of users will be able to see. You may also want to prepare an “Event Message” to be sent on login to every user within 24 hours of the upgrade to remind them that they should expect EKP to be taken off line at a certain time.

Stop EKP Rename your login page and replace it with your Maintenance page to prevent users from logging in. Verify that nobody else is currently logged in. This can be done by going to the “System Administration” Menu and checking in “User Sessions” for active sessions other than your own. Check the “Last activity” column to see how long the connection has been idle for: since not all users properly log out, there can be many apparently open sessions where, in fact, the user has simply moved on without performing a proper log out. If necessary, use the “Broadcast Messenger” to send all current users an immediate message that they should log out. Stop EKP by shutting down the application server (Servlet engine). For example, if you are using Tomcat as your Servlet engine and it is installed as a service, simply stop the service. Other engines (e.g. JRUN, WebSphere) have their own unique administration procedures for starting/stopping the server.

EKP Web Site Backup It is recommended to backup the web site related files prior to perform the upgrade. The web site files are located at “<TOMCAT_HOME>\webapps\ekp” directory in the standard default installation. This may be different if you have installed EKP in a different application server, or with a different application name. Backing up the EKP file system can be done by copying all the files to a new location on disk, to a tape, or to a CD-ROM. In any event, you may need to copy information from these files during the upgrade, so a backup should be made to some form of on-line media in addition to any off-line or slow media (e.g. tape) copies.

Page 6: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

5

Please note: files should be copied, and not moved, as the upgrade will only replace or add files as required, and user-uploaded files should always remain in their original location. Before performing a pre-upgrade backup EKP should be stopped (i.e. by stopping the application server) to prevent anyone from modifying or adding new files to the EKP repositories after the backup has been done.

Backup the EKP Database It is essential that you backup the EKP database before doing the upgrade. Please refer to your database server’s documentation for detailed instructions for performing a full database backup. Before performing a pre-upgrade database backup EKP should be stopped (i.e. by stopping the application server) to prevent anyone from modifying EKP data after the backup has been done.

Customized Changes If you have changed any of the following, you may need to re-apply the customized changes after the upgrade because they will be overwritten during the upgrade.

Default login page o index.html

Default skins includes the following folders: o \nd\fresco\styles\NetD-xxx o \nd\fresco\styles\tests o \nd\fresco\images

Standard messages in folder “\WEB-INF\classes\com\netdimen\locale” o standard.properties o standard_xx.properties

Web application deployment descriptor file o \WEB-INF\web.xml

Page 7: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

6

Check Your Skins In EKP 4.5 and higher, each HTML page now has additional directives that identify the HTML standards expected to be found in the page. This improves cross-browser compatibility and ensures a more consistent screen treatment throughout the application. However, older skins that have CSS stylesheet elements that were in the gray zone of standards compliance may cause some problems after you upgrade to TS 8.0. In particular, we have found the following elements to cause screen formatting to appear odd, so you will want to go through the CSS files in each skin and verify the following potential weaknesses.

Problem Problematic Syntax Correct Syntax

Margin statements may have pixel widths ignored, causing alignment problems.

margin-left: 100 Margin-left:100px Here, just ensure any “margin” related specification specifies a units of “px” instead of nothing at all.

Font size statement in different elements sometimes specify “pt”, and sometimes specify “px”. When different elements are used together (rollovers, for example), you may encounter “jumping around” on the screen as text dynamically changes size.

Font-size:9pt Font-size:9px It is recommended that you use “px” whenever there is a choice to be made, as it always works.

Page 8: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

7

Upgrade Procedures

The upgrade kit has included an upgrade program that will do the upgrade automatically. This is suitable for typical standard installation. Follow the following steps to perform the upgrade. Alternatively, you may perform the upgrade manually by following the steps listed in the “Manual upgrade” section.

Upgrade Steps for Windows

1. Stop EKP.

2. Backup the web site files.

3. Backup the EKP database.

4. Copy the TS 8.0 upgrade kit “Upgrades\TS80_Upgrade_Kit_build_XX” folder from the CD-ROM (or download the package from the support site) to your local hard drive.

5. Edit the “TS80_Upgrade_Kit_build_XX\build.xml” file. Change the db.username and

db.password properties for the account that will be used to execute database scripts during the upgrade process. This would usually be the default.user and default.password in your ekp.properties. Thus, the following lines should be changed:

<property name="db.username" value="admin" />

<property name="db.password" value="password" />

6. The upgrade kit will use the TOMCAT_HOME environment variable to determine the location of your EKP web application directory, so TOMCAT_HOME should be set properly on your system.

7. When using Tomcat 4.1 with JDK 5, you need to remove the following libraries from the “<Tomcat_Home>\common\endorsed” folder: - xercesImpl.jar - xmlParserAPIs.jar as these versions conflict with JDK 5 supplied files.

8. The upgrade kit will also use the JAVA_HOME environment variable to execute the upgrade scripts, so JAVA_HOME should be set to the appropriate directory as well.

9. Change to the folder “TS80_Upgrade_Kit_build_XX” and execute “upgrade.bat”.

Check the file “error.log,” if there is any error occurred during the upgrade. Also see the

“Database Upgrade Notes section”.

Please contact NetDimensions technical support [email protected] for further

assistance.

10. Restore customized changes such as login page, message bundles, etc.

Page 9: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

8

11. Copy new license file to “WEB-INF/conf” folder. (if applicable)

12. Start EKP.

Upgrade Steps for UNIX

1. Stop EKP.

2. Backup the web site files.

3. Backup the EKP database.

4. Copy the TS 8.0 upgrade kit “Upgrades\TS80_Upgrade_Kit_build_XX” folder from the CD-ROM (or download the package from the support site) to your local hard drive.

5. Edit the “TS80_Upgrade_Kit_build_XX\build.xml” file. Change the db.username and db.password properties for the account that will be used to execute database scripts during the upgrade process. This would usually be the default.user and default.password in your ekp.properties. Thus, the following lines should be changed:

<property name="db.username" value="admin" />

<property name="db.password" value="password" />

6. The upgrade kit will use the TOMCAT_HOME environment variable to determine the location of your EKP web application directory, so TOMCAT_HOME should be set properly on your system.

7. The upgrade kit will also use the JAVA_HOME environment variable to execute the upgrade scripts, so JAVA_HOME should be set to the appropriate directory as well.

8. Grant execution permission to “ant” and “upgrade.sh” by executing the following

commands:

chmod +x ant

chmod +x upgrade.sh

9. Change to folder “TS80_Upgrade_Kit_build_XX” and execute “upgrade.sh”. Check the file “error.log,” if there is any error occurred during the upgrade. Also see the

“Database Upgrade Notes section”.

Please contact NetDimensions technical support [email protected] for further

assistance.

10. Restore customized changes such as login page, message bundles, etc.

11. Copy new license file to “WEB-INF/conf” folder. (if applicable)

Page 10: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

9

12. Start EKP.

Manual Upgrade

In some cases, you may want to perform the upgrade manually. The following described the necessary steps in order to upgrade EKP manually.

Steps to Upgrade Manually

1. Stop EKP.

2. Backup the web site files.

3. Backup the EKP database.

4. Copy the TS 8.0 upgrade kit “Upgrades\TS80_Upgrade_Kit_build_XX” folder from the CD-ROM (or download the package from the support site) to your local hard drive

5. Replace the obsolete libraries from “<tomcat_home>/webapps/ekp/WEB-INF/lib” folder by

using the new 8.0 lib folder. If you have any custom files/jars that have been added to the standard distribution, manually copy these from your 7.3 directory to the new 8.0 set.

6. When using Tomcat 4.1 with JDK 5, you need to remove the following libraries from the “<Tomcat_Home>\common\endorsed” folder: - xercesImpl.jar - xmlParserAPIs.jar as these versions conflict with JDK 5 supplied files.

7. Unzip the “ekp-upgrade.zip” to the EKP web application directory (Default:

<tomcat_home>/webapps/ekp).

8. Copy the new “ekp.jar” to “<tomcat_home>/webapps/ekp/WEB-INF/lib” folder and overwrite the existing file.

9. Upgrade the EKP database (See the notes in the following section). Start a command prompt and change directory to <tomcat_home>/webapps/ekp/nschema/<database>, run the following: <database> is Oracle:

sqlplus ndadmin/ndadmin@<server> @upgrade.sql

<database> is MS-SQL:

osql –Undadmin –Pndadmin –S<server> -d<database name> < upgrade.sql

Page 11: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

10

<database> is MySQL:

mysql –user=ndadmin –password=ndadmin <database name> < upgrade.sql

10. Add new properties to <tomcat_home>/webapps/ekp/WEB-INF/conf/ekp.properties. Append “add-ekp.properties” to “ekp.properties’

11. Restore customized changes such as login page, message bundles, etc.

12. Copy new license file to “WEB-INF/conf” folder. (if applicable)

13. Start EKP.

Database Upgrade

1. For SQL Server, make sure the login defined in “ekp.properties” is assigned as dbo in the EKP database. For example, if the following properties are defined in “ekp.properties”:

default.user=ndadmin

default.password=ndadmin

default.driverName=com.microsoft.jdbc.sqlserver.SQLServerDriver

default.connectURL=jdbc:microsoft:sqlserver://localhost:1433;DatabaseName=ekp;SelectMethod=cursor

Execute the following SQL to add the alias:

use ekp

go

sp_dropuser ndadmin

go

sp_addalias ndadmin,dbo

go

2. The execution of the database upgrade script may take a while to complete depending on the size of the data in the database. Beware it may take several hours to run the script if your database is huge.

Multiple Instances Configuration If EKP is not configured to run on default web context ‘ekp’, you need to change the new property “system.domain” in the “ekp.properties”. In previous version, it is defined in the “<tomcat_home>/webapps/ekp/WEB-INF/web.xml”. For example,

<servlet>

<servlet-name>ekp</servlet-name>

Page 12: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

11

<servlet-class>com.netdimen.txserver.TransactionServlet</servlet-class>

<init-param>

<param-name>domain</param-name>

<param-value>ekp2</param-value>

</init-param>

<init-param>

<param-name>baseURL</param-name>

<param-value>/ekp/servlet/ekp</param-value>

</init-param>

</servlet>

Change the “system.domain” property as follows in the “<tomcat_home>/webapps/ekp/WEB-INF/conf/ekp.properties”:

system.domain=ekp2

Page 13: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

12

Languages Note

Restore Changes to Customized Language Bundles If you have modified any of the language files in the “WEB-INF\classes\com\netdimen\locale” directory, or added modified “US English” languages files to that directory you may need to restore your customized language files from your backup.

Since each new version of EKP will add new messages, change existing messages, and remove obsolete messages, it is best to carefully review your customized language files against the new messages before upgrading. HINT: When modifying EKP language bundles you should always group all your modifications together near the top (or bottom) of the file to make restoring them after upgrades a simpler task, and these changes placed in the “custom_xx.properties” file (not the “standard_xx.properties” file)

Upgraded language bundles (non US English) Since it takes approximately one month to bring all the language bundles up to date, when a new release of EKP is initially shipped not all the language files have been updated. If you are running EKP in a language other than US English, and are still seeing some messages coming up in US English, they are probably new messages that are new or modified and are now being localized. EKP Localization bundles are available for download from the NetDimensions support website (see www.netdimensions.com) for clients with valid Support & Maintenance contracts, and the upgraded language bundles will be posted here as soon as they are available. For EKP Silver clients (who receive direct support from their EKP reseller), please contact your reseller for language bundle upgrades.

Important Note It is not advisable to simply copy your customized files over the standard EKP message files, as

you will lose new messages (and/or changes to existing messages) in the new files.

Page 14: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

13

Appendix A – Special Upgrade Instructions Configuring Tomcat 4.1 with JDK 5.0

1. Run command “regedit” in command prompt and open Registry Editor

2. Go to Parameters folder in Apache Tomcat 4.1

3) Edit parameter “JVM Library” and change the value to path of JDK 5.0. (The default path of

JDK 5.0 is “C:\Program Files\Java\jdk1.5.0_09\jre\bin\server\jvm.dll”)

4. When using Tomcat 4.1 with JDK 5, you need to remove the following libraries from the

“<Tomcat_Home>\common\endorsed” folder:

- xercesImpl.jar

- xmlParserAPIs.jar

as these versions conflict with JDK 5 supplied files.

Page 15: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

14

Appendix B - Special Upgrade Instructions for

Windows Single Sign On (SSO)

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 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.

Page 16: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

15

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.

Page 17: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

16

Figure 1: Authentication Methods

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 %WIND WINDIR%\Microsoft.Net\Framework\v2.0.50807

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” />

Page 18: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

17

</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.

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.50807

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...YEHzqk8kLInCH16mFAAAAAGDGIEk4309d</Cipher

Page 19: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

18

Value>

</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.

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

Page 20: Enterprise Knowledge Platform Talent Suite · Enterprise Knowledge Platform Talent Suite Upgrade Guide . TS 8.0 Upgrade Guide Feb 2012 1 Document Information Document ID: EN8002 Upgrade

TS 8.0 Upgrade Guide Feb 2012

19

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.