Configuring OAuth access

If you want to use an OAuth authentication service to provide secure delegated access to Maximo® Manage data, you can configure OAuth access by using the HTTP handler that is provided in the integration framework.

Before you begin

Details for the OAuth client access are stored in the MAXOAUTHCLIENT object.

Administrators must grant the appropriate authorizations to the MAXOAUTHCLIENT object structure by using the Security Groups application.

Because most OAuth handshakes are done over TLS, the Manage truststore must also be updated with the CA trust chain of the OAuth provider.

About this task

Maximo Manage supports the OAuth 2.0 client credentials grant type. Using this flow, Maximo Manage sends a client ID and client secret to the URL of the OAuth provider for authentication and receives an access token.

The date and time that the access token is created are stored in the MAXOAUTHCLIENT object. The OAuth provider specifies an expiration interval for the access token, and the token expires at the end of that interval. After expiration, a new token is generated when a new authentication request occurs.

There are two options for adding or modifying OAuth clients:
  • You can add or modify clients in the End Points application.
  • You can add or modify clients by using a REST API call.

Adding or modifying OAuth clients in the End Points application

In the End Points application, you can add OAuth clients or update existing clients.

Procedure

  1. In the End Points application, from the More Actions menu, select Add/Modify OAuth Clients.
  2. In the Add/Modify OAuth Clients window, click New Row.
  3. In the Details section on the Add/Modify OAuth Clients window, enter the details for the OAuth connection, as shown in the following table.
    Option Description
    Client Name Unique identifier of the OAuth client.
    Client ID Maximo Manage client ID that is registered with the OAuth provider.
    Grant Type Grant type for exchange. The default is client_credentials.
    Token URL URL of the OAuth provider, which is used to exchange the client ID with the access token.
    Client Secret Maximo Manage client secret that is registered with the OAuth provider.

    The clientsecret is encrypted in the Manage database. Because the table is backed up in cache, do not perform offline updates to the table.

    Scope Scope that specifies the permissions that are granted for the access token request. This field is optional.
    Refresh Token Token to support grant types that use a refresh token. Maximo Manage 8.3 does not support this attribute.
    The following fields on the Add/Modify OAuth Clients window are read-only fields:
    • The Expiry field displays the expiration interval in seconds for the access token.
    • The Creation date field displays the date and time that the access token was created.
  4. Click OK.

Adding or modifying OAuth clients by using a REST API

The HTTP handler endpoint includes an oauthclient property. To add a client by using a REST API call, you must specify the value for the clientname attribute in the oauthclient property.

Procedure

To configure the OAuth client for token exchange, you can send a REST API call that specifies values from the MXAPIOAUTHCLIENT object structure, as shown in the following example:
POST /oslc/os/mxapioauthclient?lean=1&ctx=ccrypto=1
{
  "clientname":"{user-defined name for the client}",
  "clientid":"{ID that is provided by the OAuth provider}",
  "clientsecret":"{secret that is provided by the OAuth provider}",
  "scope":"{optional scope}",
  "tokenurl":"{token URL that is provided by the OAuth provider}"
}