Collect audit logs using a custom connector (deprecated)

Important

Using the dedicated Center of Excellence - Audit Log solution and the Office 365 Management custom connector to collect audit log events are deprecated. The solution and custom connector will be removed from the CoE Starter Kit in August 2023.

We have a new flow that collects audit log events, which is part of the Center of Excellence - Core Components solution. This new flow uses an HTTP connector. Learn more: Collect audit logs using an HTTP action

The Audit Log Sync flow connects to the Microsoft 365 audit log to gather telemetry data (unique users, launches) for apps. The flow uses a custom connector to connect to the Audit Log. In the following instructions, you set up the custom connector and configure the flow.

The Center of Excellence (CoE) Starter Kit works without this flow, but the usage information (app launches, unique users) in the Power BI dashboard will be blank.

Important

Complete the instructions in Before setting up the CoE Starter Kit and Set up inventory components before continuing with the setup in this article. This article assumes you have your environment set up and are signed in with the correct identity.

Only set up the Audit Log solution if you've chosen cloud flows as the mechanism for inventory and telemetry.

Watch a walk-through on how to set up the audit log connector.

Before you use the audit log connector

1. Microsoft 365 audit log search must be turned on for the audit log connector to work. More information: Turn audit log search on or off

2. The user identity running the flow must have permission to the audit logs. Minimum permissions for this are described here: Before you search the audit logs

3. Your tenant must have a subscription that supports unified audit logging. More information: Security & Compliance Center availability for business and enterprise plans

4. A Global Admin is required to configure the Microsoft Entra app registration.

The Office 365 Management APIs use Microsoft Entra ID to provide authentication services that you can use to grant rights for your application to access them.

Create a Microsoft Entra app registration for the Office 365 Management API

Using these steps, you set up a Microsoft Entra app registration that is used in a custom connector and Power Automate flow to connect to the audit log. More information: Get started with Office 365 Management APIs

1. Sign in to portal.azure.com.

2. Go to Microsoft Entra ID > App registrations.

   

3. Select + New Registration.

4. Enter a name (for example, Microsoft 365 Management), don't change any other setting, and then select Register.

5. Select API permissions > + Add a permission.

   

6. Select Office 365 Management API, and configure permissions as follows:

   1. Select Delegated permissions, and then select ActivityFeed.Read.

      

   2. Select Add permissions.

7. Select Grant Admin Consent for (your organization). Prerequisites: Grant tenant-wide admin consent to an application

   The API permissions now reflect delegated ActivityFeed.Read with a status of Granted for (your organization).

8. Select Certificates and secrets.

9. Select + New client secret.

   

10. Add a description and expiration (in line with your organization's policies), and then select Add.

11. Copy and paste the Secret to a text document in Notepad for the time being.

12. Select Overview, and copy and paste the application (client) ID and directory (tenant) ID values to the same text document; be sure to make a note of which GUID is for which value. You'll need these values in the next step as you configure the custom connector.

Leave the Azure portal open, because you'll need to make some configuration updates after you set up the custom connector.

Set up the custom connector

Now you'll configure and set up a custom connector that uses the Office 365 Management APIs.

1. Go to Power Apps > Dataverse > Custom Connectors. The Office 365 Management API custom connector is listed here; it has been imported with the core components solution.

2. Select Edit.

3. If your tenant is a commercial tenant, leave the General page as is.

   Important

   • If your tenant is a GCC tenant, change the host to manage-gcc.office.com.
   • If your tenant is a GCC High tenant, change the host to manage.office365.us.
   • If your tenant is a DoD tenant, change the host to manage.protection.apps.mil.

   More information: Activity API operations

4. Select Security.

5. Select Edit at the bottom of the OAuth 2.0 area to edit the authentication parameters.

   

6. Change the Identity Provider to Microsoft Entra ID.

   

7. Paste the application (client) ID you copied from the app registration into Client Id.

8. Paste the client secret you copied from the app registration into Client secret.

9. Don't change the Tenant ID.

10. Leave the Login URL as is for commercial and GCC tenants, and change it to https://login.microsoftonline.us/ for a GCC High or DoD tenant.

11. Set the Resource URL to https://manage.office.com for a commercial tenant, https://manage-gcc.office.com for a GCC tenant, https://manage.office365.us for a GCC High tenant, and https://manage.protection.apps.mil for a DoD tenant.

12. Select Update Connector.

13. Copy the Redirect URL into your text document in Notepad.

Note

If you have a data loss prevention (DLP) policy configured for your CoE Starter Kit environment, you'll need to add this connector to the business data–only group of this policy.

Update Microsoft Entra app registration with the redirect URL

1. Go to the Azure portal and your app registrations.

2. Under Overview, select Add a Redirect URI.

3. Select + Add a platform > Web.

4. Enter the URL you copied from the Redirect URL section of the custom connector.

5. Select Configure.

Start a subscription to audit log content

Go back to the custom connector to set up a connection to the custom connector and start a subscription to the audit log content, as described in the following steps.

Important

You must complete these steps for subsequent steps to work. If you don't create a new connection and test the connector here, setting up the flow and child flow in later steps will fail.

1. On the Custom Connector page, select Test.

2. Select + New connection, and then sign in with your account.

3. Under Operations, select StartSubscription.

   

4. Paste the directory (tenant) ID—copied earlier from the App Registration overview page in Microsoft Entra ID—into the Tenant field.

5. Paste the directory (tenant) ID into PublisherIdentifier.

6. Select Test Operation.

You should see a (200) status returned, which means the query was successful.

Important

If you have previously enabled the subscription, you will see a (400) The subscription is already enabled message. This means the subscription has successfully been enabled in the past. You can ignore this error and continue with the setup.

If you don't see the above message or a (200) response, the request may have failed. There could be an error with your setup that's keeping the flow from working. Common issues to check are:

• Validate that the identity provider on the Security tab is set to Microsoft Entra ID.
• Are audit logs enabled, and do you have permission to view the audit logs? Check by seeing if you can search in the Microsoft Compliance Manager.
• If you don't have permissions, see Before you search the audit log.
• Have you enabled the audit log very recently? If so, try again in a few minutes, to give the audit log time to activate.
• Have you pasted in the correct tenant ID from your Microsoft Entra app registration?
• Have you pasted in the correct resource URL, with no added spaces or characters at the end?
• Validate that you correctly followed the steps in Microsoft Entra app registration.
• Validate that you correctly updated the security settings of the custom connector, as described in step 6 of the custom connector setup procedure earlier in this article.

If you are still seeing failures, your connection may be in a bad state. Learn more: Step-by-step instructions to repair Audit Log connection

Set up the Power Automate flow

A Power Automate flow uses the custom connector, queries the audit log daily, and writes the Power Apps launch events to a Microsoft Dataverse table. This table is then used in the Power BI dashboard to report on sessions and unique users of an app.

1. Follow the instructions in Set up core components to download the solution.

2. Go to make.powerapps.com.

3. Import the Center of Excellence audit logs solution (CenterofExcellenceAuditLogs_x_x_x_xxx_managed.zip).

4. Establish connections to activate your solution. If you create a new connection, you must select Refresh. You won't lose your import progress.

   

5. Open the Center of Excellence – Audit Log solution.

6. Remove the unmanaged layer from the [Child] Admin | Sync Logs.

7. Select the [Child] Admin | Sync Logs.

8. Edit the Run only users settings.

   

9. For the Office 365 Management API custom connector, change the value to Use this connection (userPrincipalName@company.com). If there's no connection for any of the connectors, go to Dataverse > Connections, and create one for the connector.

   

10. For the Microsoft Dataverse connector, leave the run-only permission value blank and confirm that the connection reference for the CoE Audit Logs - Dataverse connection is configured correctly. If the connection is showing an error, update the connection reference for the CoE Audit Logs - Dataverse connection reference.

    

11. Select Save, and then close the Flow details tab.

12. (Optional) Edit the TimeInterval-Unit and TimeInterval-Interval environment variables to gather smaller chunks of time. The default value is to chunk 1 day into 1 hour segments. You receive an alert from this solution if the Audit Log fails to collect all data with your configured time interval.

    Name	Description
    StartTime-Interval	Must be a whole number to represent the start time for how far back to fetch. Default value: 1 (for one day back)
    StartTime-Unit	Determines units for how far back in time to go to fetch data. Must be a value from accepted as an input parameter to Add to Time. Example legal values: Minute, Hour, Day Default value: Day
    TimeInterval-Unit	Determines units for chunking the time since start. Must be a value from accepted as an input parameter to Add to Time. Example legal values: Minute, Hour, Day Default value: Hour
    TimeInterval-Interval	Must be a whole number to represent the number of chunks of type unit (above). Default value: 1 (for 1 hour chunks)
    TimeSegment-CountLimit	Must be a whole number to represent the limit on the number of chunks that can be created. Default value: 60

    Important

    The default values provided work in a medium-sized tenant. You may have to adjust the values multiple times for this to work for your tenant size.

    Important

    Learn how to update environment variables: Update Environment Variables

13. Back in the solution, turn on both the [Child] Admin | Sync Logs flow and the Admin | Sync Audit Logs flow.

    

Example configurations for environment variables

Here are example configurations for these values:

StartTime-Interval	StartTime-Unit	TimeInterval-Interval	TimeInterval-Unit	TimeSegment-CountLimit	Expectation
1	day	1	hour	60	Will create 24 child flows, which is within the limit of 60. Each child flow does the work to pull back 1 hour of logs from the past 24 hours
2	day	1	hour	60	Will create 48 child flows, which is within the limit of 60. Each child flow does the work to pull back 1 hour of logs from the past 48 hours
1	day	5	minute	300	Will create 288 child flows, which is within the limit of 300. Each child flow does the work to pull back 5 minutes of logs from the past 24 hours
1	day	15	minute	100	Will create 96 child flows, which is within the limit of 100. Each child flow does the work to pull back 15 minutes of logs from the past 24 hours

How to get older data

This solution collects app launches from the moment it's configured, and isn't set up to collect historic app launches. Depending on your Microsoft 365 license, historic data will be available for up to a year using the audit log in Microsoft Purview.

You can load historic data into the CoE Starter Kit tables manually. Learn more: How to import old Audit Logs

I found a bug with the CoE Starter Kit; where should I go?

To file a bug against the solution, go to aka.ms/coe-starter-kit-issues.