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 have 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 other documents for the features, looks and functionality of them. Link here:
https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/IBM%20Maximo%20Asset%20Management/page/Work%20Centers
https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/IBM%20Maximo%20Asset%20Management/page/Work%20Centers
There are options when deploying work centers. I will 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 will label those steps as we go through, and when deploying for non-LDAP, you will want to skip those steps.
Work centers are deployed using the maximo-x war that is part of base Maximo, so if you see reference to maximo-x, that is what it means.
Work centers are deployed using the maximo-x war that is part of base Maximo, so if you see reference to maximo-x, that is what it means.
Please note that Internet Explorer is not supported with work centers. Please use Edge, Chrome or Firefox when connecting. 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:
Types of deployments
-Maximo-x login form
-Maximo login form
-Maximo CORS login (When the maximo-x war is deployed in a separate server/cluster as the maximo UI)
-Maximo-x login form
-Maximo login form
-Maximo CORS login (When the maximo-x war is deployed in a separate server/cluster as the maximo UI)
Changes to make before deploying
-web.xml changes
-config.json changes
-web.xml changes
-config.json changes
Deploying the Maximo-x war
-Building the maximo-x war
-To the same cluster as UI
-To a separate cluster from UI
-Building the maximo-x war
-To the same cluster as UI
-To a separate cluster from UI
Properties to change in Maximo
Group considerations and Object Structures (Work center permissions)
Logging into Work Centers
Types of Deployments
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) The first is using the maximo-x login form.
This means that 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. Note that with LDAP the URL used to login should be /maximo-x/index.html.
This means that 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. Note that with LDAP the URL used to login should be /maximo-x/index.html.
(Option 2) The second is to use the Maximo login form. This means that when users access the /maximo-x context root (same URL as above), they will be redirected to the Maximo page to login. This will authenticate users with access to Maximo and if they have permissions to a work center, it will redirect them to work centers.
(Option 3) The third is to 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.
Changes to Make Before Building and Deploying
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
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 will need to be changed in order to enable security. This is similar to the base Maximo web.xml's and involves uncommenting out the security constraint and changing the login-config and changing application security 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>
<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>
-->
<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>
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>
<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 will 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 will need to modify this file.
(Option 2) You will need to modify the top section of the config.json, changing the enabled value to true, and updating the hostname and port of Maximo.
(Option 3) You will need to modify both sections of the config.json.
If your MAXIMO CONTEXT ROOT HAS CHANGED you will need to modify this file, whether using non-ldap or ldap. For example if you access Maximo as /maxprod in the URL, you will need to change the first part of the config.json to reflect this change. Change the line "defaultcontext": "/maximo", below to "defaultcontext": "/maxprod",
Below is an example of 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.",
"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."
}
"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."
}
Deploying the Maximo-x war
After configuring the above files as needed for your deployment, build the maximo-x war.
To do this navigate to SMP\maximo\deployment in command prompt and run the command:
buildmaximo-xwar
To do this navigate to SMP\maximo\deployment in command prompt and run the command:
buildmaximo-xwar
This will build 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 less steps.
You will need to select the server/cluster to deploy the war to, as well as map the virtual host that is appropriate to that server/cluster.
The rest can be left as default (unless you'd like to change the application name or context root).
You will need to select the server/cluster to deploy the war to, as well as map the virtual host that is appropriate to that server/cluster.
The rest can be left as default (unless you'd like to change the application name or context root).
When deploying to a cluster separate from the UI cluster, there are no extra steps involved in the deployment process.
For LDAP, after deploying 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.
Do this by going to the WebSphere console, Applications, select the maximo-x application, the Security role to user/group mapping.
Properties to change in Maximo
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 webappurl.
These properties represent the URL that is passed to the request when making an oslc rest call. This is needed because the URLs returned from the calls are used to make additional calls.
Update this to the URL that would be used to connect to either your UI or OSLC cluster.
These properties represent the URL that is passed to the request when making an oslc rest call. This is needed because the URLs returned from the calls are used to make additional 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.
Example: http://maximouiserverhostname.ibm.com:80/maximo/oslc/
Example: http://maximouiserverhostname.ibm.com:80/maximo/oslc/
Update mxe.oslc.restwebappurl to include the correct hostname and port.
After changing the properties, save and then select the changed properties, and perform a live refresh.
Group considerations and Object Structures (Work center permissions)
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/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 login and test.
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 login and test.
The knowledge center has how to configure these security groups and Object Structures:
https://www.ibm.com/support/knowledgecenter/en/SS8CCV_7.6.0.5/com.ibm.mbs.doc/securgroup/t_add_users_workcntr.html
https://www.ibm.com/support/knowledgecenter/en/SS8CCV_7.6.0.5/com.ibm.mbs.doc/securgroup/t_add_users_workcntr.html
Logging into Work Centers
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, especially if you have attempted to log in previously and were unable to.
Access the URL http://maximouiserverhost/maximo-x and it will direct you to the login page.
In 7.6.0.5, the user logging in must have the same loginid and userid in order to be able to log in. This is fixed in Maximo 7.6.0.6.
If you receive a white page when 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.
It is highly recommended to clear your browser cache before logging in, especially if you have attempted to log in previously and were unable to.
Access the URL http://maximouiserverhost/maximo-x and it will direct you to the login page.
In 7.6.0.5, the user logging in must have the same loginid and userid in order to be able to log in. This is fixed in Maximo 7.6.0.6.
If you receive a white page when 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.
Thank you for taking to the time to go over this blog, and if any questions, comments or concerns please let me know!
No comments:
Post a Comment