How To
Summary
How do you log in to Maximo in a secure application server environment in order to create an api key? How do you use that api key without needing user credentials in a secure application server environment?
Objective
Api keys are tokens that can be used to make REST API calls without needing to provide user credentials along with the request. When using an api key to access a resource in Maximo, no user session is created in Maximo, so that user sessions do not need to be maintained, no logout is required. When the key is created, it is registered in Maximo for the user it was created for, and all subsequent use of that key will invoke security checks based on the user associated with it.
In the following discussion you will learn how to connect to the Maximo application running in a secure application server environment, generate a REST api key and subsequently use the generated api key to GET and POST data from/to Maximo calling the REST API.
Environment
Maximo 7.6.0.9 or later
Steps
In a secure application server environment, there are changes made in the Maximo application files and system properties application as well as enabling Application Server Security and creating a connection to an LDAP connection from within the application server console such as WebSphere Application Server's administration console.
For the REST api, in order to use api keys without being constrained by the security settings in place, a new servlet mapping needs to be added. This servlet mapping is required for Maximo versions 7.6.0.9, 7.6.0.10 and 7.6.1. Later releases include this mapping.
To add the mapping, edit the following file:
ibm\smp\maximo\applications\maximo\maximouiweb\webmodule\WEB-INF\web.xml
Locate the OSLCServlet mapping in the file, and immediately below it, enter the following text:
<servlet-mapping>
<servlet-name>OSLCServlet</servlet-name>
<url-pattern>/api/*</url-pattern>
</servlet-mapping>
Save the file, then rebuild and redeploy the maximo.ear.
The web.xml file for the maximouiweb web module also determines the authentication method being used with Maximo. The two methods are typically FORM or BASIC. We will use Postman in the following steps to log in to Maximo, create an api key, and then use that api key.
NOTE: Maximo 7.6.1.1 and later include an Administration work center for you to create the API key using a UI so you can skip steps 1 and 2.
1. Logging in to Maximo using Postman and Basic authorization header:
In Postman, click the Authorization button, and select "Basic Auth".
Set the username and password associated with a valid Maximo user.
Click the Headers button, and create the following header:
Content-type=application/json
Set the method to POST, and the URL to http://<maximohost>:<port>/maximo/oslc/apitoken/create
(Replacing <maximohost> with your Maximo host name and <port> with your port number)
Set the body format to JSON and add the following text:
{
"expiration":-1
}
"expiration":-1
}
The above will create one api key for the logged in user which will never expire. Note that there can be only one key per user. If you create a new key, the first key will no longer be valid.
Click the send button. You should see a message similar to the following:
{
"apikey": "lbudq2mc"
}
You can now test send requests to Maximo using the above generated api key. Since we added the servlet mapping to the web.xml file, we can use the api context to access objects using this key without the need to provide any user credentials. This means that the url must change.
We will get a list of assets in the following steps. Create a new tab in Postman.
The first step here is to click the Cookies link and delete all cookies in Postman. No credentials are required at this point.
Now in the new tab, another header is required. The x-public-uri header will ensure that all resource links returned to the client will contain the correct /api/* context rather than pointing to the secured /oslc/* context.
Add the following headers:
x-public-uri=http://<maximohost>:<port>/maximo/api
Content-Type=application/json
(Replacing <maximohost> with your Maximo host name and <port> with your port number)
Next, create the following two parameters:
apikey=lbudq2mc
lean=1
Set the method to GET and the URL to:
http://<maximohost>:<port>/maximo/api/os/mxapiasset
(Replacing <maximohost> with your Maximo host name and <port> with your port number)
You should receive a response containing resource links to all assets in the system. Notice that each resource is returned with the api context, bypassing application server security and no sessions are created in Maximo.
2. Logging in to Maximo using Postman and Form authentication:
When using form authentication, three tabs are needed in Postman.
The first is the login tab. This tab requires a different content-type header and needs to be done separately.
The second is the key creation requiring the
The third is the call using the api key.
For the login tab, create a header as follows:
Content-type=x-www-form-urlencoded
Add the following two parameters:
j_username=<username>
j_password=<password>
(Replacing the <username> and <password> with a valid maximo username and password)
Set the method to POST and the URL to:
http://<maximohost>:<port>/maximo/j_security_check
(Replacing <maximohost> with your Maximo host name and <port> with your port number)
Click the send button. You should now be logged in to Maximo.
On the second tab in Postman:
Click the Headers button, and create the following header:
Content-type=application/json
Set the method to POST, and the URL to http://<maximohost>:<port>/maximo/oslc/apitoken/create
(Replacing <maximohost> with your Maximo host name and <port> with your port number)
Set the body format to JSON and add the following text:
{
"expiration":-1
}
"expiration":-1
}
The above will create one api key for the logged in user which will never expire. Note that there can be only one key per user. If you create a new key, the first key will no longer be valid.
Click the send button. You should see a message similar to the following:
{
"apikey": "lbudq2mc"
}
3. You can now send requests to Maximo using the above generated api key. Since we added the servlet mapping to the web.xml file, we can use the api context to access objects using this key without the need to provide any user credentials. This means that the url must change.
We will get a list of assets in the following steps. Create a new tab in Postman.
The first step here is to click the Cookies link and delete all cookies in Postman. No credentials are required at this point.
Now in the third tab, another header is required. the x-public-uri header will ensure that all resource links returned to the client will contain the correct /api/* context rather than pointing to the secured /oslc/* context.
Add the following headers:
x-public-uri=http://<maximohost>:<port>/maximo/api
Content-Type=application/json
(Replacing <maximohost> with your Maximo host name and <port> with your port number)
Next, create the following two parameters:
apikey=lbudq2mc
lean=1
Set the method to GET and the URL to:
http://<maximohost>:<port>/maximo/api/os/mxapiasset
(Replacing <maximohost> with your Maximo host name and <port> with your port number)
You should receive a response containing resource links to all assets in the system. Notice that each resource is returned with the api context, bypassing application server security and no sessions are created in Maximo.
For assistance with any of the above scenarios, please contact IBM Support.
Set the method urlhttp://systems1-imwin.swg.usma.ibm.com:9080/maximo/api/apitoken/create
Document Location
Worldwide
[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSLKT6","label":"IBM Maximo Asset Management"},"Component":"REST API","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"7.6.0.9 and later","Edition":"","Line of Business":{"code":"LOB02","label":"AI Applications"}}]
Document Information
Modified date:
22 November 2021
UID
ibm11137772