SSO Plug-in v 3 - Java System Solutions · 2018-03-07 · credentials. So the installation process...

SSO Plug-in v 3.1InstallationJ System Solutionshttp://www.javasystemsolutions.com

Version 3.1

Introduction.................................................................................................4

Compatibility...............................................................................................5

Overview of the JSS SSO Plugin...................................................................6

Installation...................................................................................................7

Configuring the AR System......................................................................7

Copy files to your AR System......................................................................................7

Windows............................................................................................................8

UNIX / Linux......................................................................................................8

Using the SSO AREA plugin installer...........................................................................9

Server groups...........................................................................................................19

Load balancers and proxies......................................................................................19

Enable logging for verification..................................................................................19

Configuring the Midtier...........................................................................21

Midtier configuration page........................................................................................22

Logging...........................................................................................................22

Username translation and aliasing..................................................................22

Authentication methods..................................................................................23

Cleartrust / Siteminder.............................................................................................24

Built-in authentication (Internal Windows Authentication)........................................24

Selecting supported protocols.........................................................................24

Creating an AD service account to support Kerberos and NTLM......................25

Configuring NTLM............................................................................................25

Configuring Kerberos......................................................................................26

Manually creating a service account...............................................................27

Manually configuring a Service Principal Name...............................................27

Ports and firewalls...........................................................................................29

Using IIS and built-in authentication................................................................29

External Windows Authentication (using an IIS front end)........................................30

Configuring IIS.................................................................................................30

Configuring Tomcat.........................................................................................31

Large Kerberos tokens....................................................................................31

Configuring the SSO Plugin.............................................................................32

Open ID....................................................................................................................32

SSO for the Windows User Tool..............................................................33

ARSSOInfo.ini Explained...........................................................................................33

General Section...............................................................................................33

ARServer Section............................................................................................34

http://www.javasystemsolutions.com

Recreating a lost ARSSOInfo.ini................................................................................34

Installing SSO on BMC Remedy Knowledge Management.........................36

Automated installation...........................................................................36

JSP patches.............................................................................................36

Manual installation.................................................................................36

Manually logging in to RKM....................................................................37

What to do if you reconfigure the Midtier or SSO Plugin........................37

Enabling RKM logging.............................................................................37

Upgrades...................................................................................................39

If using a version prior to 2.3.................................................................39

If using version 2.3.................................................................................39

If using version 2.4.................................................................................40

If using version 3.0.................................................................................41

If using version 3.1.................................................................................42

Manually configuring the AR System.........................................................43

Import Workflow.....................................................................................43

Updating Repository Details...................................................................43

Check AR External Authentication (AREA) is Enabled............................44

Disable 'Allow Guest Users'....................................................................45

Check the AREA Hub is Installed and Configured...................................45

Windows User Tool SSO – ARSSOInfo.dll................................................47

Check the AREA LDAP Configuration......................................................47

Configure the AREA HUB to Use the JSS SSO Plugin...............................48


Page 4 of 48

Introduction

It’s a fact that no employee will dispute: passwords equal huge headaches - causing user frustration and hindering productivity – not to mention the burden on the IT Service Desk for password resets. Employees, while trying to keep pace with password policy, jot passwords on sticky notes, attach them to monitors or under keyboards – ironically creating significant security vulnerabilities and risk — quite simply, what the password policy was meant to negate.

Fortunately, creating secure and easy user access no longer is at odds with employee productivity and can be effectively managed as part of your security initiatives. Introducing JSS Single Sign On for the AR System.

J System Solutions ensures that you have a product that is easy to install, easy to configure and easy to use. We also pride ourselves on our level of service and support. If you have any questions, issues or queries then please contact us.

Product website or download an evaluation:

http://www.javasystemsolutions.com/jss/ssoplugin

Product fact sheet:

http://www.javasystemsolutions.com/documentation/factsheets/Product%20factsheet%20-%20SSO.pdf

New to Single Sign On?

http://en.wikipedia.org/wiki/Single_sign-on


http://en.wikipedia.org/wiki/Single_sign-on



http://www.javasystemsolutions.com/jss/ssoplugin

Page 5 of 48

Compatibility

The following tables present the supported product versions. If there is a separate product needed that it not displayed, please feel free to contact support.

Operating System

Windows 2000, 2003, 2008

Sun Solaris 5.x HP-UX 11.x Linux 2.4.x+ AIX

BMC Action Request System

7.0 (Patch 001)

7.1 (MT patch 6+) 7.5 (MT patch 1+)

Please note, we only support Tomcat 5.5.23 and above for the Midtier.

The SSO Plugin will support many different URL protection products and methods. Popular products include:

Authentication Systems

Cleartrust SiteMinder Quest QSJ

HTTP Basic

Novell Access Manager

OpenID

The SSO Plugin also provides built-in authentication (Kerberos and NTLM) out of the box.


Page 6 of 48

Overview of the JSS SSO Plugin

The JSS SSO Midtier plugin is invoked by the Midtier when a user goes to /arsys/home, /arsys/forms or /arsys/apps (these paths are configurable).

If the relevant details were available on the incoming request for the JSS SSO Midtier plugin to operate correctly, then these details are passed back to the Midtier, which in turn calls the AR System.

Assuming the AREA plugin does not reject the connection – Midtier will login successfully.

Please ensure you have read the ARS documentation concerning AREA plugins if you were not aware that blank passwords were required for SSO users in the User form.

One of the most common support issues is due to a user not having a blank password in the User form, resulting in the AR System rejecting the request for authentication!


Page 7 of 48

Installation

The installation zip file contains two directories, mt and area-installer. The mt directory contains the files required by the Midtier, and the area-installer directory contains the files required by the AR System. Not all the files may be used for one particular installation method - please follow the instructions carefully.

The installation has two parts: Configuring the AR System and configuring the Midtier. The AR System is configured (and tested) before the Midtier is configured.

Please be aware that some of the directory paths may be different on your installation. If in doubt, consult JSS support.

Configuring the AR System

The AR Server you are installing initially must have the Administrator thread. If you are installing to one AR Server then this is not an issue. If you are installing to an AR Server Group, then please make sure the Server Name you connect to owns that thread at that time. This is needed because the installation imports a BMC Application called SSO Administration and for that the Administrator thread is needed.

The current version of the product needs to communicate back to the AR Server through the AREA Plugin. BMC do not provide this without login credentials. So the installation process will create a new user with administrator permissions called ssoadmin. The password is not a readable word from any language and includes capital letters, numbers and special characters. Thus a fixed license is needed and will need to be free before installing.

The setup program makes use of the BMC ARDBC CONF plugin, which is installed by default on the AR System. If you do not have it installed, the setup program will tell you and to resolve the issue, add the following to your ar.cfg file:

Windows

Plugin: ardbcconf.dll

Solaris/Linux

Plugin: ardbcconf.so

One final prerequisite is that you will need to copy file(s) to the AR Servers. So you will need operating system access.

Copy files to your AR System

Regardless of whether you use our graphical installer or configure the AREA plugin manually, files need to be copied to your AR System server. Depending on your AR Server operating system, you need to copy a directory or just a file.


Page 8 of 48

Windows

Within you downloaded evaluation from the JSS web site, you will find a directory called arplugin.exe.local. This whole directory, including its contents, needs to be copied to the same directory as your arplugin.exe

UNIX / Linux

On UNIX or Linux, you have only one file to copy. This file can be copied in a number of ways. We at JSS recommend FileZilla http://filezilla-project.org/ The relevant operating system file (Linux, Solaris, HP) needs to be copied to the AR Servers bin directory as seen in the following screenshot.


http://filezilla-project.org/download.php?type=client

http://filezilla-project.org/download.php?type=client

Page 9 of 48

Using the SSO AREA plugin installer

This SSO AREA plugin installer will configure the AR system remotely. This means that as long as you have followed Copy files to your AR System, this application will complete the rest of the AR Server configuration.

From your desktop execute setup.exe


Page 10 of 48

Below is a screenshot of the welcome page reminding you to place the correct file(s) on the AR Server. Click Next.

Once you have verified you have placed the files on the AR Server, tick the box and click Next


Page 11 of 48

Fill in your AR Server details, remembering to use a user with administrative permissions. If you are using a server group then make sure you use the AR Server details of which is running the administrator thread.

Click Next.


Page 12 of 48

Make sure you enter all IP addresses of all Midtier servers and any Crystal Reports Server or Business Objects Reporting Servers, including the addresses of any load balancers.

Click Next.


Page 13 of 48

Next are the shared keys. The product verifies the communications from the clients. This installation can create secure keys for you. If you decide to create your own then deselect the check and place you test in the boxes provided.

Click Next


Page 14 of 48

The following screen shows a configuration option for the JSS SSO Plugin for the Windows User Tool. The Microsoft Security API (SSPI) can present the user information in a number of salutations for the user name. E.g. Capitalisation etc. Like many customers, you may have your login names in lower case. The case must match whatever you login name is within the AR System. E.g. Bob is not the same user as bob. So this option allows the Plugin to manipulate the user name before being sent to the AR Server for authentication. The following options are:

• Use format delivered by SSPI

o However the user name is stored in Active Directory, is how it will be sent to the AR Server

• Force lower case (default)

o Modifies the whole user name to lower case

• Force upper case

o Modifies the whole user name to upper case

• Capitalise the first letter

o Changes bob to Bob

Click Next


Page 15 of 48

This screen allows you to install a two month trial license by ticking the check box, or if you have received a site license from JSS then deselect the box and place your code where it says License Key.

Click Next


Page 16 of 48

Now all prerequisites are complete, we are ready to start the installation. A warning is presented to remind the administrator that this may take some time depending on the AR Systems performance. At times the in-stallation may look unresponsive but please be patient. Updates will ap-pear within the white box.

Click Next


Page 17 of 48

After some time you will be prompted to save a file called ARSSOInfo.ini. This has to be the name and can not be changed. At this point, the ini file has been configured with specific information belonging to that instance of the AR System or server group. This file also contains encrypted information. Please save this file and keep safe. This file will be one of two files deployed to the clients desktops who wish to use JSS SSO for the BMC Remedy Window User Tool.


Page 18 of 48

Finally upon seeing this screen, you must now restart your AR System.

Installation of the AREA plugin is complete. Click Exit.

You can now progress to install the Midtier plugin.


Page 19 of 48

Server groups

In previous version of the JSS SSO Plugin, a local configuration file was used to store important operating information. This meant that in server groups, each AR Server had to have its own configuration file and the data inside had to be synched. With version 3.0, the local configuration file is no longer implemented. The information is stored in a form within the AR Server. Here are the installation steps when using a server group/

1. Run the installer against the AR Server with the Administrator thread.

1. This is because the first installation imports a def file to store the configuration information, and thus the admin thread needs to be present.

2. Make sure you follow the same steps as Copy files to your AR System on the remaining AR Servers in the server group

3. Add the following lines to your ar.cfg or ar.conf files on the remaining AR Servers.

1. PluginPath: C:\Program Files (x86)\BMC Software\ARSystem\arplugin.exe.local

2. Plugin: jsssso.dll

3. CrossrefBlankPassword: T

4. ExternalAuthenticationRPCSocket: 390695

5. ExternalAuthenticationReturnDataCapabilities: 31

6. AuthenticationChainingMode: 0

7. AllowGuestUsers: F

4. Restart the AR Servers

Load balancers and proxies

Ensure that the Midtier IP address you enter is the correct address if you're using a load balancer, proxy, etc. If you're unsure then ask your network administrators, and if in doubt, add all the relevant IP addresses!

Enable logging for verification

The JSS AREA plugin can be verified via the AR Systems plugin log file. It is recommended this be enabled now to save time and effort later.

Login via the BMC Remedy User Tool with a user with administrative permissions. Open the AR System Administration Console and click on System and then General.

• Click on the Log Files tab.

• Check the Plug-in Server

• Check the Plug-in Log Level to ALL


Page 20 of 48

• Click Apply and Save.


Page 21 of 48

Configuring the Midtier

There's a movie available to assist with installing the JSS MT Plugin and it can be found at http://www.javasystemsolutions.com/jss/movies

To install the JSS Midtier Plugin, please follow these steps:

1. Copy the contents of the mt directory into the root Midtier directory. i.e. the contents of mt into the Midtier directory that contains the WEB-INF directory.

2. If you are using Midtier 7.0, copy the contents of the mt70 into the root Midtier directory.

3. Restart Midtier.

If you are using IBM Websphere 7, using WAS ensure the com.ibm.ws.jsp.jdkSourceLevel custom property is set to 14 or 15 on the web extension file or the custom WebContainer. This tells Websphere that the application was compiled for Java 1.5+.

4. Go to the Midtier configuration page and check the 'default authentication server' (on the 'general' page) is set to the AR System on which you installed the JSS AREA plugin.

5. Go to the JSS SSO status page by pointing your browser at http://path-to-midtier/arsys/jss-sso/index.jsp. You will be presented with a status page.

Review the Authentication Methods section below to select the SSO implementation.

Click on the Configuration link and review the section(s) below for more details on how to configure this page. If the Midtier is configured correctly then you will be advised to restart it again. Please take note of any errors and/or warnings that are displayed.

6. You can now test the SSO configuration by clicking on the Test SSO link in from the JSS SSO status page. This will attempt to perform an SSO login to the authentication server and report any errors. If the test is successful when you can click on the Midtier Home link in the navigation and you should be taken directly to the Midtier Homepage without being asked to login.

We have identified a possible bug in the AR System which will sometimes prevent our test facility working which will manifest itself in a message stating that the Shared Key or IP Address is not correct. If this is the case, proceed to the next step (going to /arsys/home) before looking further into this report.

7. If SSO fails then review the troubleshooting document or contact JSS support.


http://path-to-Midtier/arsys/jss-sso/index.jsp

http://www.javaystemsolutions.com/jss/movies

Page 22 of 48

Midtier configuration page

Logging

This enables the Midtier SSO logging which writes to the Tomcat stdout file. We recommend you select Information for production use, debugging when configuring the SSO Plugin, and trace when you're trying to resolve an issue. Trace will generate a lot of logging including full NTLM hex dumps and low level Kerberos logging (when using internal Windows Authentication).

Username translation and aliasing

If your SSO usernames do not match the AR System Login Name values in the User form, the plugin provides a range of functionality to ensure they match.

Case conversion

The convert to upper/lower case options will force the entire username (including the Windows domain name) to be converted during the authentication process.

Username conversion happens before any other kind of translation.

Removing the domain name

If using Windows Authentication, the username will be in the format DOMAIN\username or username@domain. This option will remove the domain name, leaving just username.

The 'try both ways' option will tell the SSO Plugin to check the User form for an entry with a login name set to both the domain and username, and if one doesn't exist, an entry with just the username. This is not recommended as it does not allow two users to exist with the same name in different domains.

User aliasing

This tells the SSO Plugin to run a query against the User form to return a Login Name using the username and optionally domain name as part of the query. This feature allows you to map SSO users to AR System Login Names. When writing the query, you can use the $SSO_USER$ and $SSO_DOMAIN$ place holders, which will be replaced by the SSO user and domain name (if applicable).

If you want to pass the value returned from the Windows authentication system (i.e. user@domain or DOMAIN\user) to $SSO_USER$, do not enable Remove domain part.

For example:

1. If the User form holds the SSO usernames in field 117 then you may wish to set the alias query to '117' = “$SSO_USER$”. When this query is executed against the User form, the $SSO_USER$ string is replaced with the username, and the value for the Login Name field is returned. This value is then used to connect to AR System.


Page 23 of 48

2. If you're using Windows authentication, NTLM returns usernames in the format DOMAIN\user and Kerberos returns them in the format user@domain. If you have a policy of storing all SSO accounts in the format user@domain within field 117 on the User form, then enable Remove domain part and use the following query: '117' = “$SSO_USER$@$SSO_DOMAIN”.

Please note: If there is no User form entry returned when using user aliasing, the SSO authentication request is rejected.

User aliasing and Open ID

The user aliasing feature is used for the configuration of Open ID. When using Open ID, the $SSO_DOMAIN$ place holder is used to hold the Open ID Provider, and $SSO_USER$ is used for the Open ID Identifier.

Configuring Open ID is described in more detail in the Open ID section of the document.

Authentication methods

There are a number of ways to integrate the product into your network and they are as follows:

1. Using Microsoft IIS as a front end to Tomcat and delegating Windows Authentication to IIS. This is referred to as External Windows Authentication and is enabled by selecting 'Third-party authentication' with the mechanism set to 'IIS Anonymous+IWA'.

2. Using Internal Windows Authentication, which provides Windows Authentication without an IIS front end, and is enabled by selecting 'Built-in authentication' and configuring the Kerberos and/or NTLM settings.

3. Using a third party authentication system such as Cleartrust, Siteminder or Open ID, which are enabled by selecting 'Third-party authentication' with the appropriate mechanism.

4. Using a JAAS module installed in your web application, which is enabled by setting the mechanism to Standard REMOTE_USER based (this also checks the Java User Principal).

Windows Authentication – implementation choices

If you're intending to implement Windows Authentication – so users can SSO into the Midtier if they are logged into a Windows Domain - then you need to decide whether to implement options 1 or 2. If you've already got IIS installed as a front end to Midtier, the obvious choice is option 1 – please see the 'Configuring IIS and SSO Plugin' movie on our website for an interactive installation guide. If you don't have an IIS front end, configure built-in authentication.

Redirect non-SSO users to login form

The standard BMC SSO specification has no provision for users who are not SSO enabled within the AR System – i.e. if they don't have a correctly set up entry (such as a non-blank password), the user is presented with an ARERR623 page. We don't believe this is desirable, so when this option is


Page 24 of 48

enabled, users who do not have an SSO enabled account in the User form will be redirected to the Midtier login form.

Permit Midtier login form

If a user goes to the standard Midtier login page (/arsys/shared/login.jsp), as non-SSO users will do when 'Redirect non-SSO users to login form' is enabled, Windows Authentication must be configured to allow access for users who manually logged into the Midtier. This option allows users to login manually when Internal Windows Authentication is enabled. Your corporate policy may dictate that all users must be SSO enabled, hence why this is an option – i.e. when disabled, users will not be able to login with the normal Midtier login form.

Cleartrust / Siteminder

Cleartrust and Siteminder have a timeout after which browser requests (to the Midtier) will be directed to the SSO login page. Therefore, the timeout needs to be in sync with the AR System Midtier session timeout or a situation can arise where a user is (still) logged into the Midtier but are not logged into the SSO environment. It is advised that the following points are kept in mind:

• Configure Cleartrust or Siteminder to protect the paths /arsys/home, /arsys/forms and /arsys/apps. These paths are the minimum required and a full set can be found in the web.xml.patch file (within the installation set), where each filter-mapping declaration defines a path to be protected.

• Ensure the Midtier and Cleartrust/Siteminder session timeouts are identical.

Built-in authentication (Internal Windows Authentication)

When you enable built-in authentication, the plugin to apply a patch to the Midtier web.xml file, adding the contents of the web.xml.patch (supplied with the product). If your Midtier can not write to the web.xml file, an error will be reported when the form is submitted. In this case, you will need to apply the patch manually (the instructions are in the web.xml.patch file).

Please note, most servlet engines (such as Tomcat) detect changes to the web.xml file and will restart the Midtier application. If the patch has been applied, you will need to restart Tomcat after submitting the form. Failure to do so will result in some odd errors as the Midtier can not 'survive' a restart without Tomcat being restarted.

Selecting supported protocols

The plugin must be told which protocols to support by selecting the types in the Authentication method box. It is recommend you start by configuring just NTLM as it's the easiest mechanism to configure. You should consider both Kerberos and NTLM in production and, it's unlikely you will be able to allow Kerberos only due to NTLM being a common


Page 25 of 48

protocol on Windows networks, even when administrators have attempted to insist on Kerberos only.

Creating an AD service account to support Kerberos and NTLM

In previous releases of the SSO Plugin, NTLM authentication could be configured with a user based service account. As of version 3.1, we have implemented a higher strength version of NTLM that requires a computer service account. If upgrading from a previous release, you can NOT use your existing NTLM service account!

The setup for Kerberos also involved a manual step on the Active Directory to setup a 'Service Principal Name' (SPN), using the setspn.exe utility.

We have provided a script to create a computer service account and give it a random password. The Microsoft Active Directory Users and Computers utility doesn't provide a way to set a password, so we provide a script to automate this process. The script also sets up the SPN for Kerberos, allowing the same service account to be used for both Kerberos and NTLM. We'd encourage you to setup both types of authentication.

The script is called set-service-account.cmd and is included in the installation files. Copy it to your Active Directory, run it, and you can almost certainly accept the default options. It will create a computer called JSS-SSO-SERVICE – note down the password it generates!

The script also asks you for the hostnames on which the Midtier Tomcat server will be running – please provide both the hostname and the fully qualified hostname (i.e. myserver and myserver.domain.com) to the script.

If you do not wish to run our script then please refer to the section 'manually creating a service account' which is below.

Configuring NTLM

On the SSO Plugin setup page, you will be presented with the following options after enabling 'Permit NTLM':

1. Hostname of Domain Controller: Enter the fully qualified hostname of your Domain Controller, which is probably the hostname of the Active Directory.

2. Domain name: The name of the domain – this is what you can see when you login to your machine.

3. Service user: If you have followed this guide then it's JSS-SSO-SERVICE.

4. Service password: If you the set-service-account.cmd script then you will have noted down the password. If you've forgotten it, run the script again.

There is also an advanced option:

1. IP address of the DC: In the unlikely event that the hostname of the Domain Controller does not resolve to an IP address, enter the IP address.


Page 26 of 48

Submit the setup page, restart the Midtier and go to the Test SSO page. If NTLM fails, you will get some indication of what's wrong – you can also review the Tomcat logs or contact JSS for assistance.

NTLM and multiple domains

If your domains are in a trusted relationship then you only need configure the SSO Plugin to authenticate against one of the domains. The Domain Controller should be able to authenticate users connecting from any other domain where that other domain is trusted. If the domains are in an untrusted relationship then we recommend you configure Kerberos.

Discovering if you're logged into the domain

If you're unsure whether your account is logged into the domain, or you need to find the domain name, run this command at a DOS prompt:

net config workstation

Discovering the IP address of your Domain Controller

If you want to obtain the IP address of your Domain Controller, type the following command:

netdom query /domain:fully.qualified.domain pdc

Passing dc as a parameter will provide a set of domain controllers.

Configuring Kerberos

Kerberos requires two separate elements to the configuration, each of which can be configured in two ways (providing four possible ways to configure the product!):

1. The location of the Kerberos Domain Controller (KDC). This is configured by providing the hostname of the KDC and a Kerberos realm, or by configuring a krb5.conf file.

2. A mechanism of authenticating with the KDC. This is configured by providing service account credentials (as required for NTLM), or a keytab file created using the ktpass program.

We recommend you start with the easiest configuration: a service account, a hostname of the KDC and a Kerberos realm. This configuration is the easiest for end users, and in many cases, no further configuration will be required.

Whatever configuration you choose, you must configure a Service Principal Name (SPN) or the browsers will not send a Kerberos token to the Midtier. The set-service-account.cmd script (described above) will create the SPNs and this can also be performed manually (see below) – we recommend you use the script.

On the SSO Plugin setup page, you will be presented with the following options after enabling 'Permit Kerberos' – we assume you are using the simple configuration discussd above (no krb5.conf file and a service account):


http://technet.microsoft.com/en-us/library/cc753771.aspx

http://www.daemon-systems.org/man/krb5.conf.5.html

Page 27 of 48

1. KDC address: Enter the fully qualified hostname of your Kerberos Domain Controller, which is probably the hostname of the Active Directory.

2. Kerberos realm: This is not the Windows Domain, but usually the fully qualified Windows domain. You can out this value by opening a command prompt and typing:

net config workstation

and looking for the value of Windows Domain DNS Name. If in doubt, contact your network administrator as Kerberos will not work without the correct Kerberos Realm.

3. Service user: If you have followed this guide then it's JSS-SSO-SERVICE.

4. Service password: If you the set-service-account.cmd script then you will have noted down the password. If you've forgotten it, run the script again.

Manually creating a service account

If you don't want to run our set-service-account.cmd script then you will need to configure the Active Directory service account manually. Please follow these steps:

1. Using the Active Directory Users and Computes tool, create a new computer account called JSS-SSO-SERVICE.

2. The AD tool provides no way to set the password on the computer account, and there are no Microsoft command line tools to do it either. Therefore, a small script is required to set the account. Given you don't want to run our comprehensive script, the following one line script will do it for you – please edit the LDAP path appropriately and run from a command prompt:

echo GetObject('LDAP://CN=JSSSSOSERVICE,CN=Computers,DC=testdomain,DC=local').setPassword('newpassword'); > temp.js

cscript //E:jscript temp.jsdel temp.js

3. Create the service principal name (see below).

Manually configuring a Service Principal Name

We recommend you use the set-service-account.cmd script provided to setup the Service Pricinipal Names (SPN).

For the Midtier to be able to authenticate clients using Kerberos, an SPN must be configured on the Domain Controller. The setspn.exe tool is used by the administrators to create an SPN which maps the Midtier host to a service account in the Active Directory.

To find out the fully qualified hostname of the Active Directory, ping it from the command prompt (you will see the hostname and fully qualified hostname).

We assume that:


Page 28 of 48

• The Windows domain is called development,

• The domain's fully qualified name is development.javasystemsolutions.com,

• The Midtier is running on a machine with the hostname midtier.javasystemsolutions.com,

• The service account username is midtier_service_account.

Here is an example of how to use setspn – you must add both the hostname and the fully qualified hostname of the Midtier!

setspn.exe A HTTP/midtier.javasystemsolutions.com development\midtier_service_account

setspn.exe A HTTP/midtier development\midtier_service_account

You can check to see if the SPN has been added by using the -L option, which lists the SPNs for a computer or user account:

setspn.exe L development\midtier_service_account

Please note, a hostname should only ever be declared against one user account – to declare it against multiple users will confuse Active Directory.

Untrusted domains and the krb5.conf file

Users with multiple Windows Domains that are in an untrusted relationship will need to configure a krb5.conf file (an example is provided with the installation). If your Domain Controllers are in a trusted relationship then the KDC for domain A should be able to authenticate users for domain B, and vice versa, so the krb5.conf isn't required unless you require some of the advanced Kerberos configuration options.

Why use a keytab?

Users who do not wish to store service account credentials with the Midtier can use a keytab. This is created with the ktpass program, and plenty of examples are available online, however it is briefly covered below.

Following on from the SPN example above, a keytab can then be created as follows:

ktpass princ HTTP/midtier.javasystemsolutions.com@DEVELOPMENT.JAVASYSTEMSOLUTIONS.COM out midtier_service_account.keytab mapuser service_account pass service_account_password ptype KRB5_NT_PRINCIPAL crypto RC4HMACNT

(Note, the realm – DEVELOPMENT.JAVASYSTEMSOLUTIONS.COM - has to be in upper case.)

Using the above configuration, you would store the keytab in the Midtier (we recommend under WEB-INF) and configure the SSO Plugin by providing:

• The full path to the keytab,

• The service principal, which is HTTP/midtier.javasystemsolutions.com@DEVELOPMENT.JAVASYSTEMSOLUTIONS.COM


mailto:HTTP/midtier.javasystemsolutions.com@development.javasystemsolutions.com

mailto:HTTP/midtier.javasystemsolutions.com@development.javasystemsolutions.com

Page 29 of 48

(You do not have to use such a long SPN name!)

Windows Vista, 7, 2008 and Internet Explorer (AES 256 bit encryption)

Without a patch from Sun, the standard Java Virtual Machine does not support 256bit encryption (due to US export rules) and can not decode AES 256bit tokens. AES 256bit tokens are often generated by IE when using a Windows 2008 Domain Controller and a Windows Vista, 7 or 2008 client.

The SSO Plugin warns users if AES256 is not supported by displaying a message in the JSS Midtier SSO interface, and writes a warning to the log files when the application starts.

To enable AES 256bit support, you need to download and install the Sun "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files", currently available from http://java.sun.com/javase/downloads.

Installing the patch is easy: You unzip two jar files and place them in the JRE lib/security directory.

For your information, the Java Security documentation includes the following explanation:

"The JCE framework within JDK includes an ability to enforce restrictions regarding the cryptographic algorithms and maximum cryptographic strengths available to applications. Such restrictions are specified in "jurisdiction policy files". The jurisdiction policy files bundled in Java SE limits the maximum key length. Hence, in order to use AES256 encryption type, you will need to install the JCE crypto policy with the unlimited version to allow AES with 256-bit key."

Ports and firewalls

Windows SMB protocol makes use of TCP ports 139 and 445, therefore your Midtier must have access to these ports on the Domain Controller. If you’ve got a firewall between the Midtier and Windows Domain Controller, ensure the ports are open.

Using IIS and built-in authentication

If you require an IIS front end then we recommend you do not use built-in authentication and instead use External Windows Authentication.

If you're using a single Tomcat instance, and are not engaging in software load balancing, then you don't need to use an IIS front end with built-in authentication. The BMC Midtier installer will configure IIS if it's present, and while we do not recommend this configuration, it is possible to use Internal Windows Authentication with IIS.

In order to do this, you must ensure IIS is not configured to perform any authentication. This is done by configuring the IIS website authentication to anonymous only:

1. Open the Windows Control Panel.

2. Open Administrative Tools.


http://java.sun.com/javase/downloads

Page 30 of 48

3. Open the IIS management console.

4. Locate Websites → Default website → jakarta, right click and select Properties.

5. Locate the Directory Security tab and click Edit in 'Authentication and Access Control'.

6. Ensure 'Enable anonymous access' is checked, and the 'Authenticated access' check boxes are unchecked. The following dialog box shows the configuration:

External Windows Authentication (using an IIS front end)

There are a number of steps to perform in order to correctly configure External Windows Authentication that involve changes to IIS, Tomcat's server.xml file and the workers.properties file that configures mod_jk, the software that connects IIS to Tomcat. These changes are detailed below.

Configuring IIS

IIS must be configured to perform Windows Authentication. This is done by configuring the IIS website authentication to anonymous only:

1. Open the Windows Control Panel.

2. Open Administrative Tools.

3. Open the IIS management console.


Page 31 of 48

4. Locate Websites → Default website → jakarta, right click and select Properties.

5. Locate the Directory Security tab and click Edit in 'Authentication and Access Control'.

6. Ensure 'Enable Anonymous Authentication' and 'Integrated Windows Authentication' are checked.

Configuring Tomcat

To tell Tomcat that IIS is performing Windows Authentication, locate the Tomcat server.xml file, which will be in the Tomcat conf directory. Locate the ajp/13 connector, which looks like this:

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

and add the following attribute:

tomcatAuthentication=”false”

In this example, it would now look like this:

<Connector port=”8009” tomcatAuthentication=”false” ...

Large Kerberos tokens

IE clients can send very large Kerberos tokens which can be too big to be passed between IIS and Tomcat through the mod_jk connector (this is the software that connects the two systems). This will cause browser issues and often only on some machines (as Kerberos tokens contain group information, so if a user is in many groups, the token is likely to be larger than a user who is not).

To rectify this, two files must be modified:

1. The mod_jk workers.properties. You will need to search for this file as it could be in many locations, but is often found near the Apache Tomcat installation (if the BMC installer has been used). Open the file and add the line:

worker.X.max_packet_size=16000

where X is the name of the worker - you will see many other similar lines from which to copy and edit. The BMC installer sometimes adds this line for you, so if that is the case then set the value to 16000 and ensure you carry out step 2.

2. Locate the Tomcat server.xml file, which will be in the Tomcat conf directory. Locate the ajp/13 'Connector, which looks like this:

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

and add the following attribute:

packetSize=”16000”

In this example, it would now look like this:

<Connector port=”8009” packetSize=”16000” ...


Page 32 of 48

Configuring the SSO PluginSelect third party authentication and the 'IIS Anonymous+IWA' mechanism.

The anonymous access is required for WUT Data Visualisation fields which are displayed in an IE component that can not perform Windows Authentication. Normal Midtier use will require SSO through IIS.

This operation will result in a patch being applied to the Midtier web.xml file (as is the case with built-in authentication). If the web.xml file is patched, a warning message will be displayed when you submit the setup form and you must restart the Midtier!

Open ID

The SSO Plugin can integrate with Open ID Providers such as Google, Yahoo, MyOpenID, ClaimID, etc. Open ID requires two pieces of information – the Open ID provider and identifier. Please see http://en.wikipedia.org/wiki/OpenID for an overview of Open ID.

To configure Open ID, follow these steps:

1. Go to the BMC AR System Developer Studio, open the User form and add two character fields called 'Open ID Provider' (456) and 'Open ID Identifier' (123) – we have included sample field IDs in brackets for the purposes of this guide, you will need to note down the ones assigned by Developer Studio. Arrange the new fields neatly on the User form.

2. Go to the SSO Plugin setup page and select third party authentication and the 'OpenID' mechanism.

3. Enable 'Remove domain part'.

4. Ensure 'Normalise username' is set to 'Leave as-is'.

5. Enable 'Alias username by User form query' and enter the following into 'User matching condition':

'123' = “$SSO_DOMAIN$” AND '456' = “$SSO_USER$”

6. Submit the configuration via the setup button.

7. Restart the Midtier.

Open a new browser, go to the Test SSO page and you will be presented with an Open ID login form. Select your Open ID provider, type in your Open ID and submit the login form. The browser will be redirected to the Open ID provider's login page, and after logging in, the browser will return to the Test SSO page.

If no entry exists in the User form with the correct Open ID Provider and Identifier, they will be provided so you can edit a User entry (don't forget to set a blank password). If you return to the Test SSO page then you should now see the user that has just been activated.


http://en.wikipedia.org/wiki/OpenID

Page 33 of 48

SSO for the Windows User Tool

If you used the installation setup.exe, you would have been prompted to save a file called ARSSOInfo.ini This file along with a dynamic link library, ARSSOInfo.dll must be copied to the clients machine. These files must be copied to the same directory as the aruser.exe

ARSSOInfo.ini Explained

The contents of the ini file dictate how the SSO interface works. Here is an explanation of those settings:

General Section

Enabled: Values are 1 means enabled, 0 means disabled. If the option is 0 then you are prompted with the login screen as normal.

Loginarserver: Values are arserver1, arserver2. This points to the section of AR Server connection information that should be used to login.

Userpreferenceserver: Values are arserver1, arserver2. This points to the section of AR Server connection information that should be used as the preference server.


Page 34 of 48

Debuglogging: If asked by JSS to enable logging, this option should be set to 1.

Ssover: Values are 2 or 3. This version should match whatever SSO version you are running on your AR Server(s).

ARServer Section

Servername: this is the server-name reference in the ar.cfg file. If you are using server groups then this will be the front end load balancer DNS name.

Servertcpport: This should be the TCP port of the arserver

Serverrpcport: If you need your clients to connect to a certain RPC port then place that value here.

Shared-Key: This is the unique encrypted value that is used to ensure security. This should be left as is.

Newsharedkey: If your shared key changes within the AR Server, then you can get the library to encrypt the data and replace the existing shared key. Place the plain text shared key with this value and restart the aruser.exe

Forcemode: Values 0,1,2,3. This changes the format of the user name before it gets submitted for authentication to the AR Server.

0 will send the user name as it is presented in the Active Directory.

1 will force the user name to lower case

2 will force the user name to upper case

3 will capitalise the first letter

Recreating a lost ARSSOInfo.ini

The ARSSOInfo.ini file contains encrypted information and is unique to every AR Server SSO enabled instance. The installation program can recreate those same encrypted keys by logging into an SSO enabled AR System. Use the same installation program, login when asked and you should be shown a different screen following a discovered SSO instance. Select Create ARSSOInfo.ini and Exit, click Next and you should be prompted to save the new file. Please see the screenshot below for an example:


Page 35 of 48


Page 36 of 48

Installing SSO on BMC Remedy Knowledge Management

The SSO Plugin has been extended to provide SSO for Remedy Knowledge Management (RKM). There is no official SSO interface to RKM, so JSS have developed their own 'hook' into the application in order to trap requests to the RKM homepage and pass then through the SSO Plugin.

Automated installation

The SSO Plugin Midtier interface is able to automatically patch RKM and this can be done through the Midtier SSO status page. However, this will only proceed if the plugin can correctly find the RKM installation.

You must also follow the steps in 'JSP Patches', below.

JSP patches

Whether using the automated or manual installation process, you will also need to follow these steps which are difficult to automate but only need to be performed once:

1. Locate the getAssignTo.jsp file within the RKM installation files, open it and find the following line of code:

if (HomeFinder.getDefault().getAppConfig().isRemedyAuthentication())

and add the code highlighted in bold below:

if (HomeFinder.getDefault().getAppConfig().isNoAuthentication() ||HomeFinder.getDefault().getAppConfig().isRemedyAuthentication())

Manual installation

The installation involves a couple of changes to the RKM configuration and copying files from a correctly configured Midtier.

Please do not proceed to install SSO on RKM until you are completely satisfied with the SSO configuration for the Midtier.

The installation steps are as follows:

1. Copy the WEB-INF/lib/jss-sso.jar file from the Midtier into the same location in the rkm installation.

2. Copy the relevant jss-sso-rkm-X.jar from the jss-sso/rkm within the Midtier to the RKM WEB-INF/lib directory, where X is 7.2 if RKM 7.2, or 7.5 for RKM 7.5 and above.

For example, if your Midtier installation is located at c:\Program Files\BMC\Midtier and RKM is installed at c:\Program Files\BMC\RKM then for step 1, copy c:\Program Files\BMC\Midtier\WEB-INF\lib\MidTier.jar to c:\Program Files\BMC\RKM\WEB-INF\lib.

3. Locate the following file from the RKM installation:

WEB-INF/classes/kms/authenticators/SimpleAuthenticator.class


Page 37 of 48

Rename it by appending .old to the filename.

4. Go to the RKM configuration page, i.e. http://hostname:8080/rkm/configuration

5. Select Authentication on the Configuration Settings page.

6. Set the Mode to None. This may seem odd but JSS have used the 'None' authentication layer within RKM to implement SSO.

7. Click save.

8. This step is only for those using Windows Authentication. Find the web.xml file in the rkm installation (it's in the WEB-INF directory) and make a backup of it. Open up the original web.xml file and the web.xml.rkm.patch file that's located in the jss-sso/rkm directory within the Midtier. Copy the contents of the patch file and paste it into the web.xml file at the point below the last </filter> element and before the following <filter-mapping> element. i.e. The non-italic text below is in the web.xml, and the patch is placed at the point highlighted.

<filter> <filtername>SystemFilter</filtername>

<filterclass>kms.filters.SystemFilter</filterclass></filter>

The patch goes here.

<! To use non XDoclet filtermappings, create a filtermappings.xml file that ….

9. You must also follow the steps in 'JSP Patches', above.

10. Restart the webserver running RKM.

To integrate with your SSO system, simply point the browser at the usual homepage RKM link, i.e. http://hostname:8080/rkm/home.jsp.

Manually logging in to RKM

The SSO Plugin extends the original Remedy authentication scheme and delegates authentication to it in the event an SSO login can not be performed. Therefore, existing manual login functionality is still available.

What to do if you reconfigure the Midtier or SSO Plugin

The Midtier configuration is held in the AR System so restarting RKM will result in the new configuration being loaded.

Enabling RKM logging

If there's a problem then you will need to send JSS the webserver standard out log files (i.e. the Tomcat stdout.log or catalina.out file, in the logs directory). RKM may not be configured to write all log messages to the log file, so to ensure they are, follow these steps:


Page 38 of 48

1. Go to the RKM configuration page, i.e. http://hostname:8080/rkm/configuration

2. Select General on the Configuration Settings page.

3. Click the Log Level and set to Debug.

4. Click save.

5. Restart the webserver running RKM.


Page 39 of 48

Upgrades

If using a version prior to 2.3

Remove all existing SSO Plugin files and re-install the product from scratch.

If using version 2.3

Before running the installation program (setup.exe) you must do the following:

1. Stop the AR Server

2. Backup the ar.cfg

3. Remove the Plugin: jss-sso.[dll or so] line from the ar.cfg configuration file.

4. Delete the existing jss-sso.[dll or so]

5. Run the installation program Using the SSO AREA plugin installer

6. Copy the contents of the mt directory within the installation set to the Midtier, as per the instructions for installing the Midtier components.

7. Go to the Midtier interface, check and submit the configuration.

When you run the installer (setup.exe) the application will detect an existing SSO instance. You will be presented with the following screen. Please select Remove old installation and continue. This will remove any existing forms and information from previous installations. Then click Next.


Page 40 of 48


Please follow these steps if you are upgrading from the above SSO versions.

Upgrading the AR System

First you must reset the ssoadmin password, then you must shutdown the AR Server and replace the jss-sso.dll (or .so depending on your AR Server operating System) with the new v3 plugin.

To reset the ssoadmin password, run the v3.0 install program (setup.exe) and login using an Administrator login. On finding the previous installation, you should be prompted with the following page:


Page 41 of 48

Make sure you select “Update ssoadmin password” and click Next. The application will calculate the new password and update the user record automatically.

Now shutdown the AR Server and copy the new v3 plugin to your AR Servers and restart.

Upgrading the Midtier

As with any normal installation, copy the contents of the mt directory into your Midtier. In version 3, the Midtier configuration is stored in the AR System and any existing configuration will be read from the file used by previous versions. Restart the Midtier, go to the Midtier interface, check and submit the configuration, which will push it into the AR System.


Upgrading the AR System

First the new ssoadm.30.def file needs to be imported. This file can be found in the installation package. Follow this section Import Workflow

Next you must shutdown the AR Server and replace the jss-sso.dll (or .so depending on your AR Server operating System, it is very important you replace the binary that matches your AR Server operating system. E.g. The solaris build is found in the \installer\sso-libs\solaris directory) with the new v3.1 plugin found within the installation package.

Upgrading the Midtier

As with any normal installation, copy the contents of the mt directory into your Midtier. Restart the Midtier.


Page 42 of 48

If you're using built-in authentication and NTLM, you will need to reconfigure the SSO Plugin so please review the Configuring NTLM section of this manual.


If you are using the first release of version 3.1, an updated AREA Plugin and SSO workflow definition file was included in version 3.1.1. Therefore, please replace your AREA Plugin with the relevant one from the release, and also import the ssoadm31.def file from the installation directory.


Page 43 of 48

Manually configuring the AR System

If for any reason the installation program fails. As always, you can contact JSS support. However, you can manually install the product with the following steps.

Please make sure you have copied the files as in section Copy files to your AR System

Import Workflow

Locate the ssoadm30.def file within the downloaded zip from the evaluation package. Depending on what version you have of your AR System depends on how this is imported. The screenshot below is taken from a 7.1 Administrator Tool. Please note that the option “Replace Objects on the Destination Server” is checked and the “Handle Conflicting Types” is set to “Replace with new type” and make sure ALL OBJECTS are imported from the def file including the flashboard variables and flashboards themselves.

Updating Repository Details

The .def file import installs an application called “SSO Administration”. This enables administrators only, to update SSO configuration.


Page 44 of 48

Midtier Shared Key: plain text key. For the initial install, use password

ARUSER Shared Key: plain text key. For the initial install, use password

Midtier IP Address: insert the IP addresses of the SSO enabled midtiers.

License: This is the license key delivered by JSS. You can request a trial key from JSS.

Show Password in the arplugin log file: This will verify is the correct values are being passed from all the clients. While verifying the installation, it is a good idea to have this enabled. This can be turned off at any time.

Check AR External Authentication (AREA) is Enabled

Login via the BMC Remedy User Tool with a user with administrative permissions. Open the AR System Administration Console and click on System and then General.

• Click on the EA tab.

• Make sure the RPC number is 390695

• Check the Cross Reference Blank Password

• Authentication Chaining Mode set to Off

• Click Apply and Save.


Page 45 of 48

Disable 'Allow Guest Users'

This must be disabled or the AR System will allow login attempts for users that are not present in the User form. When enabled, the JSS AREA plugin is not called for guest users, and hence automatically accepting guest users poses a security risk.

Check the AREA Hub is Installed and Configured.

If you are using the BMC AREA LDAP plugin, then a prerequisite to enable SSO is that the AR Server in question has the BMC AREA-Hub plugin installed.

To check this is configured, you can either look directly at the ar.conf / ar.cfg file or you can use the AR System User Tool.

Open the User Tool and Search for the form Configuration ARDBC. Once opened place the value areahub in the name field and search:


Page 46 of 48

Screenshot showing searching for the areahub

If this is configured, then you should observe a reply showing the areahub in the ar.conf / ar.cfg

Screenshot showing the results of the search if the areahub is installed.

If this setting is not found within the ar.cfg file or through the Configuration ARDBC form then you can quickly enable it by adding the following lines to your ar.cfg file.

Windows

Plugin: areahub.dll

Solaris/Linux

Plugin: areahub.so

You will need to restart the AR System and this can be verified within the Plug-in log file as described in section Enable logging for verification

Below is an example of what to look for within the Plug-in log file to verify the areahub is installed and configured. If the file is large, you can easily search for ARSYS.AREA.HUB


Page 47 of 48

Windows User Tool SSO – ARSSOInfo.dll

SSO for the User Tool was introduced in version 2.3 This involves placing two files on the clients PC or laptop within the same directory as the aruser.exe

Please continue to this section SSO for the BMC Remedy Windows User Tool

Check the AREA LDAP Configuration

Only follow this section if you are using an LDAP or Active Directory to store your user information. Alternatively, if you are just using the AR Systems USER table to verify then skip to Configure the AREA HUB to Use the JSS SSO Plugin .

After confirming the AREA Hub is installed, the next configuration task is to configure or confirm the configuration of the BMC AREA LDAP Plugin. The JSS SSO product will enable the user to login to the AR System via SSO but for those users who are not configured to use SSO may have to verify via other means.

Details can be found in the following documentation:

• Page 152 of the BMC Remedy Action Request System 7.0 Integrating with Plug-ins and Third-Party Products http://www.bmc.com/supportu/documents/84/67/58467/58467.pdf

• Page 133 of the BMC Remedy Action Request System 7.1.00 Integrating with Plug-ins and Third-Party Products http://www.bmc.com/supportu/documents/93/94/69394/69394.pdf

• Page 143 of the BMC Remedy Action Request System 7.5.00 Integration Guide http://www.bmc.com/supportu/documents/53/80/95380/95380.pdf

Open the form AREA LDAP Configuration form and make sure the details are populated and that a user can use the User Tool or Midtier to login via AREA.


http://www.bmc.com/supportu/documents/53/80/95380/95380.pdf

http://www.bmc.com/supportu/documents/93/94/69394/69394.pdf

http://www.bmc.com/supportu/documents/84/67/58467/58467.pdf-

Page 48 of 48

Screenshot of the AREA LDAP Configuration form

Configure the AREA HUB to Use the JSS SSO Plugin

Now we need to enable the JSS SSO Plug-in. The jss-sso.dll (using the windows library for demonstration purposes) has to be configured to be the first AREA plugin used within the AREA Hub. To enable this, the ar.conf / ar.cfg file needs to look like this if you are authenticating WITHOUT LDAP or AD:

Plugin: areahub.dll

AREAHubPlugin: jsssso.dll

Or if you using LDAP/AD:

Plugin: areahub.dll

AREAHubPlugin: jsssso.dllAREAHubPlugin: arealdap.dll

It is important that the jss-sso.dll is listed before the arealdap.dll.

Also remember these settings are case sensitive.


Date post:	17-Jul-2020
Category:	Documents
Upload:	others
View:	0 times
Download:	0 times

SSO Plug-in v 3 - Java System Solutions · 2018-03-07 · credentials. So the installation process...

Documents