Guida introduttiva: Configurazione di Microsoft Entra per un connettore personalizzato

Questa guida descrive i passaggi per configurare un'applicazione Microsoft Entra da usare con un connettore personalizzato di Power Query. Prima di procedere, è consigliabile che gli sviluppatori di connettori esaminino i concetti di Microsoft Identity Platform .

Poiché il termine dell'applicazione viene usato in più contesti nella piattaforma Microsoft Entra, questa guida usa i termini seguenti per distinguere tra gli ID applicazione del connettore e dell'origine dati :

• Applicazione client: ID client Microsoft Entra usati dal connettore Power Query.
• Applicazione risorsa: registrazione dell'applicazione Microsoft Entra per l'endpoint a cui si connette il connettore, ovvero il servizio o l'origine dati.

L'abilitazione del supporto di Microsoft Entra per un connettore personalizzato prevede:

• Definizione di uno o più ambiti nell'applicazione di risorse usata dal connettore.
• Preautenticazione degli ID client di Power Query per l'uso di tali ambiti.
• Impostazione dei valori corretti Resource e Scopes nella definizione del connettore.

Questa guida presuppone che una nuova applicazione di risorse sia registrata in Microsoft Entra. Gli sviluppatori con un'applicazione di risorse esistente possono passare alla sezione Configura un ambito .

Registrare l'applicazione di risorse

L'origine dati o l'endpoint API usa questa applicazione di risorse per stabilire un trust tra il servizio e Microsoft Identity Platform.

Seguire questa procedura per registrare una nuova applicazione di risorse:

1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come Amministratore applicazione cloud.
2. Passare a Identità>Applicazioni>Registrazioni app e selezionare Nuova registrazione.
3. Immettere un Nome visualizzato per l'applicazione.
4. Per Tipi di account supportati selezionare Account in questa directory organizzativa solo se l'endpoint è accessibile solo dall'interno dell'organizzazione. Selezionare Account in qualsiasi directory organizzativa per i servizi multi-tenant accessibili pubblicamente.
5. Selezionare Registra.

Non è necessario specificare un valore URI di reindirizzamento.

La pagina Panoramica dell'applicazione viene visualizzata al termine della registrazione. Prendere nota dei valori id directory (tenant) e ID applicazione (client) che verranno usati nel codice sorgente del servizio. Seguire una delle guide negli esempi di codice di Microsoft Identity Platform simili all'ambiente del servizio e all'architettura per determinare come configurare e usare la nuova applicazione.

Impostare un URI ID applicazione

Prima di poter configurare un ambito per l'endpoint, è necessario impostare un URI ID applicazione per l'applicazione di risorse. Questo ID verrà usato dal Resource campo del Aad record nel connettore. Il valore è impostato sull'URL radice del servizio. È anche possibile usare l'impostazione predefinita generata da Microsoft Entra - api://{clientId} dove {clientId} è l'ID client dell'applicazione di risorse.

1. Passare alla pagina Panoramica dell'applicazione di risorse.
2. Nella schermata centrale, in Informazioni di base, selezionare Aggiungi un URI ID applicazione.
3. Immettere un URI o accettare l'impostazione predefinita in base all'ID app.
4. Selezionare Salva e continua.

Gli esempi in questa guida presuppongono che si stia usando il formato URI ID applicazione predefinito ( ad esempio - api://00001111-aaaa-2222-bbbb-3333cccc4444).

Configurare un ambito

Gli ambiti vengono usati per definire autorizzazioni o funzionalità per accedere alle API o ai dati nel servizio. L'elenco degli ambiti supportati è specifico del servizio. Si vuole determinare un set minimo di ambiti richiesti dal connettore. È necessario preautorizzare almeno un ambito per gli ID client di Power Query.

Se l'applicazione di risorse dispone già di ambiti definiti, è possibile passare al passaggio successivo.

Se il servizio non usa autorizzazioni basate sull'ambito, è comunque possibile definire un singolo ambito usato dal connettore. Facoltativamente, è possibile usare questo ambito nel codice del servizio in futuro.

In questo esempio viene definito un singolo ambito denominato Data.Read.

1. Passare alla pagina Panoramica dell'applicazione di risorse.
2. In Gestisci selezionare Esporre un'API > Aggiungi un ambito .
3. In Nome ambito immettere Data.Read.
4. Per Chi può fornire il consenso, selezionare l'opzione Amministratori e utenti .
5. Compilare le caselle di descrizione e nome visualizzato rimanenti.
6. Assicurarsi che State sia impostato su Abilitato.
7. Seleziona Aggiungi ambito.

Preautenticare le applicazioni client di Power Query

I connettori di Power Query usano due ID client Microsoft Entra diversi. La preautenticazione degli ambiti per questi ID client semplifica l'esperienza di connessione.

Per preautorizzare gli ID client di Power Query:

1. Passare alla pagina Panoramica dell'applicazione di risorse.
2. In Gestisci selezionare Esponi un'API.
3. Seleziona Aggiungi applicazione client.
4. Immettere uno degli ID client di Power Query.
5. Selezionare gli ambiti autorizzati appropriati.
6. Selezionare Aggiungi applicazione.
7. Ripetere i passaggi da 3 a 6 per ogni ID client di Power Query.

Abilitare il tipo di autenticazione Aad nel connettore

Il supporto di Microsoft Entra ID è abilitato per il connettore aggiungendo il Aad tipo di autenticazione al record dell'origine dati del connettore.

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

Sostituire il {YourApplicationIdUri} valore con il valore URI ID applicazione per l'applicazione di risorse, api://00001111-aaaa-2222-bbbb-3333cccc4444ad esempio .

In questo esempio:

• AuthorizationUri: URL di Microsoft Entra usato per avviare il flusso di autenticazione. La maggior parte dei connettori può impostare questo valore come hardcoded su https://login.microsoftonline.com/common/oauth2/authorize, ma può anche essere determinata in modo dinamico se il servizio supporta gli account Azure B2B/Guest. Per altre informazioni, vedere esempi.
• Risorsa: URI ID applicazione del connettore.
• Ambito: usare l'ambito predefinito per ricevere automaticamente tutti gli ambiti pre-autorizzati. L'uso .default di consente di modificare gli ambiti del connettore necessari nella registrazione dell'applicazione di risorse, senza dover aggiornare il connettore.

Per altre informazioni e opzioni per la configurazione del supporto di Microsoft Entra nel connettore, vedere la pagina degli esempi di autenticazione di Microsoft Entra ID.

Ricompilare il connettore e ora dovrebbe essere possibile eseguire l'autenticazione con il servizio usando l'ID Microsoft Entra.

Risoluzione dei problemi

Questa sezione descrive gli errori comuni che è possibile ricevere se l'applicazione Microsoft Entra non è configurata correttamente.

L'applicazione Power Query non è stata pre-autorizzata

access_denied: AADSTS650057: risorsa non valida. Il client ha richiesto l'accesso a una risorsa che non è elencata nelle autorizzazioni richieste nella registrazione dell'applicazione del client. ID app client: a672d62c-fc7b-4e81-a576-e60dc46e951d(Microsoft Power Query per Excel). Valore della risorsa dalla richiesta: 00001111-aaaa-2222-bbbb-3333cccc4444. ID app risorsa: 00001111-aaaa-2222-bbbb-3333cccc4444

Questo errore potrebbe verificarsi se l'applicazione di risorse non ha pre-autorizzato le applicazioni client di Power Query. Seguire la procedura per preautorizzare gli ID client di Power Query.

Il record Aad del connettore non ha un valore di ambito

access_denied: AADSTS650053: l'applicazione "Microsoft Power Query per Excel" ha richiesto l'ambito "user_impersonation" che non esiste nella risorsa "00001111-aaaa-2222-bbbb-3333cccc4444". Contattare il fornitore dell'app.

Power Query richiede l'ambito user_impersonation se il record del Aad connettore non definisce un Scope campo o il Scope valore è null. È possibile risolvere questo problema definendo un Scope valore nel connettore. È consigliabile usare l'ambito .default , ma è anche possibile specificare ambiti a livello di connettore , ad esempio - Data.Read.

L'ambito o l'applicazione client richiede l'approvazione dell'amministratore

È necessaria l'approvazione dell'amministratore. <il tenant> deve disporre dell'autorizzazione per accedere alle risorse dell'organizzazione che possono concedere solo un amministratore. Prima di usarla, è necessario chiedere a un amministratore di concedere l'autorizzazione a quest'app.

Un utente potrebbe ricevere questo errore durante il flusso di autenticazione se l'applicazione risorsa richiede autorizzazioni con restrizioni di amministratore o il tenant dell'utente impedisce agli utenti non amministratori di fornire il consenso alle nuove richieste di autorizzazione dell'applicazione. È possibile evitare questo problema assicurandosi che il connettore non richieda ambiti con restrizioni di amministratore e preautenticazione degli ID client di Power Query per l'applicazione di risorse.