Technical Blog Post
Abstract
Deploying Maximo Work Centers (LDAP and non-LDAP)
Body
With the release of 7.6.0.8 and allowing Work Centers to now work, with LDAP and security-enabled environments, I wanted to make a document that would allow those who are new to the concept of work centers. This gives a good idea of the process, what could go wrong, and step-by-step how to configure the Maximo work centers in your current environment. I won't go into what work centers are available, for information on role-based interfaces I would recommend you check out the documentation for the features, looks and functionality of Work Centers.
There are several options to deploy Work Centers. I try to go over all of them and give recommendations on the best way to approach deploying for what fits your needs. Since there are extra steps for LDAP, I label those steps as we go through, and when you are deploying for non-LDAP, you want to skip those steps.
Work Centers are deployed that use the Maximo-x war that is part of base Maximo, so if you see a reference to Maximo-x that is what it means.
Microsoft Internet Explorer is not supported by Work Centers. Use Edge, Chrome, or Firefox when connecting to Work Centers. You can refer to the compatibility matrix for details.
- Work Centers are only available in Maximo 7.6.0.5 and later.
- Work Centers with LDAP are only available in Maximo 7.6.0.8 and later.
Overview:
- Maximo-x Login form
- Maximo Login form
- Maximo CORS login (When the Maximo-x war is deployed in a separate server or cluster as the Maximo UI)
Changes to make before deploying
- web.xml changes
- config.json changes
Building and Deploying maximo-x.war
- Building the Maximo-x war
- To the same cluster as UI
- To a separate cluster from the UI
Properties to change in Maximo
Group considerations and Object Structures (Work center permissions)
There are a few types of deployments, and depending on how you want your users to connect and how you want the infrastructure to flow, there are 3 main options.
Option 1: Use the maximo-x Login form. For a user to connect to Maximo Work Centers, they must access the URL of http://<servername>:<port>/maximo-x (by default). This uses the maximo-x Login form and will authenticate users with access to Maximo and Work Centers. This is the default option. With LDAP, the URL used to log in is /maximo-x/index.html.
Option 2: Use the Maximo Login form. When users access the /maximo-x context root (same URL as above), they are redirected to the Maximo page to log in. This authenticates users with access to Maximo and if they have permissions to a work center, it will redirect them to Work Centers.
Note: With SAML and interactive login schemes, this option is recommended.
Option 3: Use CORS. CORS is when you deploy your Maximo-x war to a separate server or cluster than your base Maximo UI server, and since the maximo-x authentication always goes through base Maximo, this is how it knows where to connect to.
The web.xml is located by default here: SMP\maximo\applications\maximo-x\WEB-INF
The config.json is located by default here: SMP\maximo\applications\maximo-x\script
For NON-LDAP deployments, you will not need to make any changes to the Maximo-x web.xml.
For LDAP deployments, the web.xml needs to be changed in order to enable security. This is similar to the base Maximo web.xml, uncommenting out the security constraint and changing the login-config, and changing application security parameters to 1.
<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
<display-name>Maximo-X</display-name>
<welcome-file-list>
<welcome-file>index.html</welcome-file>
</welcome-file-list>
<security-constraint>
<web-resource-collection>
<web-resource-name>MAXIMO-X</web-resource-name>
<description>MAXIMO-X</description>
<url-pattern>/index.html</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<description>Roles that have access to MAXIMO-X</description>
<role-name>maximouser</role-name>
</auth-constraint>
<user-data-constraint>
<description>data transmission gaurantee</description>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
<!-- Uncomment this login-config if you want to use BASIC authentication and make
sure the FORM based login-config below is commented out. NOTE: You still need the
security-constraint about uncommented too.
-->
<!--
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>MAXIMO Web Application Realm</realm-name>
</login-config>
-->
<!-- Uncomment this login-config if you want to use form authentication and make
sure the BASIC based login-config above is commented out. NOTE: You still need the
security-constraint above uncommented too.
-->
<login-config>
<auth-method>FORM</auth-method>
<realm-name> MAXIMO Web Application Realm</realm-name>
<form-login-config>
<form-login-page>/formlogin.html</form-login-page>
<form-error-page>/formloginerror.html</form-error-page>
</form-login-config>
</login-config>
<security-role>
<description>MAXIMO Application Users</description>
<role-name>maximouser</role-name>
</security-role>
<env-entry>
<description>Indicates whether to use Application Server security or not</description>
<env-entry-name>useAppServerSecurity</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>1</env-entry-value>
</env-entry>
</web-app>
If you refer to the previous section, you find the different deployment options. Changes to the config.json are based on the options above.
Option 1: No changes to config.json needed. If your MAXIMO CONTEXT ROOT HAS CHANGED you need to modify this file.
Option 2: Modify the top section of the config.json, changing the enabled value to true, and updating the hostname and port of Maximo.
Option 3: Modify both sections of the config.json.
If your MAXIMO CONTEXT ROOT HAS CHANGED you need to modify this file, whether using nonldap or ldap. For example, if you access Maximo as /maxprod in the URL, you need to change the first part of the config.json to reflect this change. Change the following line "defaultcontext": "/maximo", to "defaultcontext": "/maxprod",
Here is an example with each section filled out. If you do not need a section for your deployment type as mentioned above, then you don't need to make any changes.
{
"defaultcontext": "/maximo",
"comment_defaultcontext": "The default context, based on default setup, where maximo and maximo-x are deployed on the same server using same hostname and port.",
"maximoserverauthentication" : {
"enabled": true,
"maximologinurl": "http://uiserverhostname.ibm.com:80/maximo"
},
"comment_maximoserverauthentication": "Enable this if you want to use maximo server configured authentication only. In this mode, the user would be re-directed to maximologinurl to authenticate. By default, this is not enabled and the maximo-x login dialog would be shown, which would gather credentials and submit to maximo server.",
"contexts": [
{
"name": "Separate Maximo Host",
"hostname": "workcenterhostname.ibm.com",
"maximohostname": "uiserverhostname.ibm.com",
"maximoport": 80,
"maximocontext": "/maximo"
}
],
"comment_contexts": "Use contexts, if you want to use a different hostname to access maximo-x or if maximo-x and maximo are running on two different servers. If you are not using proxy, make sure to configure Maximo server with CORS settings. NOTE that you do not need to use contexts if maximo-x and maximo are running on the same server and using the same hostname and port."
}
After configuring the files as needed for your deployment, build the maximo-x war.
In an administrative command prompt window, Navigate to SMP\maximo\deployment. Run the command
This builds the maximo-x.war is the same place as the maximo ear, in SMP\maximo\deployment\default.
Deploying the maximo-x war to either WebSphere or WebLogic is the same process as deploying the regular maximo.ear, but with fewer steps. You need to select the server or cluster to deploy the war to, as well as map the virtual host that is appropriate to that server or cluster. The rest can be left as default (unless you'd like to change the application name or context root).
When deploying maximo-x war to a cluster separate from the UI cluster, there are no extra steps involved in the deployment process.
For LDAP, after deploying maximo-x war it is still recommended to map the security role to user/group mapping to All Authenticated In Application's Realm.
Do this by going to the WebSphere console, Applications, select the maximo-x application, the Security role to user/group mapping.
Before logging in to maximo-x, there are a few properties in Maximo's System Properties application that should be updated.
In the System Properties application, filter for web app url.
These properties represent the URL that is passed to the request when oslc rest call is made. This is needed because the URLs returned from the calls are used to make more calls.
Update this to the URL that would be used to connect to either your UI or OSLC cluster.
Update mxe.oslc.webappurl to include the correct hostname and port, for example http://maximouiserverhostname.ibm.com:80/maximo/oslc/
Update mxe.oslc.restwebappurl to include the correct hostname and port, for example
http://maximouiserverhostname.ibm.com:80/maxrest/oslc
Update mxe.x_context system property to reflect the context root set in WebSphere for maximo-x application.
After changing the properties, save and then select the changed properties, and perform a Live Refresh.
Since Work Centers behave similar to an application in Maximo, the security permissions are controlled from Group security.
By default the groups need to be created. You want groups associated with each role or work center. There are examples in the Maximo demo data. These groups give access to the work center, as well as the appropriate needed object structures. Work centers work by using the JSON API in Maximo and collecting data from object structures through it. Make sure that users logging in to Work Centers have permissions associated with these groups.
Users can have access to multiple Work Centers, and from 7.6.0.7 and later, the user is able to select their default work center to log them in to.
It is possible to give the Maxadmin group access to all Work Centers for ability to log in and test. See Creating Work Center and Tool security groups.
Now that users have permissions, Work Centers are deployed and configured, we can log in.
It is highly recommended to clear your browser cache before logging in Work Centers, especially if you attempted to log in previously and were unable to.
Access the URL http://maximouiserverhost/maximo-x and it directs you to the login page.
In 7.6.0.5, the user logging in must have the same login ID and userid in order to be able to log in. This issue is fixed in Maximo 7.6.0.6.
If you receive a blank page logging in, ensure that you are NOT using Internet Explorer, clear your browser cache, and ensure that the security groups are correctly configured for the user, then try again.
If after logging in, some KPIs or sections don't load, then the problem will likely be either access to an Object Structure is missing, or the data retrieved is missing a piece of information needed.
UID
ibm11114023