Configuring IBM TRIRIGA with Microsoft Exchange 365 and OAuth

There are several steps for configuring IBM® TRIRIGA® Workplace Reservation Manager (Reserve) with Microsoft Exchange 365 and OAuth authorization. For the complete integration to work effectively between TRIRIGA and Microsoft Exchange, you must register two different applications using the OAuth registration process. First OAuth registration is used for the back-end server communication between TRIRIGA and Microsoft Exchange and the second OAuth registration is required for integrating TRIRIGA with Reserve Perceptive app.

Note: The following content discusses the Microsoft Graph API. For more Microsoft Exchange guidance, consult your Microsoft Exchange administrator or documentation.

Contents

I. Concept

Integration between TRIRIGA Reserve and Microsoft Exchange requires two-way communication between TRIRIGA and Exchange.
  • Exchange to TRIRIGA: Exchange sends meeting requests to TRIRIGA for the room resources that TRIRIGA is managing. This communication is done via Simple Mail Transfer Protocol (SMTP) protocol.
  • TRIRIGA to Exchange: TRIRIGA sends messages back to Exchange to accept or reject a meeting request for a managed room. It sends free/busy data to Exchange to ensure the Exchange calendars are kept in sync with TRIRIGA. This communication is done via Graph API.

To enable this communication, you must perform initial configuration in both Exchange and TRIRIGA.

II. Registering OAuth to integrate TRIRIGA server with Exchange

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

a. 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:
  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 may vary depending on your organization's overall use of Microsoft Azure and Microsoft 365. However, for normal TRIRIGA integrations, Single Tenant is sufficient.
    • Redirect URL: Select Web from the drop down list and set the redirect URI to: <TRIRIGA base URL>/p/oauth/signon. For example: https://triapp.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 TRIRIGA.
      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 TRIRIGA.
    5. Select the following permissions:
      • Calendars.ReadWrite: Allows TRIRIGA 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 TRIRIGA 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.

b. Entering OAuth Provider (Microsoft Azure) in TRIRIGA

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

Procedure
  1. Log in to the TRIRIGA 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, "Azure" for Microsoft Azure Active Directory. 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 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 TRIRIGA 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 TRIRIGA 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 TRIRIGA 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 TRIRIGA Reserve. For example: https://login.microsoftonline.com/<tenant Id>/oauth2/v2.0/token
    • OAuth Redirect URL: Enter the value for: <TRIRIGA base URL>/p/oauth/signon. This value is required by TRIRIGA Reserve. For example: https://triapp.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 TRIRIGA Reserve. End users may be asked to approve these permissions when they login.
    • Login section: This section is not used by TRIRIGA 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 TRIRIGA 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 for processing 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.

III. Registering OAuth to integrate TRIRIGA Perceptive App with Exchange

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

a1. 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:
  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://<tririga_server>/<tririga_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 TRIRIGA.
      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 TRIRIGA.
    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.

b1. Entering OAuth Provider (Microsoft Azure) in TRIRIGA

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

Procedure
  1. Log in to the TRIRIGA 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, "azure" for Microsoft Azure Active Directory.
    • Access type: Set 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 TRIRIGA 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 TRIRIGA 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 TRIRIGA 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 TRIRIGA Reserve. For example: https://login.microsoftonline.com/<tenant Id>/oauth2/v2.0/token
    • OAuth Redirect URL: Enter the value for: <TRIRIGA base URL>/p/oauth/. This value is required by TRIRIGA Reserve. For example: https://<tririga_server>/<tririga_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 login.
    • Login section: This section is not used by TRIRIGA 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 TRIRIGA 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.

IV. Importing Microsoft 365 SSL certificate

For TRIRIGA to access the Microsoft Graph API, the application server must make a 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.

V. Configuring IBM TRIRIGA

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 TRIRIGA user who is the default reservation contact. If the Create External Contact for unknown Exchange user? checkbox is not selected, Reserve uses the TRIRIGA 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 TRIRIGA 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 or TAS 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 TRIRIGA to Exchange.
    • Retry Attempts: Specify the number of attempts for reestablishing the connection between TRIRIGA 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 TRIRIGA.
    • 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 TRIRIGA 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 Azure) with TRIRIGA. This registration enables the communication from TRIRIGA 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, for example, abc.tririga.
    • 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. 3. 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. TRIRIGA will write 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 TRIRIGA 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.

VI. 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 TRIRIGA 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.

VII. Next

After you have confirmed that the TRIRIGA 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 TRIRIGA can recognize them.

VIII. Appendix

This section provides the list of application permissions and delegated permissions used for the integration between TRIRIGA 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: