Automatically Fulfilling Pre-requisites in a Modern Authentication-Enabled Environment

To ensure that the pre-requisites discussed in Pre-requisites for Monitoring Office 365 Environments where Modern Authentication is Enabled are fulfilled without a glitch, eG Enterprise provides a proprietary PowerShell script. By running this script, you can have these requirements automatically fulfilled. This way, you can eliminate the effort and time involved, and minimize the likelihood of errors in getting Office 365 monitoring up and running.

To run the script, do the following:

  1. Login to the eG agent host.

  2. Open Windows PowerShell ISE in elevated mode.

  3. Run the O365_setup_prerequisites.ps1 script from the <EG_AGENT_INSTALL_DIR>\lib directory.

  4. Figure 1 will then appear, where you need to indicate how you want to connect to Office 365 - using basic authentication or modern authentication.

    Figure 1 : Choosing between Modern Authentication and Basic Authentication

  5. To use modern authentication to connect to Office 365, click the Yes button in Figure 1.
  6. You will now be prompted to confirm whether/not you want to install the PowerShell modules/packages required for monitoring, on the eG agent host. Click Yes to confirm.   

    Figure 2 : A messaging prompting you to confirm whether/not PowerShell modules are to be installed on the agent host

  7. Figure 3 will then appear. Click Yes in Figure 3 to download the Microsoft Online Services Sign-in Assistant.

    Figure 3 : Choosing to download the sign-in assistant

  8. When Figure 4 appears, click Yes to install the downloaded sign-in assistant on the agent host.

    Figure 4 : Choosing to install the downloaded sign-in assistant

  9. Clicking Yes in Figure 4 will invoke a wizard that will guide you through the sign-in assistant's installation. Click Next here to move to the next step of the installation.

    Figure 5 : Welcome screen of the sign-in assistant's installation wizard

  10. Then, select the 'I agree...' check box that you see in Figure 6 to agree to the licensing terms and conditions, and click Install to the install the sign-in assistant.

    Figure 6 : Agreeing to the sign-in assistant's licensing terms

  11. If installation is successful, Figure 7 will appear. Click Finish here to exit the wizard.

    Figure 7 : Exiting the wizard after successful installation of the sign-in assistant

  12. Figure 8 will appear now. Here, first, choose the O365 products/components that you want to monitor by selecting the relevant check boxes in the Components to be monitored section. The script will automatically download and install only those packages that are required for monitoring the chosen components.

    Figure 8 : Choosing the Office 365 products/components that you want to monitor

  13. After the packages are installed, the script automatically communicates with the Office 365 portal to verify whether/not the installation was successful. If all communications between the eG agent host and the Office 365 portal are routed through a proxy server, then you need to provide the details of that server in the Proxy Details section, so that the script that resides on the agent host is able to connect to the portal. In this case, specify the Host IP an Port number of the proxy server in the Proxy Details section. If the proxy requires authentication, then specify the Username and Password of a valid proxy user as well. On the other hand, if the agent host does not communicate with the Office 365 portal via a proxy server, specify none in all text boxes in the Proxy Details section.

  14. Finally, click the OK button in Figure 8.

  15. Figure 9 will then appear. Click Yes here to download the Skype for Business Network Assessment Tool.

    Figure 9 : A message requesting your confirmation to download the Skype for Business Network Assessment Tool

  16. When Figure 10 appears, click Yes again to install the downloaded tool.

    Figure 10 : Enabling the installation of the downloaded Skype for Business Network Assessment Tool

  17. Clicking Yes in Figure 10 will invoke a wizard (see Figure 11), which will help you install the Business Network Assessment Tool. Select the "I agree...' check box in Figure 10 that appears to agree to the licensing terms of the tool. Then, click Install to begin installing the tool.

    Figure 11 : Installing the Skype for Business Network Assessment Tool

  18. Once the tool is installed, Figure 12 will appear, prompting you to confirm whether/not certificate-based authentication is to be enabled. Click Yes to confirm the same.

    Figure 12 : A message box requesting your confirmation to enable certificate-based authentication

  19. Figure 13 will then appear. To automatically enable certificate-based authentication, the script first needs to connect to the Office 365 portal. If the eG agent host, where the script resides, communicates with Office 365 via a proxy server, then you need to provide the details of the proxy server in the Proxy Details section of Figure 13. Using these details, the script will be able to establish a connection with Office 365. In this case therefore, specify the Host IP and Port number of the proxy server in the Proxy Details section. If the proxy requires authentication, then provide the Username and Password of a valid proxy user as well, in this section. On the other hand, if the agent host is not communicating via a configure all the settings required by the Proxy Details section with none.

    Figure 13 : Assigning roles and permissions to a new Office 365 user

  20. Certificate-based authentication, once enabled, results in the creation of a PFX certificate file on the eG agent host. To protect this file, you should set a secure password for it. Specify this password in the PFX File Password text box in Figure 13.
  21. Some of the tests executed by the eG agent may use modern authentication to connect to Office 365, but may emulate user operations (using Microsoft Graph API) or mock a user's browser access for metrics collection. Because they support modern authentication, these tests will not need user credentials for connecting to Office 365. However, after the connection is established, the tests will be able to gather the required metrics only if certain additional pre-requisites are fulfilled. These tests and their additional requirements are detailed in Pre-requisites for Monitoring Office 365 Environments where Modern Authentication is Enabled topic . A few of these tests need the credentials of a user with Teams Administrator permission and who is assigned a valid Office 365 license for Microsoft Teams subscription and Exchange Online Mailbox subscription. Follow the steps below to fulfill this requirement:

    • To automatically create a new user and assign the required license to that user, select the New User option in the eG Monitoring User Credentials section (see Figure 13). Then, specify the name and password of the new user in the Monitoring User and Monitoring Password text boxes in Figure 13.

    • Alternatively, you can use an existing Office 365 user account for this purpose. In this case, select the Existing User option in the eG Monitoring User Credentials section. Then, specify the name of the existing Monitoring User and the Monitoring Password of that user.

    • Finally, click the OK button. Figure 14 will then appear. Using Figure 14, login to Office 365 as a user with Global Administrator credentials.

      Figure 14 : Logging into Microsoft Office 365 using global administrator credentials

    • Figure 15 will appear. Select the license for the Microsoft Teams and Exchange Online Mailbox subscription, and click the OK button to assign that license to the new user or existing user you specified in Figure 13.

      Figure 15 : Assigning the license to the new/existing Offce 365 user

  22. With that, you will exit the script. In summary, the script automatically performs the following tasks:

    • Creates a new application on Azure AD for the purpose of enabling certificate-based authentication;
    • Creates a self-signed PFX certificate file in the <EG_AGENT_INSTALL_DIR>\agent\O365\AppInfo directory on the eG agent host;
    • Uploads the certificate to the Office 365 cloud for secure communication;
    • Grants the Exchange.ManageAsApp permission to the new application in the Office 365 Exchange Online API;
    • Assigns the Exchange Administrator role to the new application;
    • Installs the certificate on the system hosting the eG agent
    • Captures the ID of the new application and the certificate thumbprint into the AppDetails.dat file in the <EG_AGENT_INSTALL_DIR>\agent\O365\AppInfo
    • Registers an Microsoft Graph App with Azure Active Directory, and auto-assigns all the permissions required for monitoring to that app.

    • Creates an MSGraph folder in the <EG_AGENT_INSTALL_DIR>\agent\O365 directory containing the details for connecting to the MS Graph App mentioned above;

    • Creates a new user with Team Administrator permissions on Office 365 , and assigns a license to that user for the Microsoft Teams and Exchange Online Mailbox subscriptions, (OR)

      Assigns the aforesaid license to an existing user with Team Administrator permissions.

  23. After the script successfully executes, login to the Office 365 portal and select the Azure Active Directory option.
  24. Next, select the new application that the script created in Azure AD and pick the View API Permissions or API Permissions option.
  25. Finally, click the Grant admin consent for button to grant “admin consent” for delegated permissions (see Figure 16).

    Figure 16 : Granting admin consent to the new application in Azure AD

  26. In environments where hundreds of users connect to Office 365, it is common-place to configure multiple agents to monitor a single Office 365 tenant for the purpose of load-balancing - e.g., you can have one agent that monitors Exchange Online alone for that tenant, and another that monitors SharePoint Online alone. In such environments, it would suffice to run this script on any one agent that monitors the target Office 365 tenant. This is because, enabling certificate-based authentication and MS Graph App registration are one-time exercises, which need to be performed only once for a target Office 365 tenant, regardless of the number of agents monitoring that tenant. However, in such environments, after running this script on an eG agent host, you should make sure that the MSGraph and AppInfo folders are copied to the <EG_AGENT_INSTALL_DIR>\agent\O365\ directory of every other agent that has been configured to monitor the target Office 365 tenant. If these folders are not copied to the other eG agents as well, then none of these agents will be able to report metrics using modern authentication