Edit

Share via

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 is 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 in Collect audit logs by using the Office 365 Management API.

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 is then blank.

Prerequisites

Before you use the audit log connector

  1. Microsoft 365 audit log search must be turned on for the audit log connector to work. Learn more in Turn auditing on or off.

  2. The user identity running the flow must have permission to the audit logs. Minimum permissions are described in Before you search the audit log.

  3. Your tenant must have a subscription that supports unified audit logging. Learn more in Microsoft 365 guidance for security & compliance.

  4. Microsoft Entra permissions might be required to configure the Microsoft Entra app registration. Depending on your Entra configuration, you need the Application Developer role or higher. Review the least privileged roles by task in Microsoft Entra ID for more guidance.

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

Follow these steps to set up a Microsoft Entra app registration that you can use in a custom connector and Power Automate flow to connect to the audit log. Learn more in Get started with Office 365 Management APIs.

  1. Sign in to the Azure portal.

  2. Go to Microsoft Entra ID > App registrations.

    Screenshot that shows the Microsoft Entra app registration.

  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.

    Screenshot that shows 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.

      Screenshot that shows delegated permissions.

    2. Select Add permissions.

  7. Select Grant Admin Consent for (your organization). Review prerequisites in 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 when you configure the custom connector.

  13. 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

Next, 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. The connector is imported with the core components solution.

  2. Select Edit.

  3. If your tenant is a commercial tenant, don't change anything on the General page.

    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.

    Learn more in Activity API operations.

  4. Select Security.

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

    Screenshot that shows how you can edit the OAuth 2.0 section of Security tab of Custom connectors.

  6. Change the Identity Provider to Microsoft Entra ID.

    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. However, for a GCC High or DoD tenant, change the URL to https://login.microsoftonline.us/.

  11. Set the Resource URL:

    Tenant type URL
    Commercial https://manage.office.com
    GCC https://manage-gcc.office.com
    GCC High https://manage.office365.us
    DoD https://manage.protection.apps.mil

  12. Select Update Connector.

  13. Copy the Redirect URL into a text document, such as Notepad.

Note

If you have a data policy configured for your CoE Starter Kit environment, 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 and 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 fails.

  1. On the Custom Connector page, select Test.

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

  3. Under Operations, select StartSubscription.

    Screenshot that shows the custom connector Start Subscription.

  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.

Screenshot that shows a successful status returned from the StartSubscription activity.

Important

If you previously enabled the subscription, you see a (400) The subscription is already enabled message. This message means the subscription is already enabled. Ignore this error and continue with the setup.

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

  • The identity provider on the Security tab should be set to Microsoft Entra ID.
  • Audit logs should be enabled and you have permission to view them. Check your access by searching the Microsoft Purview Compliance Manager.
  • If you don't have permissions, review Before you search the audit log.
  • If you enabled the audit logs recently, try searching again in a few minutes to give the audit log time to activate.
  • The tenant ID from your Microsoft Entra app registration should be correct.
  • Your resource URL should have no added spaces or characters at the end.
  • Review the steps in your Microsoft Entra app registration for correctness.
  • The security settings of the custom connector, as described in step 6 of the custom connector setup, should be updated correctly.

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

Set up the Power Automate flow

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

  1. Download the solution in Set up core components.

  2. Go to make.powerapps.com.

  3. Import the Center of Excellence audit logs solution by using the CenterofExcellenceAuditLogs_*x_x_x_xxx*_managed.zip file.

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

    Screenshot that shows how to import the CoE audit log components solution.

  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.

    Child flow - run-only users.

  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.

    Screenshot that shows where to find the Configure run-only users selection.

  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 shows an error, update the connection reference for the CoE Audit Logs - Dataverse connection reference.

    Screenshot that shows where to check 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 accepted as an input parameter to Add to Time. Example legal values: Minute, Hour, Day. Default value is Day.
    TimeInterval-Unit Determines units for chunking the time since start. Must be a value accepted as an input parameter to Add to Time. Example legal values: Minute, Hour, Day. Default value is Hour.
    TimeInterval-Interval Must be a whole number to represent the number of chunks of type unit. Default value is 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 is 60.

    Tip

    These default values work in a medium-sized tenant. You might need to adjust the values multiple times to make them work for your tenant size.

    Learn more in 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 Create 24 child flows, which is within the limit of 60. Each child flow pulls back 1 hour of logs from the past 24 hours.
2 day 1 hour 60 Create 48 child flows, which is within the limit of 60. Each child flow pulls back 1 hour of logs from the past 48 hours.
1 day 5 minute 300 Creates 288 child flows, which is within the limit of 300. Each child flow pulls back 5 minutes of logs from the past 24 hours.
1 day 15 minute 100 Create 96 child flows, which is within the limit of 100. Each child flow pulls back 15 minutes of logs from the past 24 hours.

How to get older data

Once configured, this solution collects app launches, but isn't set up to collect historic app launches. Depending on your Microsoft 365 license, historic data is available for up to one year using the audit log within Microsoft Purview.

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

How to file an issue

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

  • Last updated on