Certificate-based authentication to Office 365

If your company's security policy doesn't allow you to use an account and password to access Office 365 or if you use MFA, you can skip the User-based authentication mode and use the Certificate-based authentication mode instead. You can make this choice in the Configuration Wizard or in the Office 365 configuration tab of Tools > Options.

Create the certificate and the Promodag Reports Application

Please follow these steps to create the Promodag Reports Application, the certificate, register them in Microsoft Entra ID and create a dedicated role group in Exchange Admin Center:

Prerequisites

The computer’s operating version must be greater than or equal to Windows 10/Windows Server 2016. Microsoft PowerShell 7 or higher is required.

The ExchangeOnlineManagement and Microsoft.Graph PowerShell modules should be installed on the computer. It they are not, please proceed with these steps:

1. Click and search for PowerShell > Windows PowerShell 7 and run it as administrator.

2. Install the ExchangeOnlineManagement module: Install-Module ExchangeOnlineManagement -Scope AllUsers

3. Install the Microsoft.Graph module: Install-Module Microsoft.Graph -Scope AllUsers

Create the certificate and application using the provided script

These steps will enable you to create a self-signed certificate, an application in Microsoft Entra ID to access your tenant, and a role group in Exchange Admin Center.

1. The script is delivered by default in the C:\Users\Public\Documents\Promodag\Reports\ directory but you can use it from a different location.

2. Run the script: ./CreateRepexRBACApp.ps1
3. Enter certificate password at prompt and write it down.

4. 4. The script will proceed, and you will be prompted to sign-in to Office 365 to create the role group and grant it the relevant permissions. Use a Global Administrator account.

5. 5. A certificate valid for two years has now been created in the script directory with the name " RepexRBACAppCertificate.pfx". The application has been created in Microsoft Entra ID with the name "Promodag Reports RBAC Application", a role group with the name “Promodag Reports RBAC Role Group” has been created in Exchange Admin Center, a service principal object has been created for this new application and it has been added as a member of this new role group.

6. 6. The script displays the summary information to be used in Promodag Reports: Application ID and certificate path, plus a link (Authorization URL) to connect to Microsoft Entra ID and authorize the newly created application. This information is then saved into a file in the current directory.

Authorize this new application in Microsoft Entra ID

Grant admin consent

1. Paste the URL displayed in a web browser to connect to Microsoft Entra ID. Sign in using a Global Administrator account. The Promodag Reports RBAC Application | API permissions page opens.

2. Click Grant admin consent for <name of your Office 365 tenant>.
3. Review the permissions granted to the application (see details of each permission here: Office 365 permissions).
   

Optional: You can delete the self-signed certificate and use your own if you prefer. See Replace or renew the certificate.

Apply "Promodag Reports RBAC Application" settings to Promodag Reports

Please make sure that you have retrieved the following information the first step:

• Application ID,
• Certificate path,
• Certificate password.

1. In Promodag Reports, go to Tools > Options, Office 365 configuration.
2. Select Certificate-based authentication.
3. Enter the Application ID, Certificate file path and Certificate password in the corresponding fields.
4. Click the Check validity link to verify the certificate expiration date.  
5. Click the Check connection links to verify that Promodag Reports can connect to your tenant using the Microsoft Entra ID application and the certificate.

If you have already created the Promodag Reports application and wish to grant it minimum permissions

Step 1 Remove the Global Reader role

1. Open the Azure AD portal at https://portal.azure.com/.
2. Under Manage Microsoft Entra ID, click View.
3. On the Overview page that opens, under Manage, select Roles and administrators.
4. In the search field, enter the name of the Global Reader role.
5. Select the Global Reader role.
6. Remove the Promodag Reports Application from the assignments.

Step 2: Retrieve the Promodag Reports Microsoft Entra ID application identifiers

1. Open the Azure AD portal at https://portal.azure.com/.
2. Under Manage Microsoft Entra ID, click View.
3. On the Overview page that opens, under Manage, select Enterprise applications.
4. Uncheck Application type ==Enterprise Applications next to the Search by application name field.
5. In the search field, enter the name of the existing custom Promodag Reports application (default: “Promodag Reports Application”).
6. In Properties, write down the Application ID and Object ID. This will be used later.

Step 3: Create an Exchange Admin role group for Promodag Reports

1. Go to Microsoft 365 admin center, Exchange admin center.
2. Expand Roles on the left and click Admin roles.
3. Click Add role group.
4. In the New role group window that appears, enter “Promodag Reports role group” as the name of the role group along with a description.
5. Click Next.
6. In the Add permissions window, select View-Only Recipients and Mail Recipients.
7. Click Next.
8. Role group assignment will be performed in the next step. So, click Next again then Add role group to create the Role group.

Step 4: Create Management Role Assignment

In a PowerShell 7 window, connect to Exchange Online PowerShell.

Create a service principal object for the Promodag Reports Microsoft Entra ID application

$SP = New-ServicePrincipal -AppId <appId from step 6> -ObjectId <Object id from step 6> -DisplayName "SP for Promodag Reports Application"

Add the service principal as a member of the custom role group:

Add-RoleGroupMember -Identity “Promodag Reports role group” -Member $SP.Identity

Then go to Apply "Promodag Reports RBAC Application" settings to Promodag Reports.

of