How to create a custom Promodag app in Microsoft Entra ID

Note: This procedure cancels and replaces the one we published in November 2023. If you have already published your custom application in Microsoft Entra ID (Azure AD) and it is still assigned to the Global Reader role, go directly to step 6.

Promodag Reports now uses Certificate-Based authentication instead of the old User-Based authentication method . This requires that an application with the necessary permissions be created in Microsoft Entra ID and that you allow this application to interact with your tenant.

For your convenience Promodag has created an application that you can authorize to access your tenant. However, it is possible that your company's security policy requires you to create an application and a certificate yourself. Here's a manual procedure for doing so.

Step 1: Generate and export a self-signed certificate with PowerShell

The first step is to generate a self-signed x.509 certificate which will serve as an authentication between your application and Promodag Reports.

Open an elevated (run as administrator) Windows PowerShell session to create a self-signed certificate and export it to .cer and .pfx formats.

For example, here is how to create a self-signed certificate with the name “Promodag Reports App” with a validity period of two years from now on and P@ssw0rd1234 as password. The certificate will be stored in the personal store of the currently logged user.

$mycert = New-SelfSignedCertificate -CertStoreLocation "cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(2) -KeySpec KeyExchange -Subject "Promodag Reports Application"

Once created, export the certificate under a pfx format with the password P@ssw0Rd1234. The pfx certificate will be used by Promodag reports as well as the password.

$mycert | Export-PfxCertificate -FilePath promodagReports.pfx -Password $(ConvertTo-SecureString -String "P@ssw0Rd1234" -AsPlainText -Force)

Then export to a cer certificate file that will be used by your Azure application.

$mycert | Export-Certificate -FilePath promodagReports.cer

Step 2: Register a custom Promodag Reports Microsoft Entra ID application

1. Open the Microsoft Azure portal at https://portal.azure.com/.
2. Under Manage Microsoft Entra ID, click View.
3. On the Overview page that opens, under Manage, select App registrations.
4. On the App registrations page that opens, click + New registration.
5. On the Register an application page that opens, configure the following settings:
   a. Name: Enter something descriptive. For example, Promodag Reports AP.
   b. Supported account types: Verify that Accounts in this organizational directory only (<YourOrganizationName> only - Single tenant) is selected.
   When you're finished, click Register.
6. Copy the application ID into Notepad as you will need this information at the end of the procedure.
7. Leave the app page open. You'll use it in the next step.

Step 3: Assign the appropriate permissions to the application

1. On the app page under Manage, select API permissions.
2. Remove the Microsoft Graph > User.Read permission

Add the Microsoft Graph > User.Read.All permission.

• Click + Add a permission.
• In the Microsoft APIs tab select Microsoft Graph.
• Select Application permissions.
• Scroll down to User and select User.Read.All.
• Click the Add permissions button.

Add the Office 365 Exchange Online > Exchange.ManageAsApp and full_access_as_app permissions

• Click + Add a permission.
• In the APIs my organization uses tab, enter Office 365 Exchange Online in the search field.
• Select Office 365 Exchange Online.
• Select Application permissions.
• In Exchange, select Exchange.ManageAsAppl.
• In Other permissions, select full_access_as_app.
• Click the Add permissions button.

When you're finished, click Save.

Step 4: Approve the application in the Office 365 tenant

Check that the following permissions are displayed:

• Microsoft Graph : User.Read.All
•  Office 365 Exchange Online : Exchange.ManageAsApp and full_access_as_app.

Note: The details of each of these permissions are described here: Office 365 permissions. To revoke or remove some of them, see Remove or revoke specific permissions.

• Status column: The current incorrect value is Not granted for <Organization>, and this value needs to be changed.

Select Grant admin consent for <Organization>, read the confirmation dialog that opens, and then click Yes.

The value of the Status column should now be Granted for <Organization>.

Step 5: Import the certificate created in step 1

1. On the application page, under Manage, select Certificates & secrets.
2. On the Certificates & secrets page that opens, open the Certificates tab and click Upload certificate.
3. In the dialog that opens, browse to the self-signed certificate (.cer file) that you created in Step 1 and click Add.

Your application is now created.

Note: You can use your own certificate if required, and delete/update any existing one. See Replace or renew the certificate.

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

1. Open the Microsoft Azure 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 by application name field, enter the name of your custom Promodag Reports application.
6. In Properties, write down the Application ID and Object ID. This will be used later.

Step 7: 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 8: Create Management Role Assignment

In a PowerShell 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

Step 9: Apply the Promodag Reports 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 Azure application and the certificate.

of