Manually Enabling Certificate-based Authentication For an Office 365 Tenant

The broad steps for achieving this are as follows:

  1. Create a new application on Azure AD for the purpose of enabling certificate-based authentication.

  2. Create a self-signed X.509 certificate.

  3. Upload the certificate to the Office 365 cloud for secure communication.

  4. Grant the Exchange.ManageAsApp permission to the new application in the Office 365 Exchange Online API.

  5. Assign the Exchange Administrator role to the new application

  6. Install the certificate on the system hosting the eG agent

  7. Capture the ID of the new application and the certificate thumbprint into a *.dat file.

  8. Configure the eG tests for Office 365 components with the name of the tenant for which certificate-based authentication has been enabled. The tests will then read the Application ID and Certificate Thumbprint of that tenant from the .dat file. Using this access information, the eG tests will then communicate with and pull metrics related to the target tenant and its resources.

The sections that follow will discuss steps 1-7, elaborately.

Creating a New Application on Azure AD for Certificate-based Authentication

To achieve this, follow the steps detailed below:

  1. Login to the Office 365 portal as a user with Global Administrator rights to the Office 365 tenant being monitored. Figure 139 will then appear:

    Figure 139 : The Office 365 tenant portal

  2. Click on the icon at the left top corner of Figure 139. This will invoke the menu options depicted by Figure 140. Select the Admin option from the menu.

    Figure 140 : Selecting the Admin option

  3. Figure 141 will then appear. Select the Azure Active Directory option from Figure 141.

    Figure 141 : Selecting the Azure Active Directory option

  4. This will open Figure 142. From the left panel of the Overview page of Figure 142, select the App registrations option.

    Figure 142 : Selecting the App registrations option

  5. Figure 143 then appears. To create a new application, click on the New registrations link in the right panel of Figure 143.

    Figure 143 : Clicking on the New registrations button

  6. This will open Figure 144. Under Name, specify the name for the new application you are creating. Then, click the Register button in Figure 144 to register a new application on Azure AD with the specified name.

    Figure 144 : Creating a new application and registering it

  7. Once the application is successfully created, Figure 145 will appear. Make a note of the Application (client) ID displayed in Figure 145.

    Figure 145 : Making a note of the Application (client) ID

Creating an X.509 Certificate

The next step is to create and configure a self-signed X.509 certificate, which will be used to authenticate the application you have created against Azure AD, while requesting the app-only access token.

Follow the steps below to create the self-signed certificate:

  1. First, log into the system hosting the eG agent.

  2. To enable you to automatically generate a self-signed certificate, eG provides a proprietary powershell cmdlet. To run this cmdlet, open the Windows PowerShell ISE as 'administrator', and run the O365GenerateCertificate.ps1 script in the <EG_AGENT_INSTALL_DIR>\lib directory.
  3. The self-signed certificate that this cmdlet creates will be available as a .cer file and as a .pfx file in the <EG_AGENT_INSTALL_DIR>\agent\O365\AppInfo directory. To make sure that the certificate allows secure access to a tenant's resources, you need to protect the .pfx certificate file using a password. Set this PFX File Password using Figure 146 that appears, and click the OK button therein.

    Figure 146 : Setting the PFX file password

Uploading the Certificate to the Office 365 Cloud

Next, proceed to upload the .cer certificate file on the eG agent host to Office 365. For this, do the following:

  1. Click on the Certificates and Secrets option in the left panel of Figure 147. The right panel will change to display a Certificates section. Click on the Upload certificate link in Figure 147.

    Figure 147 : Clicking the Upload certificate link

  2. Figure 148 will then appear. In the Select a file text box, specify the full path to the .cer file that was automatically created previously using the O365GenerateCertificate.ps1 script. You can use the button in Figure 148 to quickly browse and locate the certificate file. Note that you will find the .cer file and the .pfx file in the <EG_AGENT_INSTALL_DIR>\agent\O365\AppInfo directory.

    Figure 148 : Uploading a certificate

  3. Figure 149 will then appear. Make a note of the certificate Thumbprint displayed in Figure 149.

    Figure 149 : Details of the uploaded certificate, including its thumbprint

Granting Permissions to the New App in the Office 365 Exchange Online API

For this, do the following:

  1. Click on the API permissions option in the left panel of Figure 150. The right panel will then change to display pre-set API permissions. To grant new permissions, click on the Add a permission link in the right panel of Figure 150.

    Figure 150 : Clicking on the Add a permission link

  2. Figure 151 will then appear. Keep scrolling down the Microsoft APIs tab page (which you can see in the right panel of Figure 151), until you find the Office 365 Exchange Online API (see Figure 152). Click on that API, and then select the Application permissions option (see Figure 152).

    Figure 151 : Scrolling down the Microsoft APIs tab page

    Figure 152 : Selecting the Application permissions option

  3. Next, scroll down the Select permissions section of Figure 152, until you find the Exchange.ManageAsApp permission. Select that permission and click on the Add permissions button (see Figure 153).

    Figure 153 : Selecting the Exchange.ManageAsApp permission

  4. Figure 154 then appears displaying the selected permission. Here, click on the Grant admin consent link.

    Figure 154 : Granting admin consent to the selected permission

Assigning the Exchange Administrator role to the New Application

Follow the steps below to achieve this:

  1. Go to the Azure Active Directory Admin Center (by following steps 1 - 4 detailed in Creating a New Application on Azure AD for Certificate-based Authentication). When Figure 155 appears, click on the Roles and administrators option in the left panel.

    Figure 155 : Selecting the Roles and administrators option

  2. Figure 156 will then appear. Use the Search text box here to look for 'exchange' roles. From the search results, pick the Exchange administrator role by clicking on the check box alongside.

    Figure 156 : Selecting the Exchange administrator role

  3. When Figure 157 appears, click on the Add assignments link.

    Figure 157 : Clicking on the Add assignments link

  4. Figure 158 will then appear. Using the Search text box in Figure 158, search for the application you created in Creating a New Application on Azure AD for Certificate-based Authentication. Scroll down the search results to locate that application. Once you find the application, select it by clicking on it.

    Figure 158 : Selecting the new application to which the Exchange administrators role is to be assigned

  5. Figure 159 will then appear.

    Figure 159 : Assigning the Exchange administrators role to the new application created for the purpose of certificate-based authentication

Installing the Certificate on the eG Agent Host

For this do the following:

  1. As mentioned already, the certificate that is auto-generated using the O365GenerateCertificate.ps1 script will be available as a .cer and as a .pfx file in the <EG_AGENT_INSTALL_DIR>\agent\O365\AppInfo directory.

  2. To install the PFX certificate on the agent host, navigate to the <EG_AGENT_INSTALL_DIR>\agent\O365\AppInfo directory on the agent host (using Windows Explorer), right-click on the PFX file therein, and select Install PFX. Figure 160 will then appear.

    Figure 160 : Selecting Local Machine as Store Location in the Certificate Import Wizard

  3. Set Local Machine as the Store Location in Figure 160 and click the Next button.

  4. This will invoke Figure 161. Click on Yes here to proceed..

    Figure 161 : A message seeking your confirmation to proceed with the installation

  5. In Figure 162 that then appears, the path to the PFX file to be installed will by default be displayed in the File name text box. Verify the location of the file, and if it is correct, click on the Next button to proceed.

    Figure 162 : Verifying the location of the PFX file

  6. Figure 163 will then appear. In the Password text box of Figure 163, enter the same PFX File Password you specified in Figure 146 above. Then, click the Next button.

    Figure 163 : Specifying the password of the private key

  7. Figure 164 will then appear. Here, you need to indicate where the certificate needs to be stored. Select the Automatically select the certificate store based on the type of certificate option in Figure 164. If this option is chosen, then Windows will automatically select a certificate store where the certificate will be stored. Then, click the Next button to move on.

    Figure 164 : Allowing Windows to select the certificate store

  8. When Figure 165 appears, click the Finish button here to end the installation.

    Figure 165 : Finishing the certificate installation

  9. If the certificate is successfully imported to the agent host, a message to that effect will appear. Click the OK button here to exit the wizard.

    Figure 166 : A message indicating the certificate import is successful

Capturing Certificate Details into a File

To achieve this, do the following:

  1. Login to the system hosting the eG agent.

  2. Open the Windows PowerShell ISE as 'administrator', and run the O365_CreateAppInfoDat.ps1 script in the <EG_AGENT_INSTALL_DIR>\lib directory (by clicking on the button indicated by Figure 167).

    Figure 167 : Executing the O365_CreateAppInfoDat.ps1 file

  3. Upon successful script execution, Figure 168 will appear.

    Figure 168 : Capturing the certificate details

  4. In Figure 168, specify the following:

    • App Name: Specify the name of the new application you created using the procedure detailed in Creating a New Application on Azure AD for Certificate-based Authentication.

    • App ID: Enter the ID of the new application. Here, mention the Application (client) ID that you see in Figure 145.

    • Org Name: Specify the name of the tenant for which certificate-based authentication has been enabled. To know the tenant name, do the following:

      • Log in to the Microsoft 365 Admin Center as an administrator.

      • Under Setup, click on Domains.

      • Find a domain that ends with .onmicrosoft.com - this is your Microsoft O365 tenant name

    • Certificate Thumbprint: Specify the thumbprint of the certificate you uploaded to Office 365. Here, specify the Thumbprint you see in Figure 149.

    • Finally, click the OK button in Figure 168.

  5. The details you provide in Figure 168 will be automatically captured into an AppDetails.dat file. The powershell script will create this file in the <EG_AGENT_INSTALL_DIR>\egurkha\agent\O365 directory. Once you configure eG tests with a Tenant Name, then the test will read the certificate details that correspond to that tenant from this file. Using these access details, the test will communicate with and pull metrics related to that tenant and its resources.

Note:

To make sure that every eG agent that monitors an O365 component uses certificate-based authentication, copy the AppDetails.bat file that gets automatically created at step 5 to the <EG_AGENT_INSTALL_DIR>\agent\O365 diirectory of every such agent.