Security in the REST API

Tivoli®'s process automation engine provides the authentication layer and authorization support for the REST API.

No specific authentication-related processing occurs within the REST API framework.

The authentication layer can provide either J2EE authentication or native authentication for the REST API, and the application server provides HTTPS support.

J2EE authentication

To use HTTP basic authentication, modify the web.xml file for the maxrest web module by uncommenting the following lines:

 <!--
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>REST Servlet for Web App</web-resource-name>
            <description>Object Structure Service Servlet (HTTP POST)
					accessible by authorized users</description>
            <url-pattern>/rest/*</url-pattern>
            <http-method>GET</http-method>
            <http-method>POST</http-method>
        </web-resource-collection>
        <auth-constraint>
            <description>Roles that have access to Object Structure
					Service Servlet (HTTP POST)</description>
            <role-name>maximouser</role-name>
        </auth-constraint>
        <user-data-constraint>
            <description>data transmission guarantee</description>
            <transport-guarantee>NONE</transport-guarantee>
        </user-data-constraint>
    </security-constraint>

    <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>REST Web Application Realm</realm-name>
    </login-config>
-->

The preceding <security-constraint> section refers to a single role, maximouser, which is defined in the <security-role> section of the file. By default, the <security-role> section is not commented out:

<security-role>
	<description>MAXIMO Application Users</description>
	<role-name>maximouser</role-name>
</security-role>

In addition, change the value for useAppServerSecurity from 0 to 1:

<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>0</env-entry-value>
</env-entry>

Native authentication

If native authentication is used, a request can provide the credentials by specifying a MAXAUTH header property that contains a Base64-encoded user and password.

If explicit login or logout requests are necessary, use the following requests:

GET /maxrest/rest/login
GET /maxrest/rest/logout

Cross-module communication

You can communicate with the REST API from the maximo and maxrest web modules.

In cross-module communication, you typically do not want the user to re-enter their credentials. If you use application server authentication, this issue does not arise because the browser propagates the authentication token to the web modules for each request. For native authentication, the REST API is available as a library (commonweb) that any web module can access.

For example, the following URI queries an asset by using the maxrest web module: http://site.example.com:9999/maxrest/rest/mbo/asset/46.

In contrast, the following URI queries an asset by using the user interface web module: http://site.example.com:9999/maximo/rest/mbo/asset/46.

Authorization

For object structures, you can connect a resource to an authorizing application on the Object Structure tab of the Object Structures application. If you specify an authorizing application, all integration processing that uses the object structure is affected.

For business objects, you can connect a resource to an authorizing application in the Application Authorization for Objects window of the Object Structures application. The application authorizes all REST API requests for the specific MBO resource.

You can restrict resource access by specifying a list of resource names in the mxe.rest.mbo.blockaccess and mxe.rest.os.blockaccess system properties.

Feedback