I won’t get into a lengthy discussion about why you should use SSL to secure browser traffic. I’ll simply offer that your Maximo environment, especially if the environment can be accessed over the public internet, should be secured. Here are a few reasons:
SSL Encrypts Sensitive Information
SSL Provides Trust and Authentication
SSL Can Provide Compliance in certain Industries
The disadvantages are that it costs money to obtain and verify a certificate from a Certificate Authority, and it takes some time to configure. Hopefully, this blog post will help to reduce the amount of time necessary to configure SSL with Maximo.
Please note that you can also create a self-signed certificate which will suffice in forcing the browser traffic to be encrypted. However, users will see that the certificate is not trusted in the browser, and it might lead them to ask questions or not trust the connection.
This article will take you through setting up Maximo with SSL through a GoDaddy SSL Certificate, which is currently ranging anywhere from $50.00 to $300.00 annually based on the level of encryption, features, and number of sub-domains you want to secure. We will use the most basic single-domain option for this exercise.
Step 1: Create a Key Database and Generate a new Certificate Signing Request
Run the IBM Key Management Utility
Sign on to the server where the IBM HTTP Server is installed as an administrator.
Run the IBM Key Management Utility program from your Start Menu > IBM HTTP Server V8.5
Create a Key Database
Create a new Key Database File. This file will hold your private keys and must be kept secure:
Key database type: CMS
File Name: maximo.kdb
Location: C:\IBM\HTTPServer\ (provide an appropriate path for your system)
Click OK
Secure the Key Database
You will be prompted for a password to secure your new key database:
Enter a password
Confirm the password
Check the Stash password to a file checkbox
Click OK
Create a New Certificate Signing Request
Create a New Certificate Request from the menu options. This request, also known as a Certificate Signing Request (CSR), is what will be sent to the Certificate Authority for verification. With the information provided in the request, the CA will do their homework on you to make sure you are who you say you are, including possibly attempting to contact you or your business by email or phone. It’s important that this information is as accurate as possible:
Key Label: MAX_SSL_KEY
Key Size: 2048
Common Name: www.mycompany.com (this is the host name that you want to secure and must be correct!)
Organization: My Company Inc
Locality: Your city
State/Province: Your state
Zipcode: Your zip
Country or region: Your country
Email Address: admin@mycompany.com
Enter the file name: C:\IBM\HTTPServer\maximo.arm
Click OK. We’re going to leave the IBM Key Management Utility open for now. We’ll come back to it later.
Step 2: Purchase an SSL Certificate, Upload the CSR, and Download the Certificate
Purchase an SSL Certificate
Navigate to the SSL Certificate page on the GoDaddy website and purchase an SSL Certificate (sorry, no step-by-step here!).
Request an SSL certificate
After you purchase an SSL certificate, you need to request it for the website’s domain name (or “common name”) you want to use.
Activate your credit
Log in to your GoDaddy account.
Click SSL Certificates.
Next to the SSL certificate credit you want to use, click Set up.
If you have multiple credits, select the credit you want to use, and then click Set up.
Refresh the page; you should see a New Certificate. If you don’t, continue to refresh the page until you do.
Request your certificate
Next to your New Certificate, click Manage.
Select Provide a CSR, and then enter the CSR from your server. Back on the server where the IBM HTTP Server is installed, open the C:\IBM\HTTPServer\maximo.arm file in your favorite text editor. Copy its contents. This is your Certificate Signing Request (CSR).
Click Request Certificate.
Verification Process
GoDaddy will verify your certificate request. How long this takes depends on the type of certificate (typically between 1 and 7 days). Once we have that certificate we can continue with the process. Until then, we wait.
Download the Certificate
After GoDaddy approves your SSL certificate request, you can download your primary and intermediate certificate from within the SSL application on the GoDaddy website.
On your SSL certificate home page, click Download.
Select the Apache server type.
Click Download ZIP file.
Copy the Certificate to your IBM HTTP Server
Copy the ZIP file to the C:\IBM\HTTPServer\ folder on the server where the IBM HTTP Server is installed.
Extract the contents of the ZIP file to the C:\IBM\HTTPServer\ folder.
Note that there should be two files: one that represents your certificate, and one that represents GoDaddy’s intermediate certificate. You will need both to install the certificate in the next step.
Step 3: Install the Certificate
Run the IBM Key Management Utility
Sign on to the server where the IBM HTTP Server is installed as an administrator.
Run the IBM Key Management Utility program from your Start Menu > IBM HTTP Server V8.5
Open your maximo.kdb key database created earlier, using the password you created earlier to unlock the key database.
Install the Intermediate Certificate
Change the Key database content drop-down to Signer Certificates.
Click the Add… button
Choose the intermediate certificate file that you extracted in the previous step. Please note that the file name is likely to be of the nature gd_bundle_*.crt, and that the CRT file extension is not in the default list in the Key Management Utility file browser. Simply change the file extension drop-down to All Files or paste the exact file name into the window.
Click OK
You should see the intermediate GoDaddy certificates listed.
Install the Certificate
Change the Key database content drop-down to Personal Certificates.
You should see the MAX_SSL_KEY record that was created earlier when we created our CSR. Highlight that record. Note that the * in front of the MAX_SSL_KEY record indicates it is the default key.
Press the Receive button.
Choose the certificate file that you extracted in the previous step. Please note that the file name is likely to be some has sequence with a file extension of .crt, and that the CRT file extension is not in the default list in the Key Management Utility file browser. Simply change the file extension drop-down to All Files or paste the exact file name into the window.
Click OK
If all goes well you should see a Validation Successful message in the Key Management Utility! This means that your key database is now validated with a signed certificate from a Certificate Authority (GoDaddy). We’re almost done!
Step 4: Update the HTTP Server, WebSphere, and Maximo
Update the IBM HTTP Server
Sign on to the server where the IBM HTTP Server is installed as an administrator.
Edit the C:\IBM\HTTPServer\conf\httpd.conf file. Please note that the directory path may be different based upon your installation (e.g. C:\Program Files\IBM\HTTPServer\).
Log into the IBM WebSphere Console as an administrator.
Navigate to Environment > Virtual Hosts.
Click on the maximo_host Virtual Host.
Click on Host Aliases under Additional Properties.
Click on the New… button.
Add the host name that you used for the Common Name (e.g. www.mycompany.com) in your certificate request as the Host Name. Specify 443 as the Port.
Click OK and save the configuration to the Master File.
Restart your IBM WebSphere Windows Services (Cell Manager and Node Agent).
Update your Maximo System Properties
At this point, you should be able to access Maximo over SSL (HTTPS). There are just a few System Properties that should be updated in order to have everything buttoned up.
Log into Maximo as an administrator.
Navigate to the System Configuration > Platform Configuration > System Properties application.
Update the following properties, which should just involve changing the existing property value to change the http:// to https://
mxe.doclink.path01: This is for attached documents.
mxe.help.protocol: This is for application help. Please note that in 7.6.0.4 the help is now pointing to IBM’s website. In either case, the property value should be changed to https.
mxe.int.webappurl: This is for Integration Framework web service and HTTP calls.
mxe.oslc.restwebappurl: This is for OSLC calls through the REST interface.
mxe.oslc.webappurl: This is for OSLC calls through the standard interface.
That’s it! I hope this has been helpful. Please feel free to leave feedback in the comments section below.
Alex Walter is the Chief Innovation Officer at the A3J Group, a company he formed to address the need for innovative software solutions and integrated consulting services within the EAM industry. Alex brings 17 plus years of experience in business consulting in various industries including Life Sciences, Oil and Gas, Water and Waste Management, Education, Government Facilities, among others.
Alex lives in Tampa, FL with his wife, two sons, and dogs. In his free time, he enjoys running half marathons, making space in his garage for new camping and outdoor equipment, traveling to far off places with the Walter Circus, and remaining hopeful that his NY Jets' best days are ahead of them and not behind.
22 Thoughts on “Maximo SSL (HTTPS) Configuration”
Great article, very concise and informative. Do you have any further steps in order to only allow TLS 1.2 as the transport protocolo on SSL?
Your article is quite good. Do you think it is advisable in this situation to configure access such that ssl is the only/mandatory connection available?
If you have a BIRT Reporting Only Server (BROS), you can secure that environment in a similar fashion. Then update your mxe.report.birt.viewerurl System Property to use the HTTPS protocol.
You’re welcome! For a clustered environment, the key is securing the load balancer URL and then ensuring that the Virtual Hosts are configured properly. You do not need certificates for each host within the cluster. You simply need to establish trust with the load balancer.
Yes, a wildcard certificate can be used with Maximo. Most of the SSL certificate providers will provide a way to specify your list of sub-domains for wildcard certificates. Other than providing the Maximo sub-domain to the provider, the steps should be very similar to what’s been listed in the article.
A certificate is usually only valid for a given domain name. In other words, you will need two certificates – one for maximo.xyz.ca and one for maxrep.xyz.ca. The exception is that some providers offer wildcard certificates, where one certificate can match *.xyz.ca.
In your case you will need two certificates or one wildcard certificate to secure both maximo.xyz.ca and maxrep.xyz.ca. The setup above can be followed for both JVMs. Good luck!
I am able to get around the invalid certificate problem by deploying the BROS EAR to a webserver running on the same VM as BROS JVM. But this approach then allows users to login to maximo using the maxrep.xyz.ca url as well which I dont want to happen.
Have you thought about playing with how to setup SSL with Maximo linked to Cloudfare???
trying to follow your above post and figure out where the PEM file and Private Key I get from Cloudfare would come in on setting up the Origin CA server (Maximo).
This article talks about the IBM HTTP Server. How is this different than generating a certificate for WebSphere itself and under what conditions do you do one vs. the other?
When WebSphere is installed by the IBM Maximo Configuration Utilitiy, it creates a Web Server and an App Server. But Maximo runs fine with just an App Server. Is a Web Server needed to secure Maximo through SSL?
Dear Julio – Thanks for your comment. This was exactly my concern as well. I believe our Linux admin already installed a self-signed cert for WebSphere although Maximo runs on HTTP. Although our situation is slightly different, your situation is very helpful in coordinating with both IBM Maximo support and IBM WebSphere support it seems.
Your article helped me get SSL working when accessing Maximo through the IBM HTTP Server. I was still getting “Not Secure” messages when accessing Maximo directly or accessing the WebSphere Console but IBM Support walked me through how to import the SSL certificates into WebSphere itself.
One issue I found was with the Help application. I found that if mxe.help.protocol is changed to “https” then mxe.help.port needs to be changed from “80” to “443” to avoid errors when opening the IBM Knowledge Center.
MxApprove End User License Agreement
If you agree to the terms of this MxApprove End User License Agreement (the “License Agreement”), click the Accept License Agreement button after reviewing the contents of this License Agreement to proceed with accessing the MxApprove (the “Application”). IF YOU DO NOT AGREE TO THE TERMS OF THE THIS LICENSE AGREEMENT, YOU WILL NOT HAVE ACCESS TO THE APPLICATION.
This is a license agreement between you, as the licensee and A3J Group LLC, a Delaware limited liability company, (“A3J”), its successors and assigns, its affiliated companies, and its authorized distributors and resellers as the licensor. This is not a contract for sale of the Application, but a license to use the Application subject to the terms and conditions of this License Agreement. Please read the terms carefully. You and A3J agree as follows:
Application.
The Application is the property of A3J. The term Application includes any related documentation, updates and permitted copies of the Application licensed to you by A3J. A3J expressly reserves all rights not expressly granted you.
Scope of License.
Upon your acceptance of the terms contained in this License Agreement, A3J grants you a nonexclusive, nontransferable, limited right to use the Application for personal or business use on the Licensed Devices, as defined below. The term "Use" means to install and access the Application in conjunction with the Application’s related and compatible software.
“Primary Device” shall mean the mobile device, tablet or other device compatible with applications owned or controlled by you, on which you download and install the Application and agree to be bound by the terms of this License Agreement and any other agreement associated with the Application. “Licensed Devices” shall mean the Primary Device and any other device that synchs or otherwise shares the same cloud or backup identification as the Primary Device.
This License Agreement does not allow you to use the Application on any device that you do not own or control. You may not distribute or make the Application available over a network where it could be used by multiple devices at the same time. You may not rent, lease, lend, sell, redistribute or sublicense the Application. You may not assign any right granted under this License Agreement without A3J’s prior written consent. You may not copy the Application. YOU AGREE THAT YOU WILL NOT MODIFY, ADAPT, TRANSLATE, ALTER NOR CREATE DERIVATIVE WORKS OF THE APPLICATION. YOU FURTHER AGREE THAT YOU WILL NOT REVERSE ENGINEER, DECOMPILE, DECRYPT, DISASSEMBLE, NOR SEEK TO DISCOVER THE SOURCE CODE OF THE APPLICATION OR ANY UPDATES ASSOCIATED THEREWITH. IF THE APPLICATION CONTAINS EMBEDDING BITS THAT LIMIT THE CAPABILITIES OF THE APPLICATION, YOU MAY NOT CHANGE OR ALTER THE EMBEDDING BITS.
Embedding of the Application is prohibited. You may NOT otherwise embed the Application. For example and without limitation: (i) You may NOT embed the Application into your hardware, software or other products, such as, application programs, electronic games, e-books, kiosks, printers, etc.; (ii) You may NOT embed the Application into your web pages; and (iii) You may NOT embed the Application into electronic commercial documents. This means that the Application may not be embedded or otherwise used in non-static files that may be accessed by computers or other devices that are NOT Licensed Devices.
A breach of these restrictions may subject you to prosecution and damages, including but not limited equitable relief in the form of an injunction.
Any updates or supplements to the Application will be governed by this License Agreement, unless a separate license agreement accompanies the update or supplement.
Intellectual Property Rights.
The Application, and any trademark, copyrights, patents, or any rights associated with the same, are the intellectual property of A3J. A3J reserves all of its rights under applicable laws. You acknowledge that the structure, organization and code of the Application are valuable trade secrets and confidential information of A3J and you shall not use this proprietary content, information or materials in any way except as expressly permitted under this License Agreement.
No Other Use.
You are granted only the rights expressly stated in this Agreement, and you may not use the Application for any other use or purpose. In addition to other prohibited uses described in this Agreement and without limitation, the following uses are specifically prohibited: (i) You may not share the Application with other individuals or business entities; (ii) You may not use the Application on more than the permitted Licensed Devices; (iii) You may not change the name of the Application; (iv) You may not translate the Application into other platforms.
Consent to Use Data.
A3J may collect and use technical data and related information, including but not limited to technical information about your device, system and application software gathered periodically to facilitate the provision of software updates, product support and other services related to the Application. A3J may use this information, provided this use does not personally identify you, to modify or further develop the Application and/or provide additional technologies to you.
Termination.
The license rights granted under this License Agreement are effective until terminated by you or A3J. Your rights under this License Agreement will terminate automatically without notice from A3J if you fail to comply with any of the term(s) of this License Agreement. Upon termination of the license, you shall cease all use of the Application, and destroy all copies, if any, full or partial, of the Application.
No Warranty.
YOU EXPRESSLY ACKNOWLEDGE AND AGREE THAT USE OF THE LICENSED APPLICATION IS AT YOUR SOLE RISK. TO THE EXTENT PERMITTED BY LAW, THE APPLICATION IS PROVIDED “AS-IS” AND “AS AVAILABLE,” WITH ALL FAULTS AND WITHOUT WARRANTY OF ANY KIND. A3J DOES NOT AND CANNOT WARRANT THE PERFORMANCE OR RESULTS YOU MAY OBTAIN BY USING THE APPLICATION. A3J MAKES NO WARRANTIES, CONDITIONS, REPRESENTATIONS OR TERMS, EXPRESS OR IMPLIED, WHETHER BY STATUTE, COMMON LAW, CUSTOM, USAGE OR OTHERWISE AS TO OTHER MATTERS, INCLUDING WITHOUT LIMITATION, NON INFRINGEMENT OF THIRD PARTY RIGHTS, TITLE, INTEGRATION, SATISFACTORY QUALITY, MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. FURTHER, A3J MAKES NO WARRANTIES AGAINST INTERFERENCE WITH YOUR ENJOYMENT OF THE APPLICATION OR THAT THE APPLICATION WILL MEET YOUR REQUIREMENTS, THAT THE OPERATION AND USE OF THE APPLICATION WILL BE UNINTERRUPTED OR ERROR-FREE OR THAT DEFECTS IN THE APPLICATION WILL BE CORRECTED. IN THE EVENT THE APPLICATION PROVES DEFECTIVE, YOU ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES OR LIMITATIONS PLACED ON STATUTORY RIGHTS, SO THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU.
Damage Limitations.
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT SHALL A3J BE LIABLE FOR PERSONAL INJURY, OR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES WHATSOEVER, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, LOSS OF DATA, BUSINESS INTERRUPTION OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES, ARISING OUT OF OR RELATED TO YOUR USE OR INABILITY TO USE THE APPLICATION, HOWEVER CAUSED, REGARDLESS OF THE THEORY OF LIABILITY (CONTRACT, TORT OR OTHERWISE) AND EVEN IF A3J HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. In no event shall A3J’s cumulative liability for any loss or damage to you (other than as may be required by applicable law in cases involving personal injury) exceed the amount of fifty dollars (US$50.00). The foregoing limitations will apply even if the above-stated remedy fails of its essential purpose.
No Export or Re-Export.
You may not use or otherwise export or “re-export” the Application. Specifically, and without limitation, you may not export or re-export the Application into (a) U.S. embargoed countries or (b) to anyone on the U.S. Treasury Department’s list of Specially Designated Nationals or the U.S. Department of Commerce Denied Person’s List or Entity List. By downloading and installing the Application and agreeing to the terms of this License Agreement you represent and warrant that you are not located in such a country or a person or entity on any such list. You further warrant and represent that you will not use the Application for any purpose prohibited by the laws of the United States.
Governing Law.
This Agreement is governed by the laws of the State of Florida, United States of America, excluding conflict of laws provisions and excluding the United Nations Convention on Contracts for the International Sale of Goods. You expressly agree that any disputes related to this Agreement will be resolved in the Circuit Court of Hillsborough County, Florida, U.S.A., or the United States District Court for the Middle District of Florida, U.S.A. Both you and A3J consent to the personal jurisdiction and venue of those courts. If any part of this Agreement is found void and unenforceable the balance of the Agreement will remain valid and enforceable according to its terms.
This License Agreement represents the entire agreement between you and A3J in connection with its subject matter. This License Agreement may only be modified by A3J in a writing that expressly states that the writing is intended to modify this License Agreement.
Contacting A3J.
A3J has a mailing address of 3225 S. MacDill Avenue, Tampa, Florida 33629, U.S.A. All support requests, completed registrations and other inquiries should be sent via e-mail to info@a3jgroup.com.
Great article, very concise and informative. Do you have any further steps in order to only allow TLS 1.2 as the transport protocolo on SSL?
Thanks Harold. I haven’t had to enforce that limitation yet, but I found an article on IBM’s Developer website that explains how to ensure TLS 1.2 is used. Note that you need to be on WebSphere v8 in order to do this. https://developer.ibm.com/answers/questions/206952/how-do-i-configure-websphere-application-server-ss.html
Your article is quite good. Do you think it is advisable in this situation to configure access such that ssl is the only/mandatory connection available?
Thanks! Automatically routing users over to SSL is certainly advisable. Check out how to use the Apache Re-write module to do this with Maximo and WebSphere here: https://a3jgroup.com/securing-maximo-by-forcing-users-to-ssl-https/
Is there some way to encrypt the mxe.report.birt.viewer?
If you have a BIRT Reporting Only Server (BROS), you can secure that environment in a similar fashion. Then update your mxe.report.birt.viewerurl System Property to use the HTTPS protocol.
Hi Alex,
A Big Thank you for making this concise instructions. Are there any special considerations for Maximo clustered environment in enabling SSL?
You’re welcome! For a clustered environment, the key is securing the load balancer URL and then ensuring that the Virtual Hosts are configured properly. You do not need certificates for each host within the cluster. You simply need to establish trust with the load balancer.
Hi Alex,
Is it possible to use wildcard SSL certificate with Maximo?
Yes, a wildcard certificate can be used with Maximo. Most of the SSL certificate providers will provide a way to specify your list of sub-domains for wildcard certificates. Other than providing the Maximo sub-domain to the provider, the steps should be very similar to what’s been listed in the article.
Hi Alex, Thanks for sharing such a useful article.
Can you please help me with the below problem?
I am getting invalid certificate when running a BIRT report.
Maximo URL: https://maximo.xyz.ca/maximo
This URL is also added to the UICluster Virtual host with port 443
Reports birt viewer URL: https://maxrep.xyz.ca/maximo/report
This URL is added to the BROSCluster Virtual Host with port 443
The BROS application is mapped to the BROS JVM and webserver1.
Thanks!
A certificate is usually only valid for a given domain name. In other words, you will need two certificates – one for maximo.xyz.ca and one for maxrep.xyz.ca. The exception is that some providers offer wildcard certificates, where one certificate can match *.xyz.ca.
In your case you will need two certificates or one wildcard certificate to secure both maximo.xyz.ca and maxrep.xyz.ca. The setup above can be followed for both JVMs. Good luck!
Thanks for responding Alex!
We are using wildcard certificate i.e. *.xyz.ca.
I am able to get around the invalid certificate problem by deploying the BROS EAR to a webserver running on the same VM as BROS JVM. But this approach then allows users to login to maximo using the maxrep.xyz.ca url as well which I dont want to happen.
Any thoughts?
You might be able to use the
Location
directive to filter out the ability to navigate to the /maximo/ui path on the maxrep.xyz.ca domain: https://httpd.apache.org/docs/2.4/mod/core.html#locationHello,
we need to call a secure webservice from Maximo using publish channel. Do I have to import certs in websphere?
thanks
Yes, certs need to be imported into the trust store within WebSphere. Look for an article shortly on this topic!
Perfect thanks!
It took a little longer than expected, but the article about importing certificates into WebSphere’s trust store is now online.
Have you thought about playing with how to setup SSL with Maximo linked to Cloudfare???
trying to follow your above post and figure out where the PEM file and Private Key I get from Cloudfare would come in on setting up the Origin CA server (Maximo).
Just curious,
Miller
This article talks about the IBM HTTP Server. How is this different than generating a certificate for WebSphere itself and under what conditions do you do one vs. the other?
When WebSphere is installed by the IBM Maximo Configuration Utilitiy, it creates a Web Server and an App Server. But Maximo runs fine with just an App Server. Is a Web Server needed to secure Maximo through SSL?
Thank you.
Dear Julio – Thanks for your comment. This was exactly my concern as well. I believe our Linux admin already installed a self-signed cert for WebSphere although Maximo runs on HTTP. Although our situation is slightly different, your situation is very helpful in coordinating with both IBM Maximo support and IBM WebSphere support it seems.
Your article helped me get SSL working when accessing Maximo through the IBM HTTP Server. I was still getting “Not Secure” messages when accessing Maximo directly or accessing the WebSphere Console but IBM Support walked me through how to import the SSL certificates into WebSphere itself.
One issue I found was with the Help application. I found that if mxe.help.protocol is changed to “https” then mxe.help.port needs to be changed from “80” to “443” to avoid errors when opening the IBM Knowledge Center.
Thank you.