Configuring IBM Maximo Real Estate and Facilities with Microsoft Exchange 365 and OAuth

Configure IBM® Maximo® Real Estate and Facilities Workplace Reservation Manager (Reserve) with Microsoft Exchange 365 and OAuth authorization.

You must register two different applications using the OAuth registration process:
  • Integrate the back-end server communication between Maximo Real Estate and Facilities and Microsoft Exchange
  • Integrate Maximo Real Estate and Facilities with the Reserve Perceptive app.

Registering OAuth to integrate Maximo Real Estate and Facilities server with Exchange

To use Microsoft Exchange 365 with Maximo Real Estate and Facilities Reserve, you must register an OAuth application with Microsoft Azure, and register the OAuth provider (Microsoft) with Maximo Real Estate and Facilities. This registration enables the communication from Maximo Real Estate and Facilities Reserve to Exchange.

Registering OAuth application with Microsoft Azure

For detailed information about the process for registering an application in Microsoft Azure portal, see Register an application with the Microsoft identity platform.

Procedure
  1. Launch the Microsoft Azure app registration screen from the following URL: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
  2. Select New Registration to begin the app registration process.
    Name
    Specify the name to identify the registration in the Microsoft Azure portal.
    Account Type
    This value might vary depending on how your organization uses Microsoft Azure and Microsoft 365. However, for normal Maximo Real Estate and Facilities integrations, select Single Tenant.
    Redirect URL
    Select Web from the drop down list and set the redirect URI to: <base URL>/p/oauth/signon. For example: https://mrefapp.company.com/dev/p/oauth/signon
  3. Specify the client ID, credentials, and certificates.
  4. Create a client secret by completing the following steps:
    1. Click Certificates & secrets.
    2. Click New client secret.
    3. Provide a description and enter a value for the duration of when the client secret expires.
    4. Click Add.
    5. Copy the client secret value from the Value column. This value is later provided in the OAuth Application Secret field of the Microsoft OAuth profile record in Maximo Real Estate and Facilities.
      Note: The client secret can only be viewed immediately after creation so ensure to make note of the value before leaving the page.
  5. Configure API permissions by completing the following steps:
    1. Click API permissions.
      Note: A default User.Read permission for Graph API is available in the API permissions list. You can configure the required permissions by adding them to the existing permissions list.
    2. Click Add a permission.
    3. Select Microsoft Graph.
    4. Click Application permissions to provide permissions for Maximo Real Estate and Facilities.
    5. Select the following permissions:
      Calendars.ReadWrite
      Allows Maximo Real Estate and Facilities to fetch events in a room's calendar. Retrieves a list of event objects that contains single instance meetings and series instances (occurrences) of an event for a specified time range, read event and its attendees, organizers, and get the master working hour events. The permission also allows to create, update, delete, cancel, accept, decline, and tentatively accept events in a room's calendar.
      Mail.ReadWrite
      Allows Maximo Real Estate and Facilities to create, read, update, and delete email in resource mailboxes but does not include permission to send mails. This is applicable only for the resource mailboxes and does not include all user mailboxes.
    6. Click Add permissions.
    7. Click Grant admin consent for "application name" for providing consent.
      Note: You need admin access to view the option to grant admin consent.
    8. Click Yes.
  6. Specify the permissions to limit the application access to a specific set of mailboxes by using the ApplicationAccessPolicy PowerShell cmdlet to configure access control. For more information, see Limiting application permissions to specific Exchange Online mailboxes.

Registering OAuth provider (Microsoft Azure) in Maximo Real Estate and Facilities

After you register an OAuth application with Microsoft Azure, you must enter the OAuth provider (Microsoft) in Maximo Real Estate and Facilities. To enter the OAuth provider (and OAuth application), you must create a Microsoft OAuth profile record in Maximo Real Estate and Facilities.

Procedure
  1. Log in to the Maximo Real Estate and Facilities main portal.
  2. Navigate to Tools > System Setup > Integration > OAuth Settings.
  3. Select Add to add a new Microsoft OAuth profile record.
  4. In the OAuth Setup section, specify the following OAuth settings:
    Name
    This name may be displayed to end users, and used in API calls to identify the target record.
    OAuth Provider
    Name of the OAuth provider. For example, Microsoft for Microsoft Entra ID. Name is not case-sensitive.
    Access Type
    Set the access type as Application (OAuth application with Microsoft Azure).
    Description
    Description that describes this profile, so an application can display it to users.
    OAuth Application Key
    Enter the value of the Application (Client) ID field from the OAuth application registration in Microsoft Azure. This value is required by Maximo Real Estate and Facilities Reserve.
    OAuth Application Secret
    Enter the value of the client secret Value column from the above OAuth application registration in Microsoft Azure. This value is required by Maximo Real Estate and Facilities Reserve.
    OAuth Authorize URL
    Enter the tenant-specific URL value of the OAuth 2.0 authorization endpoint (v2) field from the above OAuth application registration in Microsoft Azure. This value is required by Maximo Real Estate and Facilities Reserve. For example: https://login.microsoftonline.com/<tenant Id>/oauth2/v2.0/authorize.
    To get the URL value, click Overview on the Azure App registrations page, and then click the Endpoints tab. Copy the value of the OAuth 2.0 authorization endpoint (v2) field.
    OAuth Token URL
    Enter the tenant-specific URL value of the OAuth 2.0 token endpoint (v2) field from the above OAuth application registration in Microsoft Azure. This value is required by Maximo Real Estate and Facilities Reserve. For example: https://login.microsoftonline.com/<tenant Id>/oauth2/v2.0/token
    OAuth Redirect URL
    : Enter the value for: <base URL>/p/oauth/signon. This value is required by Maximo Real Estate and Facilities Reserve. For example: https://mrefapp.company.com/dev/p/oauth/signon
    OAuth Scope
    API permissions that are granted to an OAuth application. For Microsoft Azure, enter: .default. This value is required by Reserve. End users may be asked to approve these permissions when they login.
    Login section
    This section is not used by Reserve.
    Domain Filter
    Specify the domain name for the OAuth profile. For example, <domain name>.onmicrosoft.com.
    Important: In multiple-tenant Exchange environments, a valid Domain Filter value must be defined for the OAuth profile so that Maximo Real Estate and Facilities searches for the correct OAuth profile for reserving a room in that particular tenant. However, even in the single-tenant Exchange environments, the Domain Filter value must be defined for the Exchange tenant that is being used.
    Use with Exchange
    Select this checkbox to process the reservation request.
    Microsoft Graph Callback URL
    The callback URL is used for the Graph Subscriptions setup.
  5. Save your new Microsoft OAuth profile record.

Registering OAuth to integrate the Maximo Real Estate and Facilities reserve perceptive app with Exchange

To use the Maximo Real Estate and Facilities Perceptive App with Microsoft Exchange 365, you must register the Maximo Real Estate and Facilities as an OAuth application with Microsoft Azure, and register the OAuth provider (Microsoft) with Maximo Real Estate and Facilities. This registration enables the communication between the Maximo Real Estate and Facilities Perceptive App and Exchange.
Note: The OAuth registration process in this section is different from the registration process explained in section Registering OAuth to integrate Maximo Real Estate and Facilities server with Exchange.

Registering OAuth application with Microsoft Azure

Important: For detailed information about the process for registering an application in Microsoft Azure portal, see Register an application with the Microsoft identity platform.
Procedure
  1. Launch the Microsoft Azure app registration screen from the following URL: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
  2. Select New Registration to begin the app registration process.
    Name
    Specify the name to identify the registration in the Microsoft Azure portal.
    Account Type
    Select the account type as Accounts in any organizational directory (Any Azure AD directory - Multitenant).
    Redirect URL
    Select Web from the drop down list and Set the redirect URI to: https://<mref_server>/<mref_context>/app/tririgaRoomReservation/oauth. For example: https://triapp.company.com/dev/app/tririgaRoomReservation/oauth.
  3. Specify the client ID, credentials, and certificates.
  4. Create a client secret by completing the following steps:
    1. Click Certificates & secrets.
    2. Click New client secret.
    3. Provide a description and enter a value for the duration of when the client secret expires.
    4. Click Add.
    5. Copy the client secret value from the Value column. This value is later provided in the OAuth Application Secret field of the Microsoft OAuth profile record in Maximo Real Estate and Facilities.
      Note: The client secret can only be viewed immediately after creation so ensure to make note of the value before leaving the page.
  5. Configure API permissions for Microsoft Graph by completing the following steps:
    1. Click API permissions.
    2. Click Add a permission.
    3. Select Microsoft Graph.
    4. Click Delegated permissions to provide permissions for Maximo Real Estate and Facilities.
    5. Select the following permissions:
      Calendars.ReadWrite
      Get full access to user calendars. Allows the app to create, read, update, and delete events in user calendars.
      Contacts.Read
      Read user contacts and allow the app to read logged-in user contacts. i.e get Exchange photo.
      People.Read
      Read users' relevant people lists and allow the app to read a scored list of people relevant to the logged-in user. The list can include local contacts, contacts from social networking or your organization's directory, and people from recent communications. In Reserve Perceptive app, this permission allows the logged-in user to retrieve attendees.
      User.Read
      Read user profiles, allow users to sign-in to the app, and allow the app to read the profile of logged-in users. It also allows the app to read basic company information of logged-in users.
      User.ReadBasic.All
      Read all users' basic profiles. Allows the app to read a basic set of profile properties of other users in your organization on behalf of the logged-in user. This includes display name, first and last name, email address, open extensions, and photo. Also allows the app to read the full profile of the logged-in user. Reserve uses this permission to create or get a custom field that is unavailable in the Exchange event. For example, the Reserve app stores the Additional Location information in a custom extension.
    6. Click Add permissions.
    7. Click Grant admin consent for "application name" for providing consent.
      Note: You need admin access to view the option to grant admin consent.
    8. Click Yes.

Entering OAuth Provider (Microsoft Azure) in Maximo Real Estate and Facilities

After you register an OAuth application with Microsoft Azure, you must enter the OAuth provider (Microsoft) in Maximo Real Estate and Facilities. To enter the OAuth provider (and OAuth application), you must create a Microsoft OAuth profile record in Maximo Real Estate and Facilities.

Procedure
  1. Log in to the Maximo Real Estate and Facilities main portal.
  2. Navigate to Tools > System Setup > Integration > OAuth Settings.
  3. Select Add to add a new Microsoft OAuth profile record.
  4. In the OAuth Setup section, specify the following OAuth settings:
    Name
    This name may be displayed to end users, and used in API calls to identify the target record.
    OAuth Provider
    Name of the OAuth provider. For example, Microsoft for Microsoft Azure Active Directory.
    Access type
    Aet the access type as Both or User Delegate (recommended for delegated permissions).
    Description
    Description that describes this profile, so an application may display it to end users.
    OAuth Application Key
    Enter the value of the Application (Client) ID field from the above OAuth application registration in Microsoft Azure. This value is required by Reserve.
    OAuth Application Secret
    Enter the value of the client secret Value column from the above OAuth application registration in Microsoft Azure. This value is required by Reserve.
    OAuth Authorize URL
    Enter the tenant-specific URL value of the OAuth 2.0 authorization endpoint (v2) field from the above OAuth application registration in Microsoft Azure. This value is required by Reserve. For example: https://login.microsoftonline.com/<tenant Id>/oauth2/v2.0/authorize.
    Note: To obtain the URL value, click Overview on the Azure App registrations page, and then click the Endpoints tab. Copy the value of the OAuth 2.0 authorization endpoint (v2) field.
    OAuth Token URL
    Enter the tenant-specific URL value of the OAuth 2.0 token endpoint (v2) field from the above OAuth application registration in Microsoft Azure. This value is required by Reserve. For example: https://login.microsoftonline.com/<tenant Id>/oauth2/v2.0/token
    OAuth Redirect URL
    Enter the value for: <base URL>/p/oauth/. This value is required by Reserve. For example: https://<mref_server>/<mref_context>/app/tririgaRoomReservation/oauth
    OAuth Scope
    API permissions that are granted to an OAuth application. For Microsoft Azure, enter: https://graph.microsoft.com/People.Read https://graph.microsoft.com/Calendars.ReadWrite https://graph.microsoft.com/User.ReadBasic.All https://graph.microsoft.com/Contacts.Read offline_access
    Note: Users might need to approve these permissions when they lo gin.
    Login section
    This section is not used by Reserve.
    Domain Filter
    Specify the domain name for the OAuth profile. For example, <domain name>.onmicrosoft.com.
    Important: In multiple-tenant Exchange environments, a valid Domain Filter value must be defined for the OAuth profile so that Maximo Real Estate and Facilities searches for the correct OAuth profile for reserving a room in that particular tenant. However, even in the single-tenant Exchange environments, the Domain Filter value must be defined for the Exchange tenant that is being used.
    Use with Exchange
    Clear this checkbox.
  5. Save your new Microsoft OAuth profile record.

Importing Microsoft 365 SSL certificate

For Maximo Real Estate and Facilities to access the Microsoft Graph API, the application server must make an SSL connection to the Microsoft 365 cloud services. This requires the application server to trust the Microsoft 365 SSL certificate. Typically, Java Virtual Machines (JVMs) browsers and application servers include the signer certificate from most major certificate authorities, so they trust any certificate signed by these certificate authorities including those used by the Microsoft 365 services. However, high security application server deployments do not include any certificate authority certificates in the application server trust store as part of the base install. This means that the application server does not trust the Microsoft 365 certificates and connections to the Graph API service fail with an SSL Handshake exception. To resolve this issue, the certificate authority public root certificate used by the Microsoft 365 service must be imported into the application server trust store.

There is some variance observed in the certificate presented by the Microsoft 365 service both over time and by region, so these steps might need to be repeated periodically. The procedure varies based on the application server. For more information about the Microsoft 365 SSL certificate, see Microsoft 365 encryption chains.

Configuring Maximo Real Estate and Facilities

Procedure

  1. Navigate to Tools > System Setup > General > Application Settings > Reservation Settings tab, and Exchange Settings section, and specify the following Exchange Settings.
    Default Reserve User Email
    Specify the email address of the Maximo Real Estate and Facilities user who is the default reservation contact. If the Create External Contact for unknown Exchange user? checkbox is not selected, Reserve uses the Maximo Real Estate and Facilities user profile whose email address matches this default email.
    Create External Contact for unknown Exchange user?
    Select this checkbox to create an external contact record if the Microsoft Exchange user does not match a valid Maximo Real Estate and Facilities user profile. This allows reservation notifications to be sent to the Exchange user.
    Note: This feature is only supported if there is a Reserve site license present on the server. Site licenses are not available for SaaS customers.
    OAuth Lookup
    For Exchange 365, select the Microsoft OAuth profile record that you created above.
    Exchange Retry Duration
    Specify the time duration after which Microsoft Exchange attempts to reestablish the connection from Maximo Real Estate and Facilities to Exchange.
    Retry Attempts
    Specify the number of attempts for reestablishing the connection between Maximo Real Estate and Facilities and Exchange.
    Exchange URL
    Use the following URL: https://graph.microsoft.com/v1.0
    Auto-decline all-day meetings
    Select this checkbox to automatically decline all-day single or recurring reservations from Outlook. An email notification declining the reservation is sent to the sender. If the sender updates the declined reservation by selecting a specific time slot for the reservation, the updated reservation is accepted by Maximo Real Estate and Facilities.
    Exchange Office 365
    Select this checkbox if the Exchange server is a Microsoft Exchange 365 server. This is used during PowerShell script generation to create scripts specific to the Microsoft 365 environment. It also tells Maximo Real Estate and Facilities that it is communicating with Microsoft 365.
    Note: For Exchange 365, you must register an OAuth application with Microsoft Azure, and register the OAuth provider (Microsoft) with Maximo Real Estate and Facilities. This registration enables the communication from Reserve to Exchange. See details above.
    Use Microsoft Graph API
    Select this checkbox to enable reservations using the Graph API.
    Integrate Perceptive Reserve App with Exchange
    Select this checkbox to enable integration of the Perceptive Reserve App with Exchange.
    Perceptive Reserve App OAuth Profile
    Select the OAuth profile that you have created for the Perceptive Reserve App.
  2. Log out and log in for these settings to take effect in session.
  3. Configure the following properties on the Reserve SMTP Agent tab of the Admin Console:
    • Domain information for the Microsoft Exchange server.
    • Timeout of the SMTP endpoint in minutes.
    • The port number that is used by the Reserve SMTP agent for incoming SMTP traffic, for example, 25.
    • Option to keep the email after SMTP processing.
      Note: Enable the keep email option only when you want to debug the SMTP processing.
  4. Verify that the following property in the TRIRIGAWEB.properties is set to:
    • TRIRIGA_RESERVE_SMTP_ROOT=<existing incoming SMTP directory>. For example: c:\tririga\install\userfiles\smtp\in. Maximo Real Estate and Facilities writes incoming mail to this directory to process it.
  5. Restart the application server only if you are making any updates in the TRIRIGAWEB.properties.
    Note: You don't need to restart the application server if you update the properties on the Reserve SMTP Agent tab.
  6. Start Reserve SMTP Agent from the Maximo Real Estate and Facilities Admin Console. The SMTP Agent accepts and processes forwarded email from Exchange.
  7. Create reservable rooms with a Reserve Calendar to reflect available hours. Details are not documented here.

Verifying Configuration

At this point, you should be able to verify your setup is correct by booking a meeting in Exchange Outlook Web Access (OWA) and including the room that you just created. You should get a mail response back from Maximo Real Estate and Facilities accepting the meeting invitation for the room.
  • Go to your Calendar to create an appointment.
  • Go to the Scheduling Assistant tab, and Select Rooms section. Add the room that you created above.
  • Send the invitation. You should get an acceptance email back.

Next

After you have confirmed that the Maximo Real Estate and Facilities Reserve-Exchange integration is working, you can then install and use the Advanced Room Search add-in for Microsoft Outlook.

Note: If you had any existing Outlook reservations prior to the Reserve-Exchange integration, you must delete and recreate the reservations so that Maximo Real Estate and Facilities can recognize them.

Appendix

This section provides the list of application permissions and delegated permissions used for the integration between Maximo Real Estate and Facilities and Microsoft Exchange. For more information, see Microsoft Graph permissions reference.

Application permissions

Base API URLs that are used for Microsoft Graph:
Graph API doc URLs that are used for room email address:

Delegated permissions

Graph API doc URLs that are used for room email address: