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 Microsoft Entra 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 in the Office 365 Exchange Online API add Sites.FullControl.All permission in Office 365 SharePoint Online API to the new application.

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 Microsoft Entra 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. When Figure 1 appears, click on the icon at its left top corner. This will invoke the menu options depicted by Figure 1. Select the Admin option from the menu.

   

   Figure 1 : Selecting the Admin option

2. Figure 2 will then appear. Select the Identity option from Figure 2.

   

   Figure 2 : Selecting the Azure Active Directory option

3. This will open Figure 3. From the left panel of the Overview page of Figure 3, select the App registrations option. To create a new application, click on the New registrations link in the right panel of Figure 3.

   

   Figure 3 : Clicking on the New registrations button

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

   

   Figure 4 : Creating a new application and registering it

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

   

   Figure 5 : 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 Microsoft Entra, 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 script. To run this script, 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 script 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 6 that appears, and click the OK button therein.

   

   Figure 6 : 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 Entra application. For this, do the following:

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

   

   Figure 7 : Clicking the Upload certificate link

2. Figure 8 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 8 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 8 : Uploading a certificate

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

   

   Figure 9 : 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 10. 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 10.

   

   Figure 10 : Clicking on the Add a permission link

2. Figure 11 will then appear, with the Microsoft APIs tab page selected by default. Switch to the APIs my organization uses tab page by clicking on it (see Figure 12). In the search text box (the box with the 'magnifying glass' icon within) in Figure 12, type office. All APIs with names that start with the string, office, will then be listed under the text box. Keep scrolling down the list until you find the Office 365 Exchange Online API (see Figure 13). Click on that API, and then select the Application permissions option (see Figure 13).

   

   Figure 11 : The Microsoft APIs tab page

   

   Figure 12 : Switching to the APIs my organization uses tab page and selecting the Exchange Online API

   

   Figure 13 : Selecting the Application permissions option

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

   

   Figure 14 : Selecting the Exchange.ManageAsApp permission

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

   

   Figure 15 : Granting admin consent to the selected permission

5. Similarly, switch to the Office 365 SharePoint Online API, select Application permissions option, and assign the Sites.FullControl.All permission to the app. Then, Grant admin consent to the selected permission as well.

Assigning the Exchange Administrator role to the New Application

Follow the steps below to achieve this:

1. Go to the Microsoft Entra Admin Center, and click on the Roles and admins option in the left panel (see Figure 16).

   

   Figure 16 : Selecting the Roles and administrators option

2. Figure 17 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 17 : Selecting the Exchange administrator role

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

   

   Figure 18 : Clicking on the Add assignments link

4. Figure 19 will then appear. Using the Search text box in Figure 19, search for the application you created in Creating a New Application on Microsoft Entra 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 19 : Selecting the new application to which the Exchange administrators role is to be assigned

5. Figure 20 will then appear.

   

   Figure 20 : 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 .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 21 will then appear.

   

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

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

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

   

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

5. In Figure 23 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 23 : Verifying the location of the PFX file

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

   

   Figure 24 : Specifying the password of the private key

7. Figure 25 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 25. 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 25 : Allowing Windows to select the certificate store

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

   

   Figure 26 : 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 27 : 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 28).

   

   Figure 28 : Executing the O365_CreateAppInfoDat.ps1 file

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

   

   Figure 29 : Capturing the certificate details

4. In Figure 29, specify the following:

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

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

   • 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 9.

   • Finally, click the OK button in Figure 29.

5. The details you provide in Figure 29 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.

6.  

Note:

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