Single Sign On Plugin: Integration with BMC MyIT...Deploying a standalone SSO Plugin for MyIT This deployment process is similar to the one followed when deploying SSO Plugin to BMC

SSO Plugin Integration for BMC MyIT, SmartIT and Service Broker

J System Solutions http://www.javasystemsolutions.com

Version 4.1 & 5.0+

JSS SSO Plugin – Integration with BMC MyIT

http://www.javasystemsolutions.com

Introduction.................................................................................................................................. 3

SSO Plugin and AR System compatibility ..................................................................................... 3

Deployment approaches ............................................................................................................ 3

Deploying a standalone SSO Plugin for MyIT................................................................................... 4

Deploying an integration using the Identity Federation Service ........................................................ 8

Configuring SSO Plugin on Mid Tier ............................................................................................ 8

Patch the MyIT web.xml ............................................................................................................ 9

Installing SSO Plugin for BMC MyIT ............................................................................................ 9

Enabling logging in MyIT 3.1+ ..................................................................................................... 11

Troubleshooting SSO for MyIT ..................................................................................................... 12

Service Broker ............................................................................................................................ 13

Enabling SSO Plugin logging .................................................................................................... 13

Page 3 of 14


Introduction

This document covers installation and configuration of SSO Plugin for BMC MyIT 3+. Separate

documents are available for other BMC components (ie AR System, Mid Tier, Dashboards).

As of MyIT version 2.1, the SmartIT product is encapsulated within MyIT so by following this

document, SSO will be enabled for both MyIT and SmartIT.

The JSS support website contains all the SSO Plugin documentation and videos covering installation and configuration.

BMC made a change to the logging framework in MyIT 3.1 and SSO Plugin 4.1 requires a manual change to the MyIT logging configuration file in order to enable SSO Plugin logging. SSO Plugin 5.0+

does not require this change.

SSO Plugin and AR System compatibility

SSO Plugin 4.1 is compatible with AR System versions prior to 9.1. SSO Plugin 5.0+ is compatible with AR System 9.1+.

Deployment approaches

There are two methods of integrating SSO Plugin with MyIT:

1. Using the SSO Plugin for BMC MyIT package, that looks & feels like the SSO Plugin for Mid Tier integration. This integrates directly with the SSO infrastructure and provides value-add

features such as ITSM registration. This is often referred to as “SSO Plugin standalone”.

We recommend this deployment approach as the process/configuration is familiar

to the SSO Plugin for Mid Tier deployment.

2. Using an existing SSO Plugin enabled BMC Mid Tier and the SSO Plugin Identity Federation

Service installed within MyIT.

We do not recommend this approach unless you have discussed your requirements with JSS support.

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

Page 4 of 14


Deploying a standalone SSO Plugin for MyIT

This deployment process is similar to the one followed when deploying SSO Plugin to BMC Mid Tier, ie

SSO Plugin is copied into MyIT and configured via a web interface.

A video with audio commentary has been created to show you the process.

The installation steps are as follows:

1. Download the SSO Plugin release from the JSS website. If deploying SSO Plugin 5.0+, the package is included in the “SSO Plugin for BMC products” download:

For SSO Plugin 4.1, the MyIT standalone build is a separate package and listed under “SSO Plugin for BMC MyIT (standalone)”.

2. Shutdown the Smart IT/MyIT Application service (ie Tomcat).

https://www.javasystemsolutions.com/support/video

https://www.javasystemsolutions.com/support/download

Page 5 of 14


3. Unpack the zip file package downloaded from the JSS website.

a. With SSO Plugin 5.0, copy the contents of the “3 – MyIT and SmartIT\myit” directory to the Smart_IT_MyIT\ux directory

b. With SSO Plugin 4.1, copy the contents of the myit directory to the

Smart_IT_MyIT\ux directory

4. Start the Smart IT/MyIT Application service.

Page 6 of 14


5. Once the service has restarted, open a browser and point to your MyIT instance with the

following SSO Plugin configuration URL:

http(s)://myit.yourcompany:9000/ux/jss-sso/index.jsp

You should see the following interface:

Page 7 of 14


6. To configure an SSO integration, login on the left with the default password jss and use the

interface as documented in the “configuring an SSO integration” document.

Example screenshot of Integration link showing the default Windows authentication method:

7. Change the default password using the configuration page.

8. Once you have selected and configured the integration method, you will be prompted to

restart the Smart IT/MyIT Application service.

Page 8 of 14


Deploying an integration using the Identity Federation Service

SSO Plugin runs on the Mid Tier providing SSO for the existing BMC applications, and also extends

SSO to MyIT through the SSO Plugin “Identity Federation Service”. This allows third party products, BMC or non-BMC, to be SSO enabled with the Mid Tier (and hence, AR System User form) as a single

repository of data.

The flow of data is as follows:

1. When a request hits the SSO Plugin URL (http://myit.ssoplugin.local:9000/ux/myitapp/) on

MyIT and no session exists, it is redirected to the Mid Tier running SSO Plugin.

2. The user passes through the configured SSO implementation and when complete, the request

is sent back to MyIT with the AR System User form detail (such as their groups).

3. The SSO Plugin passes the username into MyIT which progresses through the existing MyIT login process.

Configuring SSO Plugin on Mid Tier

You must first set up SSO Plugin to enable the Identity Federation Service, typically running on BMC

Mid Tier:

1. Login to the Mid Tier SSO Plugin configuration page, ie. http://yourmidtier/arsys/jss-sso/index.jsp.

2. Click Configuration.

3. Tick 'Enable Identity Federation Service'.

4. Enter a unique key or press the Random button to create one. Take a note of the key for the next section.

5. Click 'Set configuration' and ensure the SSO Plugin still functions using the 'Test SSO'

link.

Page 9 of 14


Patch the MyIT web.xml

The MyIT ux web.xml file (default location is C:\Program Files\BMC Software\Smart_IT_MyIT\Smart_IT_MyIT\ux\WEB-INF) requires patching. We provide a tool on the JSS support website to do this for you and recommend you use it, or you can do this manually.

1. Browse to the following page http://www.javasystemsolutions.com/support/tools

2. Select BMC MyIT from the Product menu

3. Enter your full URL of the Mid Tier default web path as it is configured in the AR System Administration Console. Example http://midtier.yournetwork.com/arsys

4. Enter the Federation Key copied in the previous task, to the Federation Key box

5. Click the Choose File button and browse to the MyIT ux web.xml on your installation. Note that your existing web.xml file will not be modified.

6. Click Get patched file and save the new patched-web.xml to the same directory for use in the next section.

Installing SSO Plugin for BMC MyIT

To enable SSO Plugin for BMC MyIT, the following steps must be followed:

1. Stop the instance of Tomcat running MyIT. The display name is Smart IT/MyIT Application.

2. Backup the original web.xml file and rename the patched-web.xml that was configured via the JSS website and saved in the previous section to web.xml. The default directory is C:\Program Files\BMC Software\Smart_IT_MyIT\Smart_IT_MyIT\ux\WEB-INF

3. Locate the jss-sso-myit.jar file from the product download.

Page 10 of 14


a. With SSO Pugin 5.0, download the “SSO Plugin for BMC products” package, and the jar file is located in the in the 4 - Identity Federated Application/myit-smartit directory.

b. With SSO Pugin 4.1, download the “SSO Plugin for BMC products” package, and the jar file is located in the in the myit directory.

4. Locate the index.html file under the ux web application directory.

5. Rename the index.html file to index.jsp.

6. Open the index.jsp file in your favourite text editor and add the following to the top of the file:

<% response.setHeader("Cache-Control", "no-cache"); %>

7. A setting in the MyIT database switches on SSO. Locate the TENANT table and set

SAML_AUTHENTICATION=1 where PK=1. Example SQL:

update [SmartIT].[SmartIT_System].TENANT set SAML_AUTHENTICATION = 1 where

PK = 1

8. Example screenshot:

9. Start the instance of Tomcat running MyIT. The display name is Smart IT/MyIT Application.

10. Verify the installation by browsing to http://myit.yourdomain.com:9000/ux/

Page 11 of 14


Enabling logging in MyIT 3.1+

This section is only applicable if using SSO Plugin 4.1. SSO Plugin 5.0+ has been modified to

automate this step.

BMC changed the logging framework in MyIT 3.1 and a change to the MyIT logging configuration file

is required to allow SSO Plugin 4.1 to produce a log file.

The MyIT logback.xml file is located in the tomcat/external-conf directory. Open it in your favourite text edit, locate the section below and add the text in bold:

<if condition='${LOG_TO_SEPARATE_FILES}'>

<then>

<logger name="com.javasystemsolutions" level="ALL">

<appender-ref ref="FILE"/>

</logger>

And do the same again here:

<else>

<logger name="com.javasystemsolutions" level="ALL">


</logger>

<logger name="REST" level="ERROR">


Restart MyIT and SSO Plugin logging will now be written to the ux-stdout log files.

Page 12 of 14


Troubleshooting SSO for MyIT

Browsing to the Test SSO link is the first task for anyone that is unable to use SSO for MyIT. This

should give an indication of any issues and will often provide instruction on how to resolve issues.

If the issue is not obvious from the reported messages:

1. Browse to the SSO Plugin interface, login on the left hand side (default password is jss).

2. Click Configuration, set the Diagnostic log level to Trace and click the Set Configuration button.

3. Click Test SSO or follow the steps to reproduce the issue, ie navigate to:

http(s)://myit.yourcompany:9000/ux/jss-sso/testsso – the following is the output of a successful test.

4. Take a screenshot of the Test SSO page output, or the issue you see.

5. Locate the Smart IT/MyIT Application service (Tomcat) log files, typically at:

a. C:\Program Files\BMC Software\Smart_IT_MyIT\Smart_IT_MyIT\Logs\date\smartitmyittomcat7-

stdout.date.log

b. C:/Program Files/BMC Software/Smart_IT_MyIT/Smart_IT_MyIT/Logs/ux.log.

The path to the log files will vary given your deployment/operating system.

6. Send the screenshot and the log files to [email protected].

mailto:[email protected]

Page 13 of 14


Service Broker

The BMC Service Broker component can be configured with SSO Plugin but this model is only supported when SSO Plugin standalone has been installed with MyIT.

The SSO Plugin SB component makes use of the Identity Federation Service, which should be enabled on the SSO Plugin MyIT instance.

To enable this integration, ask BMC Support for the SSO Plugin integration kit for SB. They should send you two files: com.bmc.arsys.restapi-XXX-SNAPSHOT.jar and com.example.jssowrapper-XXX-SNAPSHOT.jar (where XXX is typically an SB version).

The com.example.jssowrapper file requires updating with the latest SSO Plugin SB integration. Follow these steps:

1. Create a new directory.

2. Change into the new directory and unpack the com.example.jssowrapper jar, ie jar xf /path/to/com.example.jssowrapper.jar.

3. Locate the jss-sso-servicebroker.jar file from the "4 - Identity Federation Applications/servicebroker" directory within the SSO Plugin 5.0.x download.

4. Copy the the jss-sso-servicebroker.jar to the directory created in (1), overwriting the jss-sso-1.0.jar file.

5. Re-create the com.example.jssowrapper jar file using this command: jar cf /path/to/com.example.jssowrapper-updated.jar.

6. Deploy the com.example.jssowrapper-updated.jar and com.bmc.arsys.restapi-XXX-SNAPSHOT.jar files to SB.

You must also configure a properties file that is loaded by SSO Plugin’s SB integration.

Create a file named jss.sso.properties in <sb ar server installdir>/conf and place the following in it, substituting the values in bold for the values in your environment:

jss.sso.identityFederationServiceURL=https://myit.yourdomain.com/ux/jss-

sso/identityfederationservice

jss.sso.key=keyConfiguredWithMyITIdentityFederationService

jss.sso.domain=yourdomain.com

jss.sso.cookieDomain=yourdomain.com

jss.sso.cookiePath=/

jss.sso.skipURIs=/api/myit-sb/users/login,/api/myit-sb/version,/api/myit-

sb/healthcheck

jss.sso.loglevel=INFO

The value for jss.sso.domain should be the one you entered as the tenant identifier during installation.

Enabling SSO Plugin logging

In order to activate SSO Plugin logging for Service Broker, follow these steps:

1. Locate the <Service Broker AR System installation directory>/conf/logback_server.xml file and open it in your favourite text editor.

2. Add the following above the <root> element:

<logger name="com.javasystemsolutions" level="TRACE" additivity="false">

<appender-ref ref="ServerLog" />

Page 14 of 14


</logger>

You do not need to restart SB to activate these changes, as the UI provides a reload feature as per this screenshot:

Documents

Single Sign On Plugin: Integration with BMC MyIT...Deploying a standalone SSO Plugin for MyIT This deployment process is similar to the one followed when deploying SSO Plugin to BMC