Edit

Quickstart: Configuring Microsoft Entra for a custom connector

  • Article

This guide describes the steps to configure a Microsoft Entra application for use with a Power Query custom connector. We recommend that connector developers review the concepts of the Microsoft identity platform before proceeding.

Since the application term is used in multiple contexts in the Microsoft Entra platform, this guide uses the following terms to distinguish between connector and data source application IDs:

  • Client application: The Microsoft Entra client IDs that are used by the Power Query connector.
  • Resource application: The Microsoft Entra application registration for the endpoint the connector connects to (that is, your service, or data source).

Enabling Microsoft Entra support for a custom connector involves:

  • Defining one or more scopes in the resource application that's used by the connector.
  • Preauthorizing the Power Query client IDs to use those scopes.
  • Setting the correct Resource and Scopes values in the connector definition.

This guide assumes a new resource application is registered in Microsoft Entra. Developers with an existing resource application can skip to the Configure a Scope section.

Note

For more details on using Microsoft Entra in your service or application, go to one of the Quickstart guides.

Register the resource application

Your data source or API endpoint uses this resource application to establish trust between your service and the Microsoft identity platform.

Follow these steps to register a new resource application:

  1. Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
  2. Browse to Identity > Applications > App registrations and select New registration.
  3. Enter a display Name for your application.
  4. For Supported account types, select Accounts in this organizational directory only if your endpoint is only accessible from within your organization. Select Accounts in any organizational directory for publicly accessible, multitenant services.
  5. Select Register.

You don't need to specify a Redirect URI value.

The application's Overview page is displayed when the registration is complete. Take note of the Directory (tenant) ID and the Application (client) ID values as they'll be used in your service's source code. Follow one of the guides in the Microsoft identity platform code samples that resembles your service environment and architecture to determine how to configure and make use of your new application.

Set an Application ID URI

Before you can configure a scope for your endpoint, you must set an Application ID URI for your resource application. This ID will be used by the Resource field of the Aad record in your connector. The value is set to the root URL of your service. You can also use the default generated by Microsoft Entra - api://{clientId} - where {clientId} is your resource application's client ID.

  1. Go to the resource application's Overview page.
  2. On the center screen, under Essentials, select Add an application ID URI.
  3. Enter a URI or accept the default based on your app ID.
  4. Select Save and continue.

The examples in this guide assume you're using the default Application ID URI format (for example - api://44994a60-7f50-4eca-86b2-5d44f873f93f).

Configure a Scope

Scopes are used to define permissions or capabilities to access APIs or data in your service. The list of supported scopes are service specific. You want to determine a minimal set of scopes required by your connector. You need to preauthorize at least one scope for the Power Query client IDs.

If your resource application already has scopes defined, you can skip to the next step.

If your service doesn't use scope based permissions, you can still define a single scope that's used by the connector. You can (optionally) make use of this scope in your service code in the future.

In this example, you define a single scope called Data.Read.

  1. Go to the resource application's Overview page.
  2. Under Manage, select Expose an API > Add a scope.
  3. For Scope name, enter Data.Read.
  4. For Who can consent, select the Admins and users option.
  5. Fill out the remaining display name and description boxes.
  6. Ensure that State is set to Enabled.
  7. Select Add scope.

Preauthorize the Power Query client applications

Power Query connectors use two different Microsoft Entra client IDs. Preauthorizing scopes for these client IDs simplifies the connection experience.

Client ID Application Name Used By
a672d62c-fc7b-4e81-a576-e60dc46e951d Power Query for Excel Desktop environments
b52893c8-bc2e-47fc-918b-77022b299bbc Power BI Data Refresh Service environments

To preauthorize the Power Query client IDs:

  1. Go to the resource application's Overview page.
  2. Under Manage, select Expose an API.
  3. Select Add a client application.
  4. Enter one of the Power Query Client IDs.
  5. Select the appropriate Authorized scopes.
  6. Select Add application.
  7. Repeat steps 3 - 6 for each Power Query client ID.

Enable the Aad authentication kind in your connector

Microsoft Entra ID support is enabled for your connector by adding the Aad authentication kind to your connector's data source record.

MyConnector = [
    Authentication = [
        Aad = [
            AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
            Resource = "{YourApplicationIdUri}"
            Scope = ".default"
        ]
    ]
];

Replace the {YourApplicationIdUri} value with the Application ID URI value for your resource application, for example, api://44994a60-7f50-4eca-86b2-5d44f873f93f.

In this example:

  • AuthorizationUri: The Microsoft Entra URL used to initiate the authentication flow. Most connectors can hardcode this value to https://login.microsoftonline.com/common/oauth2/authorize, but it can also be determined dynamically if your service supports Azure B2B/Guest Accounts. For more information, go to samples.
  • Resource: The Application ID URI of your connector.
  • Scope: Use the .default scope to automatically receive all preauthorized scopes. Using .default allows you to change the required connector scopes in your resource application registration, without needing to update your connector.

For more details and options for configuring Microsoft Entra support in your connector, go to Microsoft Entra ID authentication samples page.

Rebuild your connector, and you should now be able to authenticate with your service using Microsoft Entra ID.

Troubleshooting

This section describes common errors you might receive if your Microsoft Entra application is misconfigured.

Power Query application hasn't been preauthorized

access_denied: AADSTS650057: Invalid resource. The client has requested access to a resource which is not listed in the requested permissions in the client's application registration. Client app ID: a672d62c-fc7b-4e81-a576-e60dc46e951d(Microsoft Power Query for Excel). Resource value from request: 44994a60-7f50-4eca-86b2-5d44f873f93f. Resource app ID: 44994a60-7f50-4eca-86b2-5d44f873f93

You might see this error if your resource application hasn't preauthorized the Power Query client applications. Follow the steps to preauthorize the Power Query client IDs.

Connector's Aad record is missing a Scope value

access_denied: AADSTS650053: The application 'Microsoft Power Query for Excel' asked for scope 'user_impersonation' that doesn't exist on the resource '44994a60-7f50-4eca-86b2-5d44f873f93f'. Contact the app vendor.

Power Query requests the user_impersonation scope if the connector's Aad record doesn't define a Scope field, or the Scope value is null. You can resolve this issue by defining a Scope value in the connector. Using the .default scope is recommended, but you can also specify scopes at the connector level (for example - Data.Read).

Scope or client application requires admin approval

Need admin approval. <tenant> needs permission to access resources in your organization that only an admin can grant. Please ask an admin to grant permission to this app before you can use it.

A user might receive this error during their authentication flow if your Resource Application requires admin-restricted permissions or the user's tenant prevents nonadmin users from consenting to new application permission requests. You can avoid this issue by ensuring your connector doesn't require any admin-restricted scopes and preauthorizing the Power Query client IDs for your Resource Application.