Configuring a third-party cloud OAuth IdP for Maximo Real Estate and Facilities

You can configure one of several third-party cloud IdPs as the OAuth identity provider (IdP) for single sign-on (SSO) to log in to Maximo® Real Estate and Facilities with third-party login credentials. Cloud login directly supports Microsoft, Autodesk, Okta, Google, and IBM Security Verify.

Create an OAuth application with a cloud IdP and configure the OAuth IdP details in Maximo Real Estate and Facilities.

Note: SSO does not need to be enabled to use OAuth login. However, if SSO is enabled, you can still use OAuth login and can use a different IdP than the SSO IdP.

Creating an OAuth application

Refer to these general steps to create an OAuth application for an OAuth IdP.

Important: These steps are informational only, as IdPs can change their process at any time without notice. IBM provides no support for the IdP configuration. Contact support for the IdP for any issues.

To review specific steps for Okta, see Creating an OAuth application in Okta.
To review specific steps for Google, see Registering an OAuth application in Google.

Procedure

Create and configure an OAuth application with the proper application type, scopes, users, and redirect URIs.
Note: Configure the OAuth application for three-legged flow. With OAuth, a three-legged flow involves the user (user delegate), the client, and the server, while a two-legged flow involves only the client and the server.
Locate the Client ID and Client Secret values, which you need to configure the OAuth provider in Maximo Real Estate and Facilities.

Configuring an OAuth provider in Maximo Real Estate and Facilities

Procedure

Log in to Maximo Real Estate and Facilities.
Navigate to Tools > System Setup > Integration > OAuth Settings.
Select Add to add an OAuth profile record.
Specify the following OAuth settings:
- Name: Enter a name for the OAuth profile.
- OAuth Provider: Select the name of the OAuth IdP. For example: Microsoft, Autodesk, Okta, Google, or IBM Verify. A Custom IdP option is available, which uses generic processing that might work for some other IdPs. IBM does not provide support for the custom profile.
- Access Type: Select User delegate. An OAuth three-legged flow involves the user (user delegate), the client, and the server, while a two-legged flow involves only the client and the server.
- Description: Enter a description for the profile.
- OAuth Application Key: Enter the Client ID from the third-party OAuth application.
- OAuth Application Secret: Enter the Client Secret from the third-party OAuth application.
- OAuth Authorize URL: Enter the URL value from the OAuth IdP.
- OAuth Token URL: Enter the URL value from the OAuth IdP.
- OAuth Redirect URL: Enter the value for: <MREF_URL>/p/oauth/signon.
- OAuth Scope: Enter the API permissions to grant to the OAuth application. Maximo Real Estate and Facilities requires only access to read the current user. For example:
  - For Microsoft, enter: openid
  - For Autodesk, enter: user:read
  - For Okta, enter: okta.users.read.self
  - For Google, enter: openid+https://www.googleapis.com/auth/userinfo.email
  - For IBM Security Verify, no value is needed.
- User Code Challenge: Optional: If needed by the IdP, select the checkbox.
- Use Form Post: Optional: If needed by the IdP, select the checkbox. If you select Autodesk in OAuth Provider, this checkbox is enabled by default.
- Passing Client-Id & Secret Using Basic Auth: Optional: If needed by the IdP, select the checkbox. If you select Autodesk in OAuth Provider, this checkbox is enabled by default. It enables Autodesk Authentication v2 by using Basic Authentication.
- User ID Claim: Enter the claim in the OAuth token that is used for the user identity. For example:
  - For Microsoft, enter unique_name.
  - For Autodesk, this is ignored.
  - For Okta, the claims in the OAuth token can be configured. In the default token, the Okta user (which should be an email) is in the sub claim. If you are using the default, enter sub.
  - For Google, this is ignored.
  - For IBM Security Verify, enter preferred_username.
- My Profile ID Field: Enter the field from My Profile records that you want use for the OAuth user identity. You can specify any field in the My Profile record, including custom fields. Typical values are either UserName or eMail.
- User Name Case Sensitive: Optional: Enforce case sensitivity for the user name.
- User allowed login list: Optional: Select this checkbox to further restrict access for this profile to a specific list of users. An Allowed List tab displays. Select the Allowed List tab, and add users to the allowed list. Clear this checkbox to allow all profile users to log in.
- Default Login: Select this checkbox to set this OAuth profile to be the default login profile. You can have one default profile only. When a default profile is set, the login page for the IdP opens without displaying the cloud login screen.
- User for Login: Select the checkbox to enable logging into Maximo Real Estate and Facilities by using this OAuth provider.
- Login Text and Login Image URL: Optional: You can configure the appearance of the IdP login button for this profile on the Cloud login screen.
- Target Application: Enter the URL of a Maximo Real Estate and Facilities Perceptive app or the Maximo Real Estate and Facilities Administrator Console to enable them for cloud login. For example, for the Administrator Console:
```
<MREF_URL>/html/en/default/admin/index.jsp
```
  This field is not used for IBM Maximo Real Estate and Facilities Connector for BIM or IBM Maximo Real Estate and Facilities.

Adding the OAuth IdP certificate to the Liberty truststore

The OAuth IdP certificate for the account must be trusted by IBM WebSphere® Application Server Liberty.

Procedure

Log into your OAuth IdP account from your browser.
Click on the lock icon or the Net Secure error.
Display and download the certificate.
Add the certificate to the IBM WebSphere Application Server Liberty truststore, see Adding trusted certificates.

Creating users in IBM Maximo Application Suite

Create Maximo Real Estate and Facilities users in IBM Maximo Application Suite so that they can use their third-party credentials to log in. For more information about creating users, see Administering user access and permissions.

Logging in to Maximo Real Estate and Facilities

For each option, you can go to the cloud login page and see all the available profiles or go directly to the login page for a specific IdP.

For Maximo Real Estate and Facilities, use one of these URLs:
```
<MREF_URL>/p/cloud
```
```
<MREF_URL>/p/oauth/<OAuth profile name>/tririga
```
Where <OAuth profile name> is the name that you specified in the Configuring OAuth provider in Maximo Real Estate and Facilities section.

For Maximo Real Estate and Facilities React apps, use one of these URLs:

<MREF_URL>/p/cloud/<app_name>

<MREF_URL>/p/oauth/<OAuth profile name>/<app_name>

For Maximo Real Estate and Facilities Polymer apps, use one of these URLs:

<MREF_URL>/p/cloud/<app_name>

<MREF_URL>/p/oauth/<OAuth profile name>/<app_name>?webapp=true

To log in to the Maximo Real Estate and Facilities target app that you specified in the profile, use one of these URLs:
```
<MREF_URL>/p/cloud/profile
```
```
<MREF_URL>/p/oauth/<OAuth profile name>/*
```