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 1 will then appear:

    O365 Tenant Portal

    Figure 1 : The Office 365 tenant portal

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

    Select Admin Option

    Figure 2 : Selecting the Admin option

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

    Select Azure Active Directory

    Figure 3 : Selecting the Azure Active Directory option

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

    Select App Registrations

    Figure 4 : Selecting the App registrations option

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

    Click New Registrations

    Figure 5 : Clicking on the New registrations button

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

    Create a New Application

    Figure 6 : Creating a new application and registering it

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

    View Application Client ID

    Figure 7 : 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 8 that appears, and click the OK button therein.

    Set PFX File Password

    Figure 8 : 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 9. The right panel will change to display a Certificates section. Click on the Upload certificate link in Figure 9.

    Click Upload Certificate Link

    Figure 9 : Clicking the Upload certificate link

  2. Figure 10 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 Browse icon button in Figure 10 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.

    Upload Certificate

    Figure 10 : Uploading a certificate

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

    Details of Uploaded Certifcate

    Figure 11 : 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 12. 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 12.

    Click Add Permission

    Figure 12 : Clicking on the Add a permission link

  2. Figure 13 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 14). In the search text box (the box with the 'magnifying glass' icon within) in Figure 14, 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 15). Click on that API, and then select the Application permissions option (see Figure 15).

    Microsoft APIs Tab Page

    Figure 13 : The Microsoft APIs tab page

    Switch to APIs my Organization uses Tab

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

    Select Application Permissions Option

    Figure 15 : Selecting the Application permissions option

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

    Select Permission

    Figure 16 : Selecting the Exchange.ManageAsApp permission

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

    Grant Admin Consent

    Figure 17 : 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 18 appears, click on the Roles and administrators option in the left panel.

    Select Roles and Administrators

    Figure 18 : Selecting the Roles and administrators option

  2. Figure 19 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.

    Select Exchange Administrator Role

    Figure 19 : Selecting the Exchange administrator role

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

    Click Add Assignments Link

    Figure 20 : Clicking on the Add assignments link

  4. Figure 21 will then appear. Using the Search text box in Figure 21, 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.

    Select Application

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

  5. Figure 22 will then appear.

    Assign Role to Application

    Figure 22 : 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 23 will then appear.

    Certificate Import Wizard

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

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

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

    Confirm Installtion

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

  5. In Figure 25 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.

    Verify Location of PFX File

    Figure 25 : Verifying the location of the PFX file

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

    Specify Password

    Figure 26 : Specifying the password of the private key

  7. Figure 27 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 27. 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.

    Select Certificate Store

    Figure 27 : Allowing Windows to select the certificate store

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

    Finish Certificate Installation

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

    Successful Certificate Import Message

    Figure 29 : 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 30).

    Execute PowerShell Script

    Figure 30 : Executing the O365_CreateAppInfoDat.ps1 file

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

    Update Certificate Details

    Figure 31 : Capturing the certificate details

  4. In Figure 31, 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 7.

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

    • Finally, click the OK button in Figure 31.

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