Transcription
SSO PluginInstallation for BMC Digital Workplace , DigitalWorkplace Catalog and SmartITFormerly known as MyIT and MyIT Service BrokerJ System Solutionshttps://www.javasystemsolutions.com
Introduction. 3Overview . 3FAQ . 3Implementation checklist . 4Compatibility & prerequisites . 5Application compatibility . 5Prerequisite for SSO Plugin . 5Minimum version . 5BMC AR System and ITSM . 5Licenses . 5Verify a working environment with an existing account . 6Deploying SSO Plugin to BMC Digital Workplace (DWP & SmartIT) . 7Installation . 7Configuring the SSO Plugin integration . 9Testing the SSO Plugin integration . 11Enabling logs and their locations . 12Manual login . 13Deploying SSO Plugin to BMC Digital Workplace Catalog (Service Broker) . 14Proxy configuration . 14Configure the Tenant and Cookie Domain YAML File on DWP (MyIT) . 14URL of the SSO Plugin RSSO service . 14DWPC Tenant . 14Cookie Domains . 15Configuring DWPC for SSO . 15Troubleshooting and log files . 17SSO fails after running user group sync.sh . 17http://www.javasystemsolutions.com
Page 3 of 17IntroductionThis document covers: Compatibility matrix and other introductory material for SSO Plugin. Installation and configuration of SSO Plugin for BMC Digital Workplace (formerly known asMyIT) SmartIT and BMC Digital Workplace Catalogue (formally known as MyIT ServiceBroker).If there are any further questions or queries not found within this document, please feel free tocontact JSS Support via support@javasystemsolutions.com. Additional material can be found on oursupport website.In August 2018, BMC split the Digital Workplace and SmartIT into two separate installations and webapplications.The installation procedure of SSO Plugin for both products are identical and this document assumesthat wherever the steps are uncommon e.g. installation paths, it will show examples. Otherwise theremaining tasks are the same for both BMC products.The document will reference Digital Workplace as DWP; SmartIT as SmartIT and DWPC for DigitalWorkplace Catalogue.OverviewSingle Sign On (SSO) for Digital Workspace is very simple to deploy and configure. It requires noadditional software or hardware like other applications. SSO Plugin is just a few files that aredeployed within the same Tomcat instance and is then configured via a new web page. It's extremelylightweight, easy to install and configure.The installation only takes a few minutes. It does require Tomcat to be restarted and thereforebecomes the task that takes the most amount of time.An installation video can be found deo#installations.SSOPlugin-DWPFrom a design and usability standpoint, the same easy to configure screens you may be familiar withif you have deployed SSO Plugin for the BMC Mid Tier are used.If you are not happy with the product, the status screen provided a button to disable and therefore arestart of Tomcat will restore the configuration back to the state before the SSO Plugin installation.FAQ What are the minimum versions of SSO Plugin and BMC Digital Workplace required for thisimplementation?o DWP 20.x, 19.x ,18.0x, 3.5, 3.4, 3.3 - Minimum SSO Plugin 5.1.28o DWPC 20.x, 19.x ,18.0x, 3.5, 3.4, 3.3 - Minimum SSO Plugin 5.1.28o Smart IT 20.x, 19.0x ,18.08, 18.05, 2.0 - Minimum SSO Plugin 5.1.28What changes will be made to my existing environment?o SSO Plugin installation files will be copied to the /dwp or /smartit folder and will alsomake a change to the web.xmlWhat differences to BMC Remedy SSO are there?o SSO Plugin provides all the same functionality as RemedySSO as a minimum. Inaddition, it has a multitude of extra features it doesn't. For example, dynamic username translation using SQL or Javascript for customers with domain names that donot match the login name; ITSM registration or raise an incident when the userdoesn't exist.http://www.javasystemsolutions.com
Page 4 of 17 Is there a non-SSO / manual fall back login?o Yes, when accessing via DWP.o No JSS components are required for DWPC because we use the RSSO API, and theRSSO API does not support a manual login.Implementation checklistHere is a checklist that can be followed to implement SSO Plugin for BMC Digital Workplace Verify compatibility versions for SSO Plugin and BMC Digital Workplace. Verify that BMC Digital Workplace works by logging in manually before starting theinstallation.http://www.javasystemsolutions.com
Page 5 of 17Compatibility & prerequisitesApplication compatibilityWe always recommend the latest version on the JSS site however, the following table shows theminimum tested versions.BMC ProductMinimum SSO Plugin VersionDWP, 20.x, 19.xSSO Plugin 5.1.28DWPC 20.x, 19.xSmart IT 20.x, 19.xDWP 18.0x, 3.5, 3.4, 3.3SSO Plugin 5.1.24Smart IT 18.x, 2.0DWP 3.2, 3.1, 3.0, 2.6SSO Plugin 5.0.8Smart IT 1.6Prerequisite for SSO PluginMinimum versionThe above table shows the minimum SSO Plugin versions for the various BMC product versions.If you are using SSO Plugin version 4.x and you are using AR System less than 9.x then please useSSO Plugin 5.0 which can be found BMC AR System and ITSMDWP and SmartIT require BMC Remedy IT Service Management (ITSM) be installed and configured.Therefore to SSO Plugin needs to be installed and licensed within this environment as a prerequisiteto this installation.Here are two short installation videos BMC AR Systemo nstallations.SSOPluginInstallation50-ARSBMC Mid esJSS do not charge additional licenses for DWP and SmartIT; licenses are charged per AR Systemproduction server to which these products connect.http://www.javasystemsolutions.com
Page 6 of 17Verify a working environment with an existing accountThe error messages from BMC Digital Workplace are often not clear & concise. Therefore, by ensuringthe current logged on user can utilise the application saves time.http://www.javasystemsolutions.com
Page 7 of 17Deploying SSO Plugin to BMC Digital Workplace (DWP &SmartIT)This deployment process is similar to the one followed when deploying SSO Plugin to BMC Mid Tier, ieSSO Plugin is copied into DWP or SmartIT and configured via a web interface.InstallationIf you do not have an account with JSS then you will need to fill out the online Request forEvaluation.This will create an account and email your login and password to download SSO Plugin 5.1 from ourwebsite.If you already have an account or you have received your login name and password after submittingthe evaluation form above, proceed to the download section of our site and click on SSO Plugin SSO Plugin 5.1 SSO Plugin for BMC Products SSO Plugin for BMC ProductsExample screenshotTo install the product, follow these steps:http://www.javasystemsolutions.com
Page 8 of 171. Copy the zip to the BMC Digital Workplace Basic instance and unzip. Here is a screenshot ofthe directory structure:2. Shutdown the SmartIT/DWP Application service and delete any existing logs.3. Copy the contents of the "3 – DWP and SmartIT\dwp" directory to the app directory.a. C:\Program Files\BMC Software\DWP\DWP\dwpb. C:\Program Files\BMC Software\Smart IT\Smart IT\smartithttp://www.javasystemsolutions.com
Page 9 of 174. Start the Smart IT/DWP Application service.5. After the service has restarted, open a browser and point to your DWP/SmartIT instance withthe following SSO Plugin configuration URL:http(s)://host:port/dwp/jss-sso/setup.jspYou should see the following screen:6. Restart the Smart IT/DWP Application service.7. After the service has restarted, open a browser and point to your DWP/SmartIT instance withthe following SSO Plugin configuration URL:http(s)://host:port/dwp/jss-sso/index.jspYou should see the following interface:Notice at this point, SSO Plugin requires configuring.Configuring the SSO Plugin integrationWhile presented with the above screen, to configure an SSO integration, login on the top right withthe default password jss and use the interface as documented in the configuring an SSO integrationdocument.From the menu bar at the top, select Settings Integrations.If the instance is installed on Windows and in the same domain as your users, then the fastestintegration is Windows Authentication. Select NTLM from the Protocols menu and make sure theWindows native NTLM radio button is selected. Then click the Set Configuration button below.Notice a message appear confirming the changes and prompting the restart of the SmartIT/DWPApplication service.http://www.javasystemsolutions.com
Page 10 of 17Example screenshot of Integration link showing the default Windows authentication method:http://www.javasystemsolutions.com
Page 11 of 17Upon restart, the status of the SSO integration can be viewed on the SSO Plugin status page:Testing the SSO Plugin integrationSSO Plugin provides a consistent URL for testing the SSO integration, in order to report informationfor troubleshooting purposes. The link is as follows:http(s)://host:port/dwp/jss-sso/testssoAnd the interface is shown below:http://www.javasystemsolutions.com
Page 12 of 17Enabling logs and their locationsBrowse to the SSO Plugin configuration page on the specific tomcat instance. For example:BMC ProductSSO Plugin Configuration URLDWPhttp://host:port/dwp/jss-sso/index.jspSmart IThttp://host:port/smartit/jss-sso/index.jspLogin on the top right with the default password of jssThen click on Settings GlobalSet the desired log level, for JSS Support, please set this to trace.The following files contain SSO Plugin log information:BMC ProductSSO Plugin log informationDWPC:\Program Files\BMC Software\DWP\DWP\Logs\dwptomcatstdout. date .logSmart ITC:\Program Files\BMCSoftware\Smart IT\Smart IT\Logs\smartittomcat8stdout. date .loghttp://www.javasystemsolutions.com
Page 13 of 17Manual loginSSO Plugin provides a manual login page for those users who wish to login manually, or can not loginthrough SSO. The links are as follows: DWP: http(s)://host:port/dwp/jss-sso/manuallogin SmartIT: http(s)://host:port/smartit/jss-sso/manualloginAnd the interface is shown below:http://www.javasystemsolutions.com
Page 14 of 17Deploying SSO Plugin to BMC Digital Workplace Catalog(Service Broker)The BMC Digital Workplace Catalog component can be configured with SSO Plugin using the BMCRSSO API, but this model is only supported when SSO Plugin has been installed with BMC DigitalWorkplace (DWP). Please complete and test the installation for DWP before proceeding toDWPC.Proxy configurationIf you are using a front end web proxy, the proxy requires configuration to set the URL that usersenter into a browser as a pair of HTTP Headers that will be forwarded to DWPC. This is a prerequisite for the RSSO API agent.Without these values set, the RSSO API agent will use the internal URL (for the DWPC instance) whencommencing the authentication process through browser redirection to what it believes is an RSSOinstance, passing the wrong “return URL”. This is BMC design, and nothing to do with SSO Plugin.The HTTP headers that require setting are X-Forwarded-Proto and X-Forwarded-Host. For example, ifyour user facing URL to the load balancer is https://dwp.mycompany.com then set: X-Forwarded-Proto https X-Forwarded-Host dwp.mycompany.comConfigure the Tenant and Cookie Domain YAML File on DWP (MyIT)The RSSO agent within DWPC requires a tenant. And currently this is stored within a rsso.yaml file onthe DWP server.Shutdown DWP and open the following file in your favourite text editor (default installation paths): Windows : c:\Program Files\BMC Software\DWP\dwp\WEB-INF\Classes Linux : /opt/bmc/DWP1911/DWP/dwp/WEB-INF/classesThis requires a minimum of three configuration changes to match the customers implementation.URL of the SSO Plugin RSSO serviceThis is the service endpoint that is published to all clients. And requires that the schema (https orhttp), host and port be that of your DWP(MyIT) server or load balancer that is in front of you DWPinstances. This endpoint is used both from the browser and directly from the DWP Catalog server(s).Example:ssoServiceUrl: http(s)://host:port/dwp/jss-sso/api/rssoDWPC TenantUpton installing BMC DWP Catalog (DWPC) you are asked to install a tenant. This value is required inthe rsso.yaml fileExample:tenant: bmc.comhttp://www.javasystemsolutions.com
Page 15 of 17Cookie DomainsSSO Plugin requires the domain name of the URL that users will enter to connect to the DWP Cataloginstance. Replace the cookie domain with what your users will type in the browser. E.g. If your DWPCatalog URL is http://dwpc.bmc.com:8008/myitsbe Then the cookie domain is bmc.com.Example:cookieDomains:- bmc.comSave the rsso.yaml file and start DWP (MyIT). Once it has fully started, it is important that thefollowing test if verified before continuing. From the DWP Catalog (DWPC) Linux terminal, check thatcurl is installed. If not then use the following to install:yum install -y curlThen use the following command:curl -vk heck/consumer/config(replace scheme http(s), host and port)A successful test will have both of the following: HTTP/1.1 200And a JSON configuration. Example:{"oauth2 access token ttl":3600,"features":[],"oauth2 refresh token ttl":5184000,"mapping realms apps":{"*":["*"]},"cookie https only":false,"cookie domain":"bmc.com","last modified date":1585479207,"mapping tenants apps":{"*":"bmc.com"},"max session time":1800,"server version":"19.08.00","cookie name":"sso 12345"}If the HTTP response is not 200, or you do not see the above, you must ask the administrator toensure clients can access the following URL (and sub-URLs) without needing to authenticate withyour corporate SSO ring DWPC for SSOStart by verifying that SSO Plugin is working on DWP. This can be achieved by browsing to DWP andbeing logged in. Or you can enter the following into a browser and looking for"ssopluginEnabled":true, ie: tatus1. Make sure the BMC AR SERVER HOME environment variable is setcat /.bmc profilecat /.bmc profileBMC AR SERVER HOME "/opt/bmc/digitalworkplace"BMC AR SYSTEM HOME "/opt/bmc/digitalworkplace"export BMC AR SERVER HOMEexport BMC AR SYSTEM HOMEhttp://www.javasystemsolutions.com
Page 16 of 17echo BMC AR SERVER HOME/opt/bmc/digitalworkplace2. Run configure rsso.sh to setup the SSO Agentcd /opt/bmc/digitalworkplace/sb/configure rsso/./configure rsso.shThe SSO External URL is the URL on which a user connects via a browser, which may be thehostname of a reverse proxying load balancer in your environment. You then add /dwp/jsssso/api/rsso, ie http:// your-dwp :port/dwp/jss-sso/api/rsso.The SSO Service URL is the URL that your DWPC instance will connect to the DWPC, typicallyan internal hostname either via a load balancer or direct to the DWP host. Again, add/dwp/jss-sso/api/rsso. Verify that this URL works by using a tool such as curl from the hostrunning DWPC.Depending on the complexity of your installation, typically when there is no load balancerfronting the DWP instance, the Service and External URLs will be the same. Butunderstanding which URLs to use for the Service and External URLs can be complicated, soplease contact JSS Support for advice if you are unsure.When asked for the options, here is an example of what needs to be entered:Enter agent id: agent-dwpcatalogEnter SSO External URL: http://dwp.mycompany.com/dwp/jss-sso/api/rssoEnter SSO Service URL: http://dwp.internal/dwp/jss-sso/api/rssoEnter Tenant domain set in SSO Realm configuration: calbro.localEnter the BMC Digital Workplace Catalog system administrator login name:dwpadminPassword for BMC Digital Workplace Catalog system administrator: Passw0rd!Enter Tenant administrator login name: hannah admin@calbro.localPassword for Tenant administrator: Passw0rd!3. Stop the DWPC instance. Example below./dwpcontroller -u dwpadmin -p Passw0rd! stop4. Typically for DWPC pre-20.02, when the configure rsso.sh script has not been used:a. Copy the rsso-agent.properties and rsso.cfg from our download tothe %dwpcInstalledDirectory%/conf.b. Edit the s1. Locate the line sso-external-url and sso-service-url and edit as described above:sso-external-url http:// your-sso-enabled-dwp : port /dwp/jss-sso/api/rssosso-service-url http:// dwp.internal : port /dwp/jss-sso/api/rssob. Edit the %dwpcInstalledDirectory%/conf/rsso.cfg1. Locate the line sso-service-url and edit as described above:sso-service-url http:// dwp.internal : port /dwp/jss-sso/api/rssoc.Copy the rsso-agent-osgi.jar file from the BMC RemedySSO download that matchesyour AR server version, ie from o-agent-osgi.jar to %dwpcInstalledDirectory%/deploy.5. Verify, update the /opt/bmc/DWP/DWP/dwp/WEB-INF/classes/rsso.yaml file as follows:a. ssoServiceUrl: https:// dwp.internal : port /dwp/jss-sso/api/rssob. tenant: as set when running configure rsso.sh, ie calbro.local.http://www.javasystemsolutions.com
Page 17 of 17c.cookieDomains: Add the sub domain on which both DWP and DWPC are accessed via abrowser. Typically, this is your company’s internal domain name, ie mycompay.com6. After restarting DWP, check the values by browsing to the following URL and reviewing theJSON output:https://your-sso-enabled-dwp: port igThe JSON document will look similar to this:{"oauth2 access token ttl":3600,"features":[],"oauth2 refresh token ttl":5184000,"mapping realms apps":{"*":["*"]},"cookie https only":false,"cookie domain":"calbro.local","last modified date":1581527703,"mapping tenants apps":{"*":"calbro.local"},"max session time":1800,"server version":"19.08.00","cookie name":"sso 12345"}7. Start the DWPC Server:dwpcontroller -u dwpadmin -p Passw0rd! startTroubleshooting and log filesIf you are troubleshooting DWPC, BMC’s documentation explains how to enable RSSO logging.After enabling the RSSO logging, carry out the following steps to collect log files and send them toJSS Support:1. Verify the user can browse to DWP and is authenticated via SSO2. Shutdown DWP and DWPC.3. Delete old log files from the DWP directories:a. /opt/bmc/DWP/DWP/Logsb. /opt/apache/tomcat8.5/logs4. Delete old log files in the system and tenant db directory from DWP, ie.a. /opt/bmc/digitalworkplace/dbb. /opt/bmc/digitalworkplace / TENANT /db or/opt/bmc/digitalworkplace/tenant/ TENANT /db5. Start DWPC and test by accessing DWPC directly, ideally using the desktop web debuggerFiddler to collect a trace which should be exported as a .saz file.6. Shutdown DWP and DWPC.7. Collect all of the log files from the directories detailed above in steps 3 and 4, along with theFiddler trace and rsso.yaml, and email to support@javasystemsolutions.com.SSO fails after running user group sync.shIt has been observed that following the BMC instructions to run the following script:/opt/bmc/digitalworkplace/artools/user group sync.shIt will disable the DWPC setting “Cross Reference Blank Password” which is required for SSO. Andtherefore, if you find SSO doesn’t work after running the BMC scripts, login to the application andconfirm that checkbox is enabled.http://www.javasystemsolutions.com
Deploying SSO Plugin to BMC Digital Workplace (DWP & SmartIT) This deployment process is similar to the one followed when deploying SSO Plugin to BMC Mid Tier, ie SSO Plugin is copied into DWP or SmartIT and configured via a web interface. Installation If you do not have an account with JSS then you will need to fill out the online Request for
