SSO Plugin. Installation for BMC AR System. J System Solutions. Version 5.1

Transcription

1 SSO Plugin Installation for BMC AR System J System Solutions Version 5.1

2 Introduction... 3 Compatibility... 4 Operating systems... 4 BMC Action Request System / ITSM... 4 Java web servers... 4 Single-sign on integrations and mechanisms... 4 Mixing versions of SSO Plugin... 4 Overview of the SSO Plugin... 5 Extensions to AR System authentication... 5 Installing the JSS component in AR System... 6 Mid Tier installation... 7 Replacing the BMC Mid Tier login page... 7 SSO Administration Console... 8 SSO Dashboard... 9 Licensing ITSM Incident Mapping SSO Authentication Reporting Self-service ITSM user creation Manually configuring AR System Import workflow Configuring the AR System plugin server JSS AREA plugin log file BMC Remedy SSO support Configuring the service Deploying the JSS rsso.war file Upgrades When using current major release Identity Federated Applications: BMC Analytics, Dashboards, etc Uninstalling SSO Plugin... 21

3 Introduction This document covers: Compatibility matrix and other introductory material for SSO Plugin. Installation and configuration of SSO Plugin for BMC AR System. Upgrading from previous versions. Separate documents are available for other BMC components (ie Mid Tier, My/SmartIT, Analytics). The JSS support website contains all the SSO Plugin documentation and videos covering installation and configuration.

4 Compatibility We strive to support the widest range of products and operating systems. If you require clarification or feel we've missed anything, get in touch with JSS support Operating systems Windows 2003+, Sun Solaris 5.x, HP-UX 11.x, Linux 2.4.x+, AIX BMC Action Request System / ITSM From SSO Plugin 5.0, we support all versions of the BMC AR System since version 9.1. For earlier versions of AR System, please deploy SSO Plugin 4.1. Java web servers We support Tomcat 7+, Weblogic 12c+ and Websphere 8.5+ for the Mid Tier, running under a Java or 7u79 or later Virtual Machine. Please use the latest version of the JVM as the earlier versions contain out-dated SSO related libraries. If you use another Java servlet engine, please contact us to confirm supportability. Single-sign on integrations and mechanisms Please consult the Configuring Mid Tier document for a full list of supported integrations/mechanisms. Mixing versions of SSO Plugin It is not recommended to mix versions of SSO Plugin within your infrastructure.

5 Overview of the SSO Plugin The SSO Plugin is invoked by the Mid Tier 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 SSO Plugin to operate correctly, then these details are passed back to the Mid Tier, which in turn calls the AR System. Assuming the JSS AREA plugin does not reject the connection Mid Tier will login successfully. Extensions to AR System authentication The AR System User form contains a status field that can be set to current and disabled. AR System ignores this setting but the SSO Plugin Mid Tier component does not, so you can disable AR System accounts by using this setting for all authentications passing through an SSO enabled Mid Tier.

6 Installing the JSS component in AR System The following steps will configure the JSS AREA plugin against an AR System server: 1. From the SSO Plugin installation files, copy the jss-sso-area.jar, jss-sso-area-setup.jar and jss-sso-area-setup.bat (Windows) or jss-sso-area-setup.sh (Unix) files to the AR System pluginsvr directory - in which you will find the pluginsvr_config.xml file. 2. Execute the jss-sso-area-setup.bat or jss-sso-area-setup.sh file. 3. The setup process will execute in a console window and ask for an AR System admin account so it can login and configure AR System. 4. If the setup process detects no existing JSS workflow in the database, it will import the JSS workflow. Otherwise, it will ask if you wish to remove existing workflow and re-import - which you should only need to do when upgrading SSO Plugin to a major new version (ie from 5.0 to 5.1). In the event the workflow import fails, the jss-sso-workflow.def file (from the installation files) can be manually imported using BMC Developer Studio. 5. The AR System server SSO settings will be configured correctly and you will be asked to restart AR System. 6. Repeat steps 1-5 for all AR System servers in a server group, and on step 4, do not delete and re-import workflow. At any point where by the SSO settings of an AR System server have been modified, the setup process can be executed to reset them, but do not re-import the workflow file unless you've been advised to by JSS support. The setup process generates a log file called jss-arsystem-setup_date.txt. If the setup process fails, please send this log file to JSS support.

7 Mid Tier installation A separate highly detailed document exists that explains how to configure SSO Plugin for Mid Tier. This section only covers the installation process. To install the SSO Plugin on the Mid Tier, please follow these steps: 1. Copy the contents of the "2 - Mid Tier/Mid Tier" directory from the installation files into the root Mid Tier directory. a. For convenience, A compressed zip file of the Mid Tier directory is provided in the event you need to copy the files to a server via sftp/etc. 2. Delete the Xerces jar file that BMC sometimes install in the Mid Tier/WEB-INF/lib directory. This is an ancient version of the library that is not required and presumably shipped by accident. 3. Restart Mid Tier. 4. Go to the SSO Plugin status page by pointing your browser at Tier/arsys/jss-sso/index.jsp. You will be presented with a status page. The password field in the left navigation is used to enable configuration and accepts the Mid Tier configuration password. 5. Locate the document titled Configuring Mid Tier and Web Tier to configure the SSO Plugin. 6. Test the SSO configuration by clicking on the Test SSO link in from the SSO Plugin 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 Mid Tier Home link in the navigation and you should be taken directly to the Mid Tier Homepage without being asked to login. 7. If SSO fails then review the troubleshooting document or contact JSS support. Replacing the BMC Mid Tier login page It is common to find users bookmark the BMC login page, ie /arsys/shared/login.jsp. This results in support enquiries as SSO will not be activated when this page is requested by users. Therefore, a replacement login page has been provided that is consistent with BMC branding but also highlights the SSO facility to the user. To install the page, follow these steps: 1. Locate existing Mid Tier login.jsp page under the Mid Tier shared directory. 2. Rename the existing login.jsp to login.jsp.old. 3. Create a new file login.jsp and place the following in it: <jsp:forward page="/jss-sso/manuallogin" />

8 SSO Administration Console JSS provides an AR System Application called SSO Administration V5 which allows customers to manage SSO licenses and report on the SSO activity of the instance. There are two Roles that are imported into the system. Role Name SSO Administrator SSO Dashboard Viewer Detail This role should be mapped to the Administrator group and allows licenses to be managed This role allows access to the SSO Dashboard alone for monitoring purposes. The standard installation maps this role to the Administrator group Access to the console is via the Application menu bar > SSO Administration v5 > SSO AR System License Console

9 SSO Dashboard Upon opening the console, the SSO Dashboard will appear. Over time, this will present real time information regarding SSO authentication within the customers environment. Some example of the dashboard data includes: How many success or failures has accrued Among the failures, which product and which IP e.g. X number from Mid Tier with IP How many users are authenticating using a specific authentication method. E.g. SAML, Windows NTLM etc Number of authentications from which BMC Product e.g. Mid Tier, MyIT, Dashboards etc Which browsers and versions are being used Screenshot example of the SSO Dashboard

10 Licensing A license is required to complete the installation of SSO Plugin, therefore a new license will need to be generated for the environment using the licensing tool under "Tools & licensing" on the JSS website. The values needed to generate a license differ depending on the configuration of the AR Servers. The table below represents what value to use: AR Server configuration Single instance Server Group License value from ar.cfg/conf Server-Name Server-Connect-Name Browse to making sure the Product menu has SSO Plugin (5.0 and later) selected. Add the values taken from the ar.cfg/conf files in the Servers box, making sure each server reference is on a separate line. Finally, click the Generate button.

11 To apply the license, click the License & Administration link on the SSO AR System and License Console: Click the License > Add/Remove License menu item. Enter the license in the key field and click Save.

12 ITSM Incident Mapping The product allows incidents to be raised when a user can not access the product. The configuration interface is linked from the SSO License and Reporting Console and looks like this: The event type drop down selects the type of SSO failure event that will be mapped to the incident and the default event type will be used if a specific type is not configured. When the mapping has been located, SSO Plugin will submit data to the BMC Incident Management application through the BMC out of the box HPD:IncidentInterface_Create form. This is completely configurable and easily configured using the Incident Mapping form showed in the screenshot. The special variables ($SSO_USERNAME$, $SSO_DNS_DOMAIN$, etc), that are also used for the user aliasing feature, can be used when mapping text to a field.

13 SSO Authentication Reporting A standard report is installed for reporting on authentications. This can be accessed from the SSO License and Reporting Console > License & Administration > Reports > User Access The BMC Deployable Application cannot allow us to install the report definitions without importing and overwriting the BMC forms, which isn't recommended. Therefore the individual reports are available for manual import within the SSO Plugin download under the 1 - AR System directory. There are two sets of data that need to be imported into two forms; Report and Report Definition. Run the BMC Remedy Data Import tool. Create a new mapping and select the JSS_SSO_StandardReports_Report.xml

14 Select the Target server from the dropdown and select Report for the Target Form Name. Click Auto Map. Save the mapping. Finally click Import menu item. Repeat for the remaining.xml file(s) within the directory

15 Self-service ITSM user creation This feature removes the need for daily synchronisation with a corporate Active Directory because new starters can register themselves with ITSM by virtue of passing through the configured SSO system. The product provides a feature to allow user accounts to be created when a user does not have an account in ITSM. To use this feature, a Person Template must be configured in the SSO Plugin Mid Tier interface. The user is asked to supply their first name, last name, address and phone number, which when combined with the Person Template, will be used to generate a new entry in the People form.

16 Manually configuring 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, which assume you have copied the JSS AREA plugin files to the AR System server pluginsvr directory. Import workflow Before doing this, set the AR System cache mode to development. This is to ensure the definition file loads correctly. Locate the jss-sso-workflow.def file within the downloaded zip from the evaluation package. Within BMC Developer Studio, select Import > Application Locate the jss-sso-workflow.def file within the downloaded zip from the evaluation package.

17 Select the following checkboxes and menu items exactly as the screenshot below And click Finish Configuring the AR System plugin server To enable the JSS AREA plugin, the AR System plugin server configuration file (pluginsvr_config.xml) must be updated. Open the file in your favourite text editor, locate the XML element <plugins> and add the following plugin definition, setting the correct file system path to the jss-sso-area.jar file: <plugin><name>jss.sso.area</name><classname>com.javasystemsolutions.sso.are a.jssareaplugin</classname><pathelement type="location">/path/to/jss-ssoarea.jar</pathelement></plugin> JSS AREA plugin log file The JSS AREA plugin creates its own log file called jss-ssoplugin.log. It is written to the current working directory when the plugin server starts, which is typically similar to C:\Program Files\BMC Software\ARSystem on a Windows installation. You can search for the file using a tool such as Windows Explorer or the Unix find command (ie find /path/to/arsystem name jss-*.log).

18 BMC Remedy SSO support BMC have produced yet another single-sign on solution using similar principals to the BMC AtriumSSO (a re-badged open source OpenSSO/OpenAM product), but are struggling with reliability & support. Despite RemedySSO s shortcomings, some BMC products (such as Atrium Orchestrator) will not install without RemedySSO installed and in some cases, different BMC products require different versions of RemedySSO! Each BMC product, such as ITSM, MyIT, AO, Discovery (etc) includes a RemedySSO agent, and this talks to the RemedySSO service. The agent uses a variety of different HTTP calls to integrate with the RemedySSO service. SSO Plugin 5.1 provides a service that is compatible with a RemedySSO server, allowing you to integrate any BMC application that claims only to support RemedySSO with SSO Plugin. This service is available when SSO Plugin has been integrated with BMC Mid Tier or MyIT and uses the AR System database (by storing data within existing JSS forms). The endpoint is located at /jsssso/api/rsso, hence an example URL (to configure during application installation) is: Each BMC product that requires RemedySSO has been documented separately, ie BMC Atrium Orchestrator and BMC Discovery. Configuring the service Various configuration options exist within RemedySSO and have been replicated in the SSO Plugin reimplementation. One option (conf-cookie-domain) require immediate configuration. To do so, locate the rsso.properties file in the application WEB-INF/classes directory and open it in your favourite text editor. The conf-cookie-domain value must include the domain name in which your applications (ie Mid Tier & AO) run. For example, if a user types into a browser to access Atrium Orchestrator and the conf-cookie-domain must be set to.mycorp.com. You must include a full stop as the first character of the domain, ie.mycorp.com. Deploying the JSS rsso.war file BMC provide a RemedySSO agent, which is a Java module that communicates with the RemedySSO service. We discovered a design fault in the agent (version 9.0) which assumed RemedySSO was running under the path /rsso even if a different endpoint had been configured during the installation of the RemedySSO server, ie /apps/remedysso. This proved problematic when SSO Plugin s RemedySSO service was configured with Mid Tier, which traditionally uses the path /arsys, or MyIT, which uses the path /ux. To solve this problem, a small redirection application called rsso.war has been included in the SSO Plugin installation files. This must be deployed in the same Java webserver (ie Tomcat) as the Mid Tier or MyIT applicaton being used to provide the RemedySSO service. To do install the redirection application, follow these steps: 1. In the SSO Plugin installation files, locate the rsso.war file.

19 2. Copy the rsso.war file to the Tomcat webapps directory. 3. Start Tomcat and it will expand the rsso.war file into a directory called rsso. 4. In the rsso directory, locate the file urlrewrite.xml in the WEB-INF directory and open in your favourite text editor. 5. Locate the following line and configure the endpoint directly, ie enter /arsys or /ux for Mid Tier or MyIT respectfully or a custom path if one has been used. <to type="redirect">/arsys/jss-sso/api/rsso/$1</to>

20 Upgrades A separate document covers the process for upgrading 4.x to 5.x. When using current major release When the current release of SSO Plugin is already deployed, ie you have version installed and you wish to update to version 5.0.5, the following steps should be followed unless the CHANGELOG.txt file states differently: 1. Stop AR System. 2. Copy the jss-sso-area.jar file from the installation files into the AR System server pluginsvr directory. 3. Start AR System. 4. Stop Tomcat running Mid Tier. 5. Replace the Mid Tier files, ie copy the contents of the Mid Tier directory into the Mid Tier. 6. Delete the Tomcat 'work' directory, which is a temporary cache directory re-created when Tomcat starts. 7. Start Tomcat. Identity Federated Applications: BMC Analytics, Dashboards, etc. Copy the relevant jar files from the installation files to the third party application. For example, copy the jar files in Identity Federated Applications/businessobjects/WEB-INF/lib (from the installation files) to the relevant location in the Business Objects installation, as per the original deployment.

21 Uninstalling SSO Plugin To uninstall SSO Plugin, follow these steps: 1. Go to the SSO Plugin Mid Tier status page and click the disable Mid Tier button. Mid Tier will require restarting. 2. Delete the files copied from the installation set to the Mid Tier web application directory. If you are going to upgrade SSO Plugin, this can be skipped as the new files will overwrite the old files. 3. Delete the jss-sso-area.jar file from the AR System server pluginsvr directory. 4. Remove the JSS workflow (forms, active links and filters) prefixed with JSS. 5. Restart both AR System and Mid Tier.