Prerequisites to access the Azure Active Directory reporting API

  • 4 minutes to read

The Azure Active Directory (Azure AD) reporting APIs provide you with programmatic access to the data through a set of REST-based APIs. You can call these APIs from of programming languages and tools.

The reporting API uses OAuth to authorize access to the web APIs.

To prepare your access to the reporting API, you need to:

  1. Assign roles
  2. Register an application
  3. Grant permissions
  4. Gather configuration settings

Assign roles

To get access to the reporting data through the API, you need to have one of the following roles assigned:

  • Security Reader

  • Security Administrator

  • Global Administrator

Register an application

Registration is needed even if you're accessing the reporting API using a script. The registration gives you an Application ID, which is required for the authorization calls and enables your code to receive tokens.

To configure your directory to access the Azure AD reporting API, you must sign in to the Azure portal with an Azure administrator account that is also a member of the Global Administrator directory role in your Azure AD tenant.

Important

Applications running under credentials with administrator privileges can be very powerful, so please be sure to keep the application's ID and secret credentials in a secure location.

To register an Azure AD application:

  1. In the Azure portal, select Azure Active Directory from the left navigation pane.

    Register application

  2. In the Azure Active Directory page, select App registrations.

    Register application

  3. From the App registrations page, select New registration.

    Register application

  4. The Registration an Application page:

    Register application

    a. In the Name textbox, type Reporting API application.

    b. For Supported accounts type, select Accounts in this organizational only.

    c. In the Redirect URL select Web textbox, type https://localhost.

    d. Select Register.

Grant permissions

Depending on API you want to access, you need to grant your app the following permissions:

API Permission
Windows Azure Active Directory Read directory data
Microsoft Graph Read all audit log data

Register application

The following section lists the steps for both APIs. If you don't want to access one of the APIs, you can skip the related steps.

To grant your application permissions to use the APIs:

  1. Select API permissions then Add a permission.

    Register application

  2. On the Request API permissions page, locate Support legacy API Azure Active Directory Graph.

    Register application

  3. On the Required permissions page, select Application Permissions, expand Directory checkbox Directory.ReadAll. Select Add permissions.

    Register application

  4. On the Reporting API Application - API Permissions page, select Grant admin consent.

    Register application

  5. Note: Microsoft Graph is added by default during API Registration.

    Register application

Gather configuration settings

This section shows you how to get the following settings from your directory:

  • Domain name
  • Client ID
  • Client secret

You need these values when configuring calls to the reporting API.

Get your domain name

To get your domain name:

  1. In the Azure portal, on the left navigation pane, select Azure Active Directory.

    Register application

  2. On the Azure Active Directory page, select Custom domain names.

    Register application

  3. Copy your domain name from the list of domains.

Get your application's client ID

To get your application's client ID:

  1. In the Azure portal, on the left navigation pane, click Azure Active Directory.

    Register application

  2. Select your application from the App Registrations page.

  3. From the application page, navigate to Application ID and select Click to copy.

    Register application

Get your application's client secret

Avoid errors trying to access audit logs or sign-in using the API.

To get your application's client secret:

  1. In the Azure portal, on the left navigation pane, click Azure Active Directory.

    Register application

  2. Select your application from the App Registrations page.

  3. Select Certificates and Secrets on the API Application page, in the Client Secrets section, click + New Client Secret.

    Register application

  4. On the Add a client secret page, add:

    a. In the Description textbox, type Reporting API.

    b. As Expires, select In 2 years.

    c. Click Save.

    d. Copy the key value.

Troubleshoot errors in the reporting API

This section lists the common error messages you may run into while accessing activity reports using the MS Graph API and steps for their resolution.

500 HTTP internal server error while accessing Microsoft Graph V2 endpoint

We do not currently support the Microsoft Graph v2 endpoint - make sure to access the activity logs using the Microsoft Graph v1 endpoint.

Error: Failed to get user roles from AD Graph

Sign into your account using both sign-in buttons in the Graph Explorer UI to avoid getting an error when trying to sign in using Graph Explorer.

Graph Explorer

Error: Failed to do premium license check from AD Graph

If you run into this error message while trying to access sign-ins using Graph Explorer, choose Modify Permissions underneath your account on the left nav, and select Tasks.ReadWrite and Directory.Read.All.

Modify permissions UI

Error: Tenant is not B2C or tenant doesn't have premium license

Accessing sign-in reports requires an Azure Active Directory premium 1 (P1) license. If you see this error message while accessing sign-ins, make sure that your tenant is licensed with an Azure AD P1 license.

Error: The allowed roles does not include User.

Avoid errors trying to access audit logs or sign-in using the API. Make sure your account is part of the Security Reader or Report Reader role in your Azure Active Directory tenant.

Error: Application missing AAD 'Read directory data' permission

Error: Application missing MSGraph API 'Read all audit log data' permission

Follow the steps in the Prerequisites to access the Azure Active Directory reporting API to ensure your application is running with the right set of permissions.

Next steps