BMC Atrium Orchestrator installation

SSO Plugin Integrating with BMC Atrium Orchestrator

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

Version 4.0

JSS SSO Plugin – Integrating with BMC Atrium Orchestrator

http://www.javasystemsolutions.com

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

Versions covered....................................................................................................................... 3

Terms of reference........................................................................................................................ 4

Planning the deployment ............................................................................................................... 5

Pre-requisite deployment choice ..................................................................................................... 6

Enabling the Identity Federation Service ......................................................................................... 8

Installation ................................................................................................................................... 9

Testing ..................................................................................................................................... 9

Hostnames ............................................................................................................................... 9

Patching the BMC agent jar file .................................................................................................... 10

Installing the patched agent jar file .......................................................................................... 10

Patching the web.xml file ............................................................................................................. 12

Automatic patching ................................................................................................................. 12

Manual patching ..................................................................................................................... 13

Installing the patched web.xml file ........................................................................................... 14

Installing the group mapping file .................................................................................................. 16

Customising the group mapping............................................................................................... 16

Installation process ..................................................................................................................... 17

Enabling SSO for AO CDP ........................................................................................................ 17

Enabling SSO for AO OCP ........................................................................................................ 17

Enabling SSO for AO Repository ............................................................................................... 17

Sending log files to the JSS support team ..................................................................................... 19

Example planning worksheet ....................................................................................................... 20

Page 3 of 21


Introduction

This document covers the integration of SSO Plugin with BMC Atrium Orchestrator.

Versions covered

Application Version

BMC Atrium Orchestrator 7.7+

JSS SSO Plugin 3.6.13+

Table 1 : Application Versions Covered

Page 4 of 21


Terms of reference

Reference Description

BAO BMC Atrium Orchestrator

BAO REPO BMC Atrium Orchestrator Repository

BAO CDP BMC Atrium Orchestrator Configuration Distribution Peer

BAO OCP BMC Atrium Orchestrator Operator Control Panel

JSS Java Systems Solutions

JSS SSO

Plugin

Java Systems Solutions Single Sign on plugin

IFS Java Systems Solutions SSO Identity Federation Service

Tomcat Apache Tomcat Webserver

Browser Supported Internet Browsers. Google Chrome v16+; Microsoft Internet Explorer

v9+; Mozilla Firefox v18+; Apple Safari 5+

FQDN Fully Qualified Domain Name

E.g bao.mycompany.org

BAO HA CDP BMC Atrium Orchestrator High Availability Configuration Distribution Peer

BAO AP BMC Atrium Orchestrator Activity Peer

BAO LAP BMC Atrium Orchestrator Lightweight Activity Peer

Table 2 : Terms of Reference

Page 5 of 21


Planning the deployment

Preparation is key to a successful deployment of JSS SSO for BAO.

A worksheet has been provided to allow the configuration information required to be ascertain

beforehand and easily referenced during the installation. We highly recommend this before Planning

Worksheet.

Prior to deployment please fill in the attached worksheet detailing the deployment information for

your BAO Grid.

BAO Installation Configuration

Hostname Access URL Role Port Installation Location Tomcat Service

Name

BAO Repository

BAO Content Distribution Peer

BAO Operator Control Panel

BMC Atrium Orchestrator

High Availability CDP

BMC Atrium

Orchestrator Activity Peer

BMC Atrium Orchestrator Lightweight

Activity Peer

JSS SSO Plugin Configuration If you already have an instance of JSS SSO Plugin running within the environment that houses BAO please record the details below

Hostname URL

Current JSS SSO Plugin Configuration

Unique Key To enable the JSS SSO Plugin a unique must be generated. For audit purposes please enter this key here

Key

Table 3 : Installation Planning Worksheet

Page 6 of 21


Pre-requisite deployment choice

The integration makes use of the SSO Plugin Identity Federation Service, which allows a single SSO

Plugin instance to be configured for user authentication, and for third party applications to

authenticate against it.

If an existing SSO Plugin instance is deployed within your environment, ie SSO Plugin for BMC ITSM,

this can be re-used.

If there is no existing SSO Plugin instance, download the SSO IFS from the JSS website. To install it,

follow these steps:

1. Login to your Support Account at www.javasystemsolutions.com

a. Browse to http://www.javasystemsolutions.com/jss/downloads

b. Download the SSO Plugin for the following applications

2. Unpack the zip file downloaded from the JSS website.

3. Locate the authentication-service.war file.

Figure 1 : example extracted contents of SSO Plugin

4. Copy the authentication-service.war file into the BMC AO Repository Tomcat instance webapps directory, see “Planning Worksheet”

Figure 2: example deployment of JSS SSO Plugin Identity Federation Service war file

5. Restart service BMC AO REPO Tomcat, identifying the host detailed in the planning

worksheet.

http://www.javasystemsolutions.com/

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

Page 7 of 21


Figure 3 : example BMC AO Repository Service

6. Once the authentication plugin is installed it needs to be configured.

a. Using an Internet Browser access the plugin and going to the following address

referenced in the “Planning Worksheet”:

<URL for BAO REPO>\authentication-service

7. Enter the default password of “jss” on the left hand side navigation to access and the

configuration page.

Figure 4 : Example deployment of JSS SSO Plugin Authentication Service status page

Page 8 of 21


Enabling the Identity Federation Service

After the JSS SSO configuration page has been accessed you must enable the Identity Federation

Service using the SSO Plugin instance identified accessed in the “Planning Worksheet”, ie either an

existing one within BMC ITSM or the Authentication Service.

To do so, follow these instructions:

1. From the status page Click configuration.

2. Tick 'Enable Identity Federation Service'.

3. Enter a unique key or press the button to create one. Take a note of the key in the planning

worksheet

Figure 5 : Example Federation Key

4. Press 'Set configuration' and ensure the SSO Plugin still functions using the 'Test SSO' link.

Figure 6 : Example JSS SSO Plugin configuration page

Page 9 of 21


Installation

BMC Atrium Orchestrator (BAO) 7.7 runs in a grid architecture and comprises of three applications:

BAO Configuration Distribution Peer (BAO CDP)

BAO Operator Control Panel (BAO OCP)

BAO Repository (BAO REPO)

Each application on each server in the Grid will require patching for a full SSO deployment. The

installation sequence is important and must be carried out in the order specified below.

1. BAO CDP:

a. Patching the BMC agent jar file.

b. Patching the web.xml.

2. BAO OCP:

a. Patching the BMC agent jar file.


3. BAO REPO:

a. Patching the BMC agent jar file


c. Patching the applicationContext.xml file.

Testing

To test a JSS SSO deployment for BAO, each application will need to be tested in turn.

Please note: do not perform any work on your BAO Grids until all servers have been successfully tested post JSS SSO deployment

1. BAO CDP

Using a browser navigate to the BAO CDP URL in the “Planning Worksheet”.

2. BAO OCP

Using a browser navigate to the BAO OCP URL in the “Planning Worksheet”.

3. BAO REPO

Using a browser navigate to the BAO REPO URL in the “Planning Worksheet”.

Each server should provide access to the application without being prompted for a

username/password

Hostnames

The JSS SSO Plugin server uses domains for single sign-on cookie validity and requires the use of a

FQDN to integrate with different servers.

Therefore, BAO CDP, BAO REPO, BAO OCP, BAO HA-CDP, BAO AP, and BAO LAP must be installed by

specifying the FQDN and not the IP address or host name.

Page 10 of 21


Patching the BMC agent jar file

When configuring each application, you must patch the agent file typically called agent-version.jar (ie

agent-7.7.00.00.jar) that is located in the application's <tomcat installation>WEB-INF/lib directory, ie

C:\Program Files\BMC Software\BAO\REPO\tomcat\webapps\baorepo\WEB-INF\lib

JSS provides an easy to use patching tool for the agent jar file where a patched file can produced.

Follow these steps to patch the file

1. Login to the BAO Server (for this example we will assume that we are patching the BAO

REPO server) using the access tool of you choice (RDP, SSH etc)

2. Locate the agent<version>.jar file

3. Copy the file back to a local desktop computer that has access to the Internet

4. Using a browser of the local desktop navigate to the

URL:http://www.javasystemsolutions.com/jss/service#agent

5. Enter the Secret Key set up in section “Enabling the Identify Federation Service”

6. Click browse and select the downloaded agent<version>.jar file

7. Click Get Patched file and save the patched file to your desktop

Figure 7 : Example agent jar patching tool

Installing the patched agent jar file

To install the patched agent jar file:

1. Log back onto the server with the remote access tool of your choice

2. Stop the Tomcat Service

3. Locate the original agent jar file in the WEB-INF/lib

http://www.javasystemsolutions.com/jss/service#agent

Page 11 of 21


4. Move the original agent jar file out of it's current directory to a backup directory outside of

Tomcat

If the original jar file remains in the WEB-INF/lib directory, Tomcat may ignore the patched jar file.

5. Place the patched agent jar file to the WEB-INF/lib directory

6. Restart Tomcat

The agent jar files within the different applications are typically the same file so you should only need

to patch one file and re-use it.

Figure 8 : Example patched agent jar

Page 12 of 21


Patching the web.xml file

This can be performed automatically, using a tool on the JSS website, or manually.

Automatic patching

As well as patching the agent jar file the web.xml for each application instance must be patched as

well. The process is the same as the agent jar with the important note:

The web.xml files are not interchangeable between servers and each BAO Server (CDP/REPO/OCP)

must have its respective web.xml file patched and applied.

As per the agent jar patching JSS provide easy to use patching tool on the JSS Website.

The web.xml file is typically located within the WEB-INF directory in a tomcat installation, ie.

C:\Program Files\BMC Software\BAO\REPO\tomcat\webapps\baorepo\WEB-INF\

1. Login to the BAO Server (for this example we will assume that we are patching the BAO

REPO server) using the access tool of your choice (RDP, SSH etc)

2. Locate the web.xml file

3. Copy the file back to a local desktop computer that has access to the Internet

4. Using a browser of the local desktop navigate to the

URL:http://www.javasystemsolutions.com/jss/service#webxml

5. Enter the details in the patching tool menus:

a. Product to be patched

b. URL to SSO Plugin. This is the URL where the authentication-service is installed

c. Enter the secret key

d. Click browse and select the uploaded web.xml file

e. Select ‘get patched file’ and download the patched web.xml file

Figure 9 : Example web.xml patching tool l

http://www.javasystemsolutions.com/jss/service#webxml

Page 13 of 21


Manual patching

To manually edit the web.xml follow these steps:

1. Create a backup of the web.xml file.

2. Open the web.xml, locate the AtriumSSO filter and delete it:

<filter>

<filter-name>Agent</filter-name>

<filter-class>com.bmc.atrium.sso.agents.web.jee.JEEFilter</filter-class>

...

</filter>

<filter-mapping>

<filter-name>Agent</filter-name>

...

<dispatcher>ERROR</dispatcher>

</filter-mapping>

3. Paste the following in the location of the now deleted AtriumSSO filter:

<filter>

<filter-name>ssoplugin-identity-federation-acceptor</filter-name>

<filter-

class>com.javasystemsolutions.integrations.asso.ASSOIdentityFederationAccep

tor</filter-class>

<init-param>

<param-name>identityFederationServiceURL</param-name>

<param-value>HOSTNAME/jss-sso/identityfederationservice</param-value>

</init-param>

<init-param>

<param-name>key</param-name>

<param-value>KEY</param-value>

</init-param>

<init-param>

<param-name>loglevel</param-name>



<param-value>INFO</param-value>

</init-param>

<init-param>

<param-name>principalSessionKey</param-name>

<param-value>com.bmc.ao.sso.principal</param-value>

</init-param>

<init-param>

<param-name>usernameSessionKey</param-name>

<param-value>com.bmc.ao.sso.userid</param-value>

</init-param>

</filter>

4. Referring to the text above, pasted into the web.xml file, set the following variables:

Page 14 of 21


a. HOSTNAME: This points to the identity federation service running on the SSO

Plugin installation. Referenced in the “Planning Worksheet” or in documented

in Section 5.B if this is a new install of the JSS SSO Plugin.

After entering the URL, test by navigating to the BAO REPO URL with a browser.

You should see an SSO Plugin web page mentioning the Identity Federation

Service.

b. KEY: This must be set to the federated identity key noted when is Section 5.B

5. For the CDP and OCP components, add the following below </init-param>:

<init-param>

<param-name>skipURIs</param-name>

<param-value>/ws/</param-value>

</init-param>

6. Add a filter mapping after the </filter> tag as follows:

a. For the CDP and OCP components:

<filter-mapping>


<url-pattern>/*</url-pattern>

</filter-mapping>

b. For the Repository component:

<filter-mapping>


<url-pattern>/messagebroker/*</url-pattern>

<url-pattern>/repo-ui/*</url-pattern>

</filter-mapping>

7. For all components, add the following after the last </filter-mapping>:

<filter>

<filter-name>jssLogoutFilter</filter-name>

<filter-

class>com.javasystemsolutions.integrations.asso.SpringLogoutFilter</filter-

class>

<init-param>

<param-name>targetPage</param-name>

<param-value>/loggedOut.jsp</param-value>

</init-param>

</filter><filter-mapping>

<filter-name>jssLogoutFilter</filter-name>

<url-pattern>//j_spring_security_logout</url-pattern>

</filter-mapping>

8. Save the file.

Installing the patched web.xml file

To install the patched web.xml file:

1. Log back onto the server with the remote access tool of your choice.

2. Stop the Tomcat Service.

Page 15 of 21


3. Locate the original web.xml file in the WEB-INF directory.

4. Move the original web.xml file out of its current directory to a backup directory outside of

Tomcat.

5. Place the patched web.xml file to the WEB-INF directory and ensure it is named web.xml.

6. Restart Tomcat.

Page 16 of 21


Installing the group mapping file

SSO Plugin requires a file called jss-ssoplugin-groupmapping.properties to be present in the web

application WEB-INF/classes properties in order to map SSO or ITSM groups to product groups, ie

mapping ITSM Administrator to AoAdmin.

Within the asso directory in the installation files, a file called jss-ssoplugin-

groupmapping.ao.properties can be found. This file should be copied to the component's WEB-

INF/classes directory and renamed to jss-ssoplugin.groupmapping.properties.

Customising the group mapping

The product includes a default group mapping against BMC ITSM, therefore it assumes the Identity

Federation Service is running on a Mid Tier connected to ITSM. The group mapping is held in a file

called jss-ssoplugin-groupmapping.properties and can be customised.

The default group mapping file maps ITSM groups as follows:

BMC ITSM BMC Atrium Orchestrator

Adminstrator AoAdmin

CDP View Grid Status View_Grid_Status

CDP Grid Management Grid_Management

CDP Grid Administration Grid_Administration

CDP Grid Development Studio Development_Studio

Page 17 of 21


Installation process

Enabling SSO Plugin for AO involves the configuration of the following three components.

Enabling SSO for AO CDP

To enable SSO Plugin for the BAO CDP, follow these instructions:

1. Stop the Tomcat instance running the BAO CDP: reference “Planning Worksheet”.

2. Locate the BAO CDP web application: reference “Planning Worksheet”.

3. Patch the agent jar file in the WEB-INF/lib directory.

4. Patch the web.xml file in the WEB-INF directory.

5. Copy the group mapping file into the WEB-INF/classes directory.

6. Copy the jss-sso-asso.jar file, from the asso directory within the SSO Plugin for BMC AR

System download, into the BAO CDP Tomcat installation directory WEB-INF/lib directory referenced in the “Planning Worksheet”.

7. Copy the contents of the atrium-orchestrator directory into the BAO CDP Tomcat installation

directory referenced in the “Planning Worksheet”.

8. Start the BAO CDP Tomcat service, navigate to it and ensure SSO works. If there are any problems that you cannot resolve, please send the relevant log files to JSS.

Enabling SSO for AO OCP

To enable SSO Plugin for the BAO OCP, follow these instructions:

1. Stop the Tomcat instance running the BAO OCP: reference “Planning Worksheet”.

2. Locate the BAO OCP web application: reference “Planning Worksheet”.





System download, into the BAO OCP WEB-INF/lib Referenced in the “Planning Worksheet”.

7. Copy the contents of the atrium-orchestrator directory into the BAO OCP Tomcat installation directory referenced in the “Planning Worksheet”.

8. Start the BAO OCP Tomcat instance, navigate to it and ensure SSO works. If there are any

problems that you cannot resolve, please send the relevant log files to JSS.

Enabling SSO for AO Repository

To enable SSO Plugin for the BAO REPO, follow these instructions:

1. Stop the Tomcat instance running the BAO REPO: reference “Planning Worksheet”.

2. Locate the BAO Repository web application: reference “Planning Worksheet”



Page 18 of 21



6. Locate the applicationContext.xml file located in the BAO REPO Tomcat installation directory

WEB-INF/classes/META-INF, which requires patching:

a. Create a backup of the applicationContext.xml file.

b. Open the applicationContext.xml and locate and delete the following:

<security:filter-chain pattern="/**"

filters="httpSessionContextIntegrationFilter,

atssoStaleTokenFilter,

preAuthenticatedHttpSessionFilter,

logoutFilter,

atssoPreAuthFilter,

wsseProcessingFilter,

basicProcessingFilter,

securityContextHolderAwareRequestFilter,

enforcedAuthenticationFilter,

exceptionTranslationFilter"/>

c. Place the following in the location of the text removed above:

<security:filter-chain pattern="/*" filters="none" />

<security:filter-chain pattern="/**"

filters="httpSessionContextIntegrationFilter,

preAuthenticatedHttpSessionFilter,

logoutFilter,

jss.j2eefilter,

wsseProcessingFilter,

basicProcessingFilter,

securityContextHolderAwareRequestFilter,

enforcedAuthenticationFilter,

exceptionTranslationFilter"/>

d. Locate the following immediately after the text pasted above:

</security:filter-chain-map>

</bean>

e. Paste the following immediately below </bean>:

<bean id="jss.j2eefilter"

class="com.javasystemsolutions.integrations.asso.spring.security.ASSOPreAut

hFilter" />

f. Save the file.


System download, into the WEB-INF/lib directory, for the BAO REPO Tomcat installation

“Planning Worksheet”

8. Start the AO Repository Tomcat instance, navigate to it and ensure SSO works. If there are

any problems that you cannot resolve, please send the relevant log files to JSS.

Page 19 of 21


Sending log files to the JSS support team

If you experience difficulties installing a component, please follow these steps:

1. Set the log level to TRACE in the filter you pasted into the web.xml file.

2. Restart the AO Tomcat instance in question.

3. Attempt to visit the AO component via a web browser.

4. Stop the AO Tomcat.

5. Send the AO Tomcat instance logs directory and the web.xml edited to the JSS support team.

mailto:[email protected]

Page 20 of 21


Example planning worksheet

BAO Installation Configuration

Hostname Access URL Role Port Installation Location Tomcat Service Name

BAO Repository

baorepo https://baprepo/

Primary Repository

443 D:\Program Files\BMC Software\AO\REPO

BMC Atrium Orchestrator Repository

BAO Content

Distribution Peer

baocdp1 https://baocdp1/bao

cdp

Primary CDP

443 D:\Program Files\BMC Software\AO\CDP


Configuration Distribution Peer

BAO

Operator Control Panel

baoocp http://bao

ocp/baoocp

Primary

OCP

443 D:\Program Files\BMC

Software\AO\OCP

BMC Atrium Orchestrat

or High Availability CDP

n/a n/a n/a n/a n/a n/a

BMC Atrium Orchestrat

or Activity Peer



Lightweight Activity Peer


JSS SSO Plugin Configuration If you already have an instance of JSS SSO Plugin running within the environment that houses BAO please record the

details below

Hostname URL

Current JSS SSO Plugin Configurati

on

ITSMMIDTIER01 https://itsm.mycompany/authentication-service

Unique Key To enable the JSS SSO Plugin a unique must be generated. For audit purposes please enter this key here

Key FJDHSD97863JLA

https://baocdp1/baocdp



http://baoocp/baoocp



Page 21 of 21

Documents

BMC Atrium Orchestrator installation