Single Sign On (SSO) solution for BMC Remedy Action Request System

Transcription

1 Single Sign On (SSO) solution for BMC Remedy Action Request System Installation/Administration Guide Creator: NTT DATA Version: 1.7 Date: Modified Date: Filename: SSOInstallationAdministration.docx

2 Table of contents 1 Introduction Technical Concept NTLM SSO Architecture SSO Flow Diagramm Delivered JAR Files & functionality Configuration Files Delivered Scripts Delivered.def files PreRequisites Installation Deploy MidNTTSSO.jar file (MidTier) Deploy AreaSSO.jar file (Arsystem) Deplopy CirqSSOPluginConfig.jar file (Arsystem) Import SSO Configuration Application Deploying Overview Configuration Create trusted computer account on AD (for NTLM) By script Create Service Prinicpipal Name (SPN for Kerberos) Configure MitTier to use SSO authentication plugin Configure Pluginsvr to use AREA plugin Configure AR Server AR System Administration Generate AREA/MidTier Plugin properties file Configure AREA plugin Main settings Add AD Controller (NTLM) Add KDC (Kerberos) Add LDAP Controller (Alternative Authentication) Deactivate SSO Plugin Load Balancer further Settings Configure Clients/Browsers to use SSO Configure Firefox Logging MidTier Logging AREA Logging Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 1 /28

3 10 MidTier Troubleshooting NullPointerException Javax.servlet.ServletException ClassNotFoundException No authmod set (ERR 1001) ServletException: ClassNotFoundException: jcifs AREA Troubleshooting ARERR [623] Echtheitsbestätigung failed and no log entries ARERR [623] Echtheitsbestätigung failed and log entries exist Log: Netlogon.Netlogon (Netlogon.java:107) Netlogon.Netlogon (Netlogon.java:107) - Logon failure: unknown user name or bad password Upgrading the system Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 2 /28

4 1 Introduction BMC Remedy Action Requet System does not come out with a Single Sign On Solution (SSO) out of the box. Therefore NTT DATA developed a solution for the Web client. The main features are: - Registered Domain user are authentificated automatically against Active Directory domain without login dialog in BMC Remedy Action Request System - Multi domain feature: Users from different domains can be authenticated - NTLMv2 and Kerberos supported - LDAP simple bind as alternative authentication - Configuration over Remedy Forms - No third party software necessary (ClearTrust) - Simple deployment This document describes the SSO solution for BMC Remedy Action Request System from a technical point of view. The technical concept is shown chapter 2. In chapter 3 the pre-requists are listed. Installation and configuration tasks are described in chapter 4-5. Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 3 /28

5 2 Technical Concept 2.1 NTLM SSO Architecture The architecture is shown in the picture below. There are 7 main communication steps involved which are listed in the table in this chapter. Nr. Description 1 Client (Web browser) sends HTTP Get Request 2 SSO MidTier Plugin (Web Server) returns 401 HTTP status code (Unauthorized) 3 Client send NTLM Message 1 (3 way handshake begins) 4 SSO MidTier plugin negotiate message 1, creates a randomized 8 byte server challenge and returns ntlm message type 2. 5 Client creates ntlm message type 3 by using the users password and the server challenge for encryption and sends it to the SSO MidTier plugin, with additional information: Username Domain 6 The SSO MidTier Plugin extract username and domain from ntlm message type 3 and Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 4 /28

6 passes the ntlm token, username and domain to AR Sytsem. AR System decides if AREA plugin or AR System authentication is used (Criteria: blank password and existing AR System user) 7 The SSO AREA plugin establishs a secure rpc connection by using the service account name and service account password (trusted computer AD account) and validates the generated ntlm token. When token is valid, MidTier returns 200 HTTP status code (OK) 2.2 SSO Flow Diagramm How a user will be logged in / not logged in into BMC Remedy Action Request System which ways (authentication flow) is shown in the diagram in this section section. Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 5 /28

7 2.3 Delivered JAR Files & functionality The solution consists of four.jar Files and is compiled for Java 1.6. The functionality for each jar file is listed below. JAR Filename Netlogon.jar or Netlogon2008cr MidNTTSSO.jar AreaSSO.jar SirSSOPluginConfig.jar Functionality Creates NTLM negotiation and handles RPC Netlogon authentication. Netlogon2008cr (Active Directory 2008) Remedy MidTier Plugin implementation. Initiates three way NTLM negotiation handshake and validates SPNEGO Token. Handles Netlogon authentication. Generates CirqSSOConfig.properties file with aruser and encrypted password., see chapter Configuration Files The solution consists of two.properties files: One for MidTier Plugin configuration and the other one for arsystem AREA plugin. Properties Filename CirqSSOConfig.properties (Generated by CirSSOPluginConfig.jar, Chapter 4.8) CirqSSOConfig.properties (Generated by CirSSOPluginConfig.jar, Chapter 4.8) Used by AreaSSO.jar MidNTTSSO.jar 2.5 Delivered Scripts To use NTLM authentication with Active Directory a trusted computer account has to be created on the AD. There are two scripts which can create and modify such an account: Script name Description NewComputerAccount.vbs SetComputerPass.vbs Creates a new trusted computer account. Changes the password of a trusted computer account. For further information see chapter 5.1. Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 6 /28

8 2.6 Delivered.def files.def File SSOConfigurationApp.def Description Remedy Application to configure AREA Plugin, see chapter PreRequisites The following chapter describes the prerequisites for NTT DATA SSO Solution. Active Directory (Windows Server 2003 or Windows Server 2008) Trusted Computer Account, see chapter 5.1 User names are administrated in AD as lower case Supported Webserver: Tomcat 5 or 6; Microsoft IIS as redirector MidTier Version >= Tomcat 5 or higher ARSystem Version >= Java Version > = 1.6 (MidTier and AR System Server) Netlogon Service is running on MidTier, AR System and Active Directory Server Atrium SSO is not running AREA LDAP Plugin is not running Firefox and IE supported 4 Installation The following installation steps must be succeeded in the right order (from chapter 4.1 to chapter 4.5). 4.1 Deploy MidNTTSSO.jar file (MidTier) Copy/paste MidNTTSSO.jar file into /midtier/web-inf/lib/ directory Copy/paste Netlogon.jar into /midtier/web-inf/lib/ directory Copy/paste CirSSO.properties file into /midtier/web-inf/classes/ directory (has to be in the same folder as the midtier configuration file conf.properties) 4.2 Deploy AreaSSO.jar file (Arsystem) Copy/paste AreaSSO.jar file into /ARSystem/pluginsvr/ directory Copy/paste Netlogon.jar into /ARSystem/pluginsvr/ directory 4.3 Deplopy CirqSSOPluginConfig.jar file (Arsystem) Copy/pasteCirqSSOPluginConfig.jar file into /ARSystem/pluginsvr/ directory Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 7 /28

9 4.4 Import SSO Configuration Application Open Remedy DeveloperStudio (AR System Version >= 7.5; otherwise use BMC Remedy Adminstrator Tool) and import SSO NTT DATA Application by using SSOConfigurationApp.def file. DeveloperStudio File Import Choose def File Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 8 /28

10 After importing the def file, check if SSO Configuration NTT DATA Application exists. Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 9 /28

11 4.5 Deploying Overview Deploying object MidNTTSSO.jar AreaSSO.jar Netlogon.jar CirqSSOPluginConfig.jar CirqSSOConfig.properties SSOConfigurationApp.def Deploying path /midtier/web-inf/lib/ /ARSystem/pluginsvr/ /ARSystem/pluginsvr/ /midtier/web-inf/lib/ /ARSystem/pluginsvr/ /midtier/web-inf/classes/ /ARSystem/pluginsvr/ Import by DeveloperStudio 5 Configuration 5.1 Create trusted computer account on AD (for NTLM) The computer account is needed to establish a secure RPC connection to AD (Netlogon service). IMPORTANT: Computer accounts with password are not able to connect to the domain. So if you modify an existing computer account by adding a password, nobody can access this computer anymore, because the computer is protected by a password. RECOMMENDED: Create a new computer account, which doesn t exist physicaly. Create trusted computer account on AD by script: Copy NewComputerAccount.vbs script to AD Server and run the script: Example: NewComputerAccount.vbs trustedaccount /p password123 /d MyDomain Check if the created computer exists in Active Directory. Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 10 /28

12 5.2 Create Service Prinicpipal Name (SPN for Kerberos) On the Domain Controller create a new Active Directory user: A) On the domain controller, navigate to Start > Administrative Tools > Active Directory Users and Computers. B) Create a user account with pwassword, ssouser and ensure that the Use Kerberos DES encryption types for this account option is not checked. Set Service Principial Name by using command line (cmd): C) setspn A HTTP/itsm.org.at ssouser@domain Check if spn successfully created: D) setspn L ssouser Create krb5.conf File on MidTier Server: [libdefaults] default_realm = ERMIS.LOCAL default_tkt_enctypes = rc4-hmac default_tgs_enctypes = rc4-hmac Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 11 /28

13 permitted_enctypes = rc4-hmac [realms] ERMIS.LOCAL = { kdc = at-srv srv-ewtest.ermis.local } [domain_realm].ermis.local = ERMIS.LOCAL ermis.local = ERMIS.LOCAL Replace ERMIS.LOCAL with your spn domain. Replace at-srv-ewtest.ermis.local with your kdc domain. Create JAAS.conf File on MidTier Server: SSOTESTING { com.sun.security.auth.module.krb5loginmodule required usekeytab=false storekey=true useticketcache=false principal="ssouser ssouser" debug=true; }; Replace ssouser with the user account name created in step B. 5.3 Configure MitTier to use SSO authentication plugin Edit config.properties file in /midtier/web-inf/classes/ Uncomment the default Authenticator, if exists: #arsystem.authenticator=com.remedy.arsys.session.defaultauthenticator Insert Authenticators.SSOAuthenticator: arsystem.authenticator=authenticators.ssoauthenticator Insert config.file for plugin: Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 12 /28

14 arsystem.authenticator.config.file= CirqSSOConfig.properties 5.4 Configure Pluginsvr to use AREA plugin Add the following lines to pluginsvr_config.xml: <! NTT DATA SSO AREA Plugin --> <plugin> <name>area</name> <type>area</type> <code>java</code> <filename>{path TO PLUGINSVR}/AreaSSO.jar</filename> <classname>areassontlm</classname> <pathelement type="location">{path TO PLUGINSVR}/AreaSSO.jar</pathelement> <pathelement type="location">{path TO PLUGINSVR}/Netlogon.jar</pathelement> <userdefined> <SSOConfigFile>{PATH TO SSOConfig PropertiesFile} /CirqSSOConfig.properties </SSOConfigFile> </userdefined> </plugin> Be sure that only one AREA Plugin is configured. If Atrium SSO is installed, uncomment the plugin definition in pluginsvr_conf.xml. 5.5 Configure AR Server Edit ar.conf file: Uncomment other AREA plugins (arealdap, Atrium SSO,..) #Plugin-Path: "C:\Program Files\BMC Software\ARSystem\arealdap" #Plugin: "C:\Program Files\BMC Software\ARSystem\arealdap\arealdap.dll" Add the following line: Server-Plugin-Alias: AREA AREA {fqdn of server}:{pluginsvr Port} 5.6 AR System Administration Open in remedy: AR System Administration Console General Server Information EA Tab External Authentication Server RPC Program Number: Cross Reference Blank Password: Selected Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 13 /28

15 Authentication Chaining Mode: OFF 5.7 Generate AREA/MidTier Plugin properties file Run CirqSSOPluginConfig.jar which is located in the pluginsvr folder. This small application is used to generate a properties file, which is necessary to establish a connection to authenticationserver. The CirqSSOConfig.properties file has to be deployed on MidTier- and ARServer Server. cmd> java -jar CirqSSOPluginConfig.jar 1) Fill in arserver name which is hosting the SSO Configuration Application (Authentication Server, imported in ) Fill in port of arserver. 3) Fill in a user which is used to access arsystem through remedy api. 4) Fill in user s remedy password (2x). CirqSSOConfig.properties file shoud now exist in /pluginsvr/ folder. Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 14 /28

16 5.8 Configure AREA plugin Open SSO Configuration Form in WebBrowser. SSO Application can be found on Home form or Landing Console form on the left navigation panel. User has to be Administrator on the server Main settings Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 15 /28

17 SSO Mode Use username as Loop ADController Use LDAP as alt. auth. Loop LDAP Servers Choose NTLM or Kerberos Depends on Login Usernames in arsystem If no domain is send in Header- information of the NTLM token, the plugin loops all configured AD Controller, if the field is set to yes. Should LDAP simple bind be used if someone logs in through login.jsp. (Not SSO) Defines if LDAP Servers will be looped if no domain was passed through the Authentication- String field Add AD Controller (NTLM) Domain DomainController NETBIOS-Name ServiceAccountName Not fully qualified domain name ( Example: slw.company.at slw) DNS Name of Domain Controller NetBIOS Name of the Domain Controller The AD Trusted Computer Account created in chapter 5.1 Format: passwd$@fqdn Example: [email protected] ServiceAccountPwd The AD Trusted Computer Password created in chapter 5.1 Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 16 /28

18 Order Status Defines the order of the AD controller. Important when Loop ADController Option is set to true. Status of AD Server Entry Add KDC (Kerberos) KDC LoginModule (JAAS) Service Principal Password JAAS Config Path KRB Config Path Order Status full qualified domain name ( Example: slw.company.at slw) The Login Module defined in JAAS.conf created in chapter 5.2 Service Account passwort created in chapter 5.2 Path to JAAS.conf File created in chapter 5.2 Path to krb5.conf File Created in chapter 5.2 Defines the order of the KDC controllers. Important when Loop KDC Option is set to true. Status of KDC Entry Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 17 /28

19 5.8.4 Add LDAP Controller (Alternative Authentication) LDAP Domain LDAP Host Port Order Status Domain DNS Name of LDAP Server or IP LDAP Port Defines the order of the LDAP controller. Important when Loop LDAP Server is set to true. Defines if LDAP Controller is active 6 Deactivate SSO Plugin (Reverse steps ) a) Edit config.properties file in /midtier/web-inf/classes Comment (#) authenticator and config.file #arsystem.authenticator=authenticators.ssoauthenticator # arsystem.authenticator.config.file= CirqSSOConfig.properties Uncoment default authenticator: arsystem.authenticator=com.remedy.arsys.session.defaultauthenticator b) Edit ar.conf: Comment(#) Plugin Alias #Server-Plugin-Alias: AREA AREA {fqdn of server}:{pluginsvr Port} c) Open in Remedy AR System: AR System Administration Console General Server Information EA Tab External Authentication Server RPC Program Number: (EMPTY) Cross Reference Blank Password: Deselect c) Restart arserver d) Restart midtier Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 18 /28

20 7 Load Balancer further Settings If using Midtier Load Balancer the following options should be set in MidTier config (/midtier/classes/config.properties). arsystem.response.hostip=true This setting prints the Mid-Tier Host IP Address as the ARRESPONSEHOSTIP header in the HTTP Servlet Response arsystem.xmlhttp.get=false BackChannel requests to be done using POST instead of GET 8 Configure Clients/Browsers to use SSO Some browsers have to be configured to deal with NTLM packages. IE normaly support NTLM by default. 8.1 Configure Firefox Open about:config in Firefox Search and set network.automatic-ntlm-auth.trusted-uris Search for network.ntlm.send-lm-response and set it to true Example: Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 19 /28

21 9 Logging 9.1 MidTier Logging The following logs are helpfull for MidTier troubleshooting: /WEB-INF/lib/CirqSSO.log (default path) (path and loglevel are configured in /WEB-INF/classes/CirSSOConfig.properties file) /midtier/logs/armidtier.log Catalina logs in /Apache Software Foundation/Tomcat/logs Jakarta logs (if IIS Jakarta redirect is on) 9.2 AREA Logging Java plugin log /Arserver/Db/arjavaplugin.log Log Level can be modifie in/pluginsvr/ log4j_pluginsvr.xml Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 20 /28

22 10 MidTier Troubleshooting 10.1 NullPointerException Description: The pointer to the MidTier Plugin is not established! The MidTier.jar can t find the plugin. Solution: Check MidTier config.properties file (5.3): (arsystem.authenticator=authenticators.ssoauthenticator) Check if Plugin is in the right path and Tomcat Service has access to it (4.1) Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 21 /28

23 10.2 Javax.servlet.ServletException Description: MidTier Plugin throws an Exception witch is not handled. There are a lot of reasons for such Exceptions. If there is a wrong authenticator properties file configured the MidTier.jar can t initalize the Login Servlet. Solution: Check MidTier config.properties file (5.3) (arsystem.authenticator.config.file= CirqSSOConfig.properties) Check if CirqSSOConfig.properties is in the right path and Tomcat Service has access to it (4.1) 10.3 ClassNotFoundException Description: Mostly this exception occurs when the java version is not compatible with the Plugin version. Solution: Check java Version of System: java version New Plugin deployment necessary contact NTT DATA Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 22 /28

24 10.4 No authmod set (ERR 1001) Description: The plugin tries to initialize the main SSO settings. Therefore it tries to connect by using the credentials from CirqSSOConfig.properties file to arsystem (authentication Server) to get the SSO specific information. If the plugin can t connect to the arsystem because the arsystem is not reachable, the credentials are wrong or the CirqSSOConfig.properties can t be read, error 1001 occures. This often happens when the tomcat service starts before arsystem service is up. Solution: Check if arsystem server is reachable Restart Tomcat service Check CirqSSO.log (Path specified in CirqSSOConfig.properties file) If no specific path is set, the default path is /WEB-INF/lib Check the credentials specified in CirqSSOConfig.properties The following part found in the CirqSSO.log file points to a credential failure: [DEBUG] [] :14:18 in Thread-1 Helper.SSOConfig: reading SSo Config:***** with User: Dem and pwd: ******** [DEBUG] [] :14:18 in Thread-1 Helper.SSOConfig: arserver:slwien4dev [DEBUG] [] :14:18 in Thread-1 Helper.SSOConfig: port:2000 [DEBUG] [] :14:18 in Thread-1 Helper.SSOConfig: Try to connect to arserver: slwien4dev:2000 with User: Dem and pwd: ****** [TRACE] [] :14:18 in Thread-1 Helper.SSOConfig: BEGIN init Config Main [ERROR] [] :14:18 in Thread-1 Helper.SSOConfig: Exception occured during initialization: ERROR (353): Sie haben keinen Zugriff auf die Form.; SSO_Config_Main WARNING (59): Ihre Anmeldung ist fehlgeschlagen, aber Sie wurden als Gastbenutzer angemeldet.; [Ljava.lang.StackTraceElement;@2673ba83 [ERROR] [] :14:18 in Thread-1 Helper.SSOConfig: Exception occured during initialization: ERROR (353): Sie haben keinen Zugriff auf die Form.; SSO_Config_Main Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 23 /28

25 WARNING (59): Ihre Anmeldung ist fehlgeschlagen, aber Sie wurden als Gastbenutzer angemeldet.; [ INFO] [] :14:18 in Thread-1 Helper.SSOConfig: init NtlmMidTierPlugin finished Recreate the CirqSSOConfig.properties file (5.7) Check if SSO Application is deployed on arserver (4.4) Check if SSO Application SSO Mode is set Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 24 /28

26 10.5 ServletException: ClassNotFoundException: jcifs Description: The plugin uses an external jar File for validating the tokens. Exception is shown because the plugin can t find the class NoClassDefFoundException. Reasons could be that the Netlogon.jar or Netlogon2008cr.jar was not deployed or the system has no access to it. Solution: Check MidTier deployment steps (4.1) (Netlogon.jar or Netlogon2008cr.jar has to be in /WEB-INF/lib path Check Permissions of Netlogon.jar or Netlogon2008cr.jar file (needs execute and write permissions) Check the pluginsvr_conf.xml plugin configuration Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 25 /28

27 11 AREA Troubleshooting 11.1 ARERR [623] Authentication failed and no log entries Description: The user can t log in and arjavaplugin.log has no AREA entries. The authentication request doesn t reach the pluginserver. Ether the plugin is not deployed and initializied correctly or the arsystem is not configured for AREA authentication. Solution: Check if plugin alias is set in ar.conf. (5.5) (Server-Plugin-Alias: AREA AREA {fqdn of server}:{pluginsvr Port}) Check if External Authenication Server RPC Program Number is set. (5.6) (External Authentication Server RPC Program Number: ) Check if Cross Reference Blank Password is set (5.6) Check if AREA Plugin is configured in /pluginsvr/pluginsvr_conf.xml Check the paths to the.jar files (5.4) Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 26 /28

28 11.2 ARERR [623] Authentication failed and log entries exist Log: Netlogon.Netlogon (Netlogon.java:107) Description: Netlogon component can t establish a secure channel to Active Directory for NTLM Token validating. Solution: Check the NetBIOS name and DomainController configuration in the SSO Application Netlogon.Netlogon (Netlogon.java:107) - Logon failure: unknown user name or bad password. Description: Netlogon component can t establish a secure channel to Active Directory for NTLM Token validating. The serviceaccount credentials are not valid. Solution: Check the Serviceaccount Credentials configured in the SSO application Recreate the NTLM Trusted Service Account manually or by script. (5.1) Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 27 /28

29 12 Upgrading Action Request System If the system will be upgraded to a new Major Version (Example: ) please contact NTT for a new plugin version. If the Minor version remains (Example: ) only the configurations will be modified. To be on the secure side and to avoid loosing the sso configuration, backup the following files: Arsystem: - ar.conf - pluginsvr_conf.xml MidTier: - /WEB-INF/classes/config.properties After upgrading the system compare the files and add the SSO specific configuration. Step It s not necessary to deploy the SSO jar files again, they should still exist in the right paths. Version: 1.7 / BMC Remedy SSO Installation & Administrator Guide 28 /28