Appendix A. Adding a Root Trusted Signed Certificate to the FreeBusy Operating System(s)
Troubleshooting issues
Account Expiration
If the BTAvailability test page fails, this is likely due to the BTFreeBusy account’s Active Directory password expiring. To resolve this issue, after the AD password has been reset, go to the SetFBCred tool and update the password within FreeBusy. See the SetFBCred Utility appendix for more information.
Troubleshooting FreeBusy on the Domino Coex Server
To enable logging:
-
Change the following values in the Notes.ini file on the Domino Coexistence server:
-
BTCOEX_LOG=8
-
BTCOEX_LOGDATA=15
-
BTCOEX_SERVER_LOG=6
-
BTCOEX_CLIENT_LOG=6
-
To start logging, save the Notes.ini file and restart the Domino Coex server:
-
FreeBusy logs are stored in the <Domino program directory>\logs folder
-
BTServer.log contains information about FreeBusy requests from Exchange to Domino
-
BTClient.log contains information about FreeBusy requests from Domino to Exchange
-
-
To test Domino to Exchange FreeBusy connectivity:
-
At the Domino Coex server console, enter the following command:
-
|
PowerShell |
|
tell btfreebusy test <any valid Exchange user’s SMTP address> |
-
When the FreeBusy lookup completes, search the BTClient.log for “error”
-
To test Exchange to Domino FreeBusy connectivity:
-
On the Windows Coex server, open a web browser and go to the BT Availability Router test page to request any valid Domino user’s Free/Busy time:
“http://autodiscover.domino.<your Domino Domain>/btrouter/exchange.asmx”
-
From the list of options, click on BT_TestConnectivity
-
Enter valid Domino users in the email1 and email2 textboxes and click Invoke:
-
-
When the FreeBusy lookup completes, search the BTServer.log for “error”. (If the problem is connectivity related, there will not be any request logged in BTServer.log.)
-
Network Connectivity
Free/Busy and Scheduling processing is time sensitive for both Notes and Outlook. Network connectivity delays can cause intermittent performance of FreeBusy and Schedule look ups in Outlook and Notes.
The FreeBusy logs can be checked for requests being made and returned to either Domino or Exchange / Office 365.
In the event that there are network delays causing intermittent failures the network connections between the Domino Integration server, Windows IIS Integration Server and the target Exchange Server or Office 365 tenant should be verified. Binary Tree support does not cover networking validation or network device checks, these should be completed by the customer networking team with the relevant network device vendor support for routers, firewalls and load balancers if used.
Useful Knowledgebase Articles
Troubleshooting Knowledgebase Articles:
BT FreeBusy end to end check:
https://binarytree.zendesk.com/hc/en-us/articles/360027192331-BT-FreeBusy-end-to-end-check
FB: BT FreeBusy troubleshooting steps
https://binarytree.zendesk.com/hc/en-us/articles/360026909172-BT-Freebusy-troubleshooting-steps
FB: Debug and Logging
https://binarytree.zendesk.com/hc/en-us/articles/360027193211-FB-Debug-and-Logging
FB: How to view FreeBusy for a restricted Domino Room/Resource
Appendix A. Adding a Root Trusted Signed Certificate to the FreeBusy Operating System(s)
Free/Busy requests that are coming from Exchange go through Domino’s HTTP task, which fully supports SSL when properly configured. You can refer to the Domino Administrator help or HCL support for configuration steps.
Free/Busy requests going to Exchange cannot be made using Domino’s HTTP task, so the BTFreeBusy task is used. If, on the Domino Coex server, you are able to open Internet Explorer and access the Windows Coex server root site without any SSL error, BT FreeBusy is configured correctly.
-
From the server, open Internet Explorer and browse to the Windows Coexistence Server via the HTTPS protocol:
-
https://autodiscover.domino.<YourSMTPDomain.com>/
-
-
Click on the lock icon on the browser bar, and then select View certificates:
-
Next, click on the Certification Path tab, the root certificate signer, and then click View Certificate:
-
When the root certificate is open, click on the Details tab, and then click Copy to File:
It is assumed that the installer knows how to install the SSL certificate on the Domino and Windows Coex servers.
The Domino SSL certificate will need to be added to the Certificate Store on the Windows Coexistence server.
The SetFBCred utility is used to configure the credentials for the three FreeBusy IIS components: AvailabilityService and AvailabilityRouter.
The SetFBCred utility should be run from the C:\Program Files\BinaryTree\CMT for Coexistence\AvailabilityService\bin directory.
Appendix B. SetFBCred Utility
Troubleshooting issues
Account Expiration
If the BTAvailability test page fails, this is likely due to the BTFreeBusy account’s Active Directory password expiring. To resolve this issue, after the AD password has been reset, go to the SetFBCred tool and update the password within FreeBusy. See the SetFBCred Utility appendix for more information.
Troubleshooting FreeBusy on the Domino Coex Server
To enable logging:
-
Change the following values in the Notes.ini file on the Domino Coexistence server:
-
BTCOEX_LOG=8
-
BTCOEX_LOGDATA=15
-
BTCOEX_SERVER_LOG=6
-
BTCOEX_CLIENT_LOG=6
-
To start logging, save the Notes.ini file and restart the Domino Coex server:
-
FreeBusy logs are stored in the <Domino program directory>\logs folder
-
BTServer.log contains information about FreeBusy requests from Exchange to Domino
-
BTClient.log contains information about FreeBusy requests from Domino to Exchange
-
-
To test Domino to Exchange FreeBusy connectivity:
-
At the Domino Coex server console, enter the following command:
-
|
PowerShell |
|
tell btfreebusy test <any valid Exchange user’s SMTP address> |
-
When the FreeBusy lookup completes, search the BTClient.log for “error”
-
To test Exchange to Domino FreeBusy connectivity:
-
On the Windows Coex server, open a web browser and go to the BT Availability Router test page to request any valid Domino user’s Free/Busy time:
“http://autodiscover.domino.<your Domino Domain>/btrouter/exchange.asmx”
-
From the list of options, click on BT_TestConnectivity
-
Enter valid Domino users in the email1 and email2 textboxes and click Invoke:
-
-
When the FreeBusy lookup completes, search the BTServer.log for “error”. (If the problem is connectivity related, there will not be any request logged in BTServer.log.)
-
Network Connectivity
Free/Busy and Scheduling processing is time sensitive for both Notes and Outlook. Network connectivity delays can cause intermittent performance of FreeBusy and Schedule look ups in Outlook and Notes.
The FreeBusy logs can be checked for requests being made and returned to either Domino or Exchange / Office 365.
In the event that there are network delays causing intermittent failures the network connections between the Domino Integration server, Windows IIS Integration Server and the target Exchange Server or Office 365 tenant should be verified. Binary Tree support does not cover networking validation or network device checks, these should be completed by the customer networking team with the relevant network device vendor support for routers, firewalls and load balancers if used.
Useful Knowledgebase Articles
Troubleshooting Knowledgebase Articles:
BT FreeBusy end to end check:
https://binarytree.zendesk.com/hc/en-us/articles/360027192331-BT-FreeBusy-end-to-end-check
FB: BT FreeBusy troubleshooting steps
https://binarytree.zendesk.com/hc/en-us/articles/360026909172-BT-Freebusy-troubleshooting-steps
FB: Debug and Logging
https://binarytree.zendesk.com/hc/en-us/articles/360027193211-FB-Debug-and-Logging
FB: How to view FreeBusy for a restricted Domino Room/Resource
Appendix A. Adding a Root Trusted Signed Certificate to the FreeBusy Operating System(s)
Free/Busy requests that are coming from Exchange go through Domino’s HTTP task, which fully supports SSL when properly configured. You can refer to the Domino Administrator help or HCL support for configuration steps.
Free/Busy requests going to Exchange cannot be made using Domino’s HTTP task, so the BTFreeBusy task is used. If, on the Domino Coex server, you are able to open Internet Explorer and access the Windows Coex server root site without any SSL error, BT FreeBusy is configured correctly.
-
From the server, open Internet Explorer and browse to the Windows Coexistence Server via the HTTPS protocol:
-
https://autodiscover.domino.<YourSMTPDomain.com>/
-
-
-
Next, click on the Certification Path tab, the root certificate signer, and then click View Certificate:
-
When the root certificate is open, click on the Details tab, and then click Copy to File:
It is assumed that the installer knows how to install the SSL certificate on the Domino and Windows Coex servers.
The Domino SSL certificate will need to be added to the Certificate Store on the Windows Coexistence server.
The SetFBCred utility is used to configure the credentials for the three FreeBusy IIS components: AvailabilityService and AvailabilityRouter.
The SetFBCred utility should be run from the C:\Program Files\BinaryTree\CMT for Coexistence\AvailabilityService\bin directory.
AvailabilityService
If Exchange Web Services are configured to require a username and password to access FreeBusy information, the AvailabilityService must supply those credentials on each request. Select the entry under AvailabilityService in the pane on the left to populate the BTAvailability tab:
After making changes, click Update; the config files will only be updated when you click Save
The user name is the FreeBusy user's AD login (not necessarily the actual email address) as seen below:
-
FreeBusyAdmin@myADDomain.com
The pre-Windows 2000 format may also work, but the user@domain format is recommended.
To confirm that you have the right password, start a new instance of Internet Explorer on the Windows Coex server and go to the EWS URL listed in the AvailabilityService connection settings. This will produce a login challenge where you can try out the password.
AvailabilityRouter
If the Domino requires a username/password for FreeBusy queries, the AvailabilityRouter must supply those credentials on each request. Select the entry under AvailabilityRouter in the tree on the left to populate the BTRouter tab.
The Username must belong to a Notes user who is listed in the ACLs of the btws.nsf.
Appendix C: Enable Modern Authentication
Hybrid Modern Authentication is distinct from Basic Authentication (username and password in Section 6.1.3)
Enabling the use of Modern authentication will replace the configuration in Section 6.1.3 for Basic Authentication. If the Hybrid Modern Authentication tab is populated this will override the Basic Authentication and FreeBusy will always use the Hybrid Modern Authentication details.
Basic Authentication is typically used on-premises, and Hybrid Modern Authentication is typically used with Office 365/Microsoft 365.
Both authentication schemes require the Exchange Web Services URL.
Configuring Availability Service:
Hybrid Modern Authentication requires an App registration to connect to Exchange Web Services.
Four items are required for configuration and can be taken from the App registration process which is explained below.
These four items are:
-
Application (client) ID – this is the App registration that will be created
-
Directory (tenant) ID – this is the tenant ID that FreeBusy will access for migrated accounts
-
Client secret – this is the secure access secret created for the App registration
-
Impersonation account – this is the tenant account that will be used for accessing scheduling information (eg BtFreeBusy@tenant.onmicrosoft.com). This account will require a mailbox.
Configuring an Azure AD App Registration:
First, navigate to the Office administration portal at https://portal.office.com and sign in with an admin account:
After signing in, click on the Admin button:
This takes you to the admin center for your Office 365 instance (already rebranded for Microsoft 365):
Click on the Azure Active Directory button to go to yet another admin page, this time for Azure AD for the instance:
Click on the All services button to list the services, one of which is App registrations:
Click on the App registrations button and you get here:
Click on the New registration button to load the following interface:
Set an appropriate Name (e.g. BTIntegration) and Supported account types. In the Redirect URI section, select Public client/native (mobile & desktop) and set the URI to:
urn:ietf:wg:oauth:2.0:oob
Next, click the Register button. Notice two of the four items needed for configuration, the Application (client) ID and the Directory (tenant) ID:
Notice when hovering over these two values, a copy icon will appear to copy the values with a single click:
Click this icon to copy the values before continuing.
Click on the API permissions button and click on Add a permission. Microsoft’s default permission for the Microsoft Graph API will appear.
After adding an API permission, click APIs my organization uses, type in Office 365, and select Office 365 Exchange Online:
In the next screen, select Application permissions; check the full_access_as_app box, and click Add Permissions:
Back in the API permissions screen, click the Grant admin consent for BTCorp36 checkmark button:
When the admin consent is granted, a green checkmark for the API permissions will appear. Now, click on Certificates & secrets in the Manage menu on the left:
In the Certificates & secrets screen, click on the New client secret button:
Give the secret a description and an expiration and click the Add button:
|
|
|
Now you have the third item, the client secret. Click the copy icon and save the client secret wherever you saved the application ID and directory ID:
|
|
|
Now you should be able to plug all these values into SetFBCred for the AvailabilityService, save the configuration, restart Free/Busy, and you should be using modern authentication:
Enable TLS 1.2 Connectivity
The Integration for Notes Free Busy process does support TLS 1.2. This requires the Windows Operating System to have recent patch updates and TLS 1.2 enabled on the Windows Server that hosts IIS along with Windows Server that hosts the Domino server for the FreeBusy deployment.
Valid Internet Certificates are required for the target system, self-signed certificates are not supported.
The target system should also support TLS 1.2 connections. If TLS 1.2 is enabled for FreeBusy but the target system does not have this enabled then the FreeBusy processing will fail. For support to configure TLS for IIS or Exchange a case should be raised with Microsoft, for Domino a case should be raised with HCL.
|
|
|
Windows Operating System Registry Updates:
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp]
“DefaultSecureProtocols”=Set the DWORD value to 800 for TLS 1.2.
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319]
"SchUseStrongCrypto"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319]
"SystemDefaultTlsVersions"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319]
"SchUseStrongCrypto"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319]
"SystemDefaultTlsVersions"=dword:00000001
Appendix D. Notes.ini File Parameters
The Notes.ini parameters required to configure FreeBusy are listed in blue, below:
BTCOEX_BYPASS_REQUESTOR
Accepted value = 0/1
Default = 0
This setting must be set to 1.
When set to 1, Exchange requests will use the credentials supplied by the BTCOEX_DEFAULT_FB_ACCESS_ACCOUNT parameter (described below). This is useful when Exchange is not supplying the user ID because it is set to OrgWideFB.
BTCOEX_DEFAULT_FB_ACCESS_ACCOUNT=<SMTP address>
The account specified will provide the access used by the entire Exchange organization for querying the Domino Availability Service. This account must be a Domino user with the Domain value set to the Foreign Domain in the Administrator Pre-install Checklist. This account must be allowed to see FreeBusy information for all users in the Domino environment.
BTCOEX_APPROVED_CALLERS=<IP addresses>
This comma separated list of IP addresses restricts the source of Free/Busy requests that will be processed by Domino FreeBusy. Legitimate requests would only come from servers known to the BT Coexistence install and trusted to have performed all necessary authentications prior to allowing OrgWideFB requests (e.g., 127.0.0.1,192.168.0.1).
Not providing a list of IP addresses for this setting is a potential security risk as the server would allow requests to come from any source.
BTCOEX_CACHE_EXCH_RESPONSE
Accepted value = <number of seconds to cache the response>
Default = 60
This command should be set in the Notes.ini; you can, however, manually set the FreeBusy caching, on-the-fly, using the following Domino console command:
tell btfreebusy cache n
n is the number of seconds to cache the response; 0 is also a valid value.
To turn the Exchange FreeBusy caching feature off, set the BTCOEX_CACHE_EXCH_RESPONSE parameter to a value of zero.
In addition, you may use the BTCOEX_DONT_CACHE_EXCH_RESPONSE parameter to turn the Exchange FreeBusy caching feature off. Specify 1 to indicate that the default value of 60 seconds should not be used.
BTCOEX_EXCHANGE_DOMAINS and BTCOEX_DOMINO _DOMAINS
Invitees in a Free/Busy request going to Exchange must be in a domain listed in the Notes.ini BTCOEX_EXCHANGE_DOMAINS variable.
Invitees in a Free/Busy request going to Domino must be in a domain listed in the Notes.ini BTCOEX_DOMINO_DOMAINS variable.
The following two Notes.ini variables are required (the below values are examples only):
-
BTCOEX_DOMINO_DOMAINS=BinaryTree,BTCMT,Domino
-
BTCOEX_EXCHANGE_DOMAINS=BinTreeEX,BTExchange,Exchange
FreeBusy checks requests coming from Exchange to make sure they are asking about users in the BTCOEX_DOMINO_DOMAINS.
FreeBusy checks requests going to Exchange to make sure they are asking about users in the BTCOEX_EXCHANGE_DOMAINS.
This is done to prevent an infinite loop of Free/Busy requests between the Exchange and Domino servers, which can happen when Exchange assumes that a particular SMTP address belongs to a Domino user, while Domino assumes that SMTP address belongs to an Exchange user.
If a list of domains is longer than 255 characters, the Notes.ini variables are contained in a series by appending a sequence number to the end of the variable name.
For example, if the original variable BTCOEX_DOMINO_DOMAINS contains more than 255 characters, the variables BTCOEX_DOMINO_DOMAINS1, BTCOEX_DOMINO_DOMAINS2, and so on, where each one provides up to a 255 character portion of the list of domains, will be used.
BTCOEX_SERVICE_TYPE
Accepted Value: COEX
Default Value: COEX
The BTCOEX_SERVICE_TYPE parameter specifies the Web Service format used by the FreeBusy IIS apps on the Windows Coex server to translate to the correct version of the EWS format.
The BTCOEX_SERVICE_TYPE parameter is set to COEX by default and should not be changed.
BTCOEX_LOG
Accepted Values: 0 or 8 (0=no logging to 8=all areas logging)
Default Value: 0
This controls which areas of FreeBusy should log information.
BTCOEX_SERVER_LOG
Accepted Values: 0-6 (0=no logging to 6=debug logging)
Default Value: 0
This logs incoming message processing done by the Domino Listener DSAPI filter to the <Domino Coex server>\logs\btserver.log file.
BTCOEX_CLIENT _LOG
Accepted Values: 0-6 (0=no logging to 6=debug logging)
Default Value: 0
This logs outgoing processing messages from the Domino Coex FreeBusy task to the <Domino Coex server>\logs\btclient.log file.
BTCOEX_STOP_AFTER_EXCEPTION
Accepted Values: 0, 1
Default Value: 0
This parameter controls whether FreeBusy will automatically restart if it encounters a fatal exception (error) that causes it to terminate.
If BTCOEX_STOP_AFTER_EXCEPTION is set to 1, FreeBusy will not restart after an error causes it to exit and it would need to be manually restarted.
If BTCOEX_STOP_AFTER_EXCEPTION = 0 (default), FreeBusy will restart after exiting due to an error.
BTCOEX_LOGDATA=15
This is a bit mask which controls both which data is log and where the data is logged. The value is the sum of the information you want to log and its location from the list below. Any combination of the values below can be used; the lowest value of this parameter can be “1”, the highest “15”.
1 = request
2 = response
4 = to console
8 = to file
BTCOEX_FB_TEST_POLLING
Accepted value = <number of minutes between heartbeat messages>
Default = 5
BTCOEX_FB_TEST_ACCOUNT
Accepted value = <SMTP address>
This is a recommended setting.
The SMTP address should be a valid Exchange account. It is passed from the Domino Coex server to IIS BTAvailability on the Windows Coex server.
If it is a valid Exchange account, IIS will send the request to Exchange, ensuring all servers are checked.
BTEXCHANGESERVER
Accepted value = <ExchangeSMTPDomain>
If a value for BTCOEX_FB_TEST_ACCOUNT is not provided, "fbtestaccount@” is prepended to this Exchange server name to create an SMTP address.
BTCOEX_NUM_POLLING_FAILS_BEFORE_MSG
Accepted value = <number of successive failures before sending a failure notification>
Default = 3
This parameter determines the number of successive FreeBusy failures before a notification is sent to the email account specified in BTMULTISCHEDREPORTADDRESS.
BTCOEX_MINUTES_BETWEEN_FAIL_MSGS
Accepted value = <number of minutes between failure notifications>
Default = 30
FreeBusy will send alerts to the account previously specified account until a successful test occurs. This parameter determines the interval between failure notifications, i.e. 30 minutes.
BTMULTISCHEDREPORTADDRESS
Accepted Value = <SMTP address>
Default = None
FreeBusy sends alerts to the address specified in this parameter.
The SMTP address should be a valid email address for a user or a group.
BTMULTISCHEDREPORTADDRESSTYPE
Accepted Value = 0/1/2
Default = 0
This parameter allows the user to specify whether the configured BTMULTISCHEDREPORTADDRESS should be placed in the To, CC, or BCC field when sending a mail notification. Acceptable values are as follows:
0 = To
1 = CC
2 = BCC
If the parameter is not included in the Notes.ini file or contains an unacceptable value then the address will appear in the To field as that is the default behavior.