Gestione dell'autenticazione

Articolo
07/04/2024

Tipi di autenticazione

Un'estensione può supportare uno o più tipi di autenticazione. Ogni tipo di autenticazione è un tipo diverso di credenziali. L'interfaccia utente di autenticazione visualizzata agli utenti finali in Power Query è basata sul tipo di credenziali supportate da un'estensione.

L'elenco dei tipi di autenticazione supportati è definito come parte della definizione del tipo di origine dati di un'estensione. Ogni valore di autenticazione è un record con campi specifici. Nella tabella seguente sono elencati i campi previsti per ogni tipo. Tutti i campi sono obbligatori, a meno che non siano contrassegnati diversamente.

Tipo di autenticazione	Campo	Descrizione
Anonimo		Il tipo di autenticazione Anonimo (detto `Implicit`anche ) non include campi.
OAuth	StartLogin	Funzione che fornisce l'URL e le informazioni sullo stato per l'avvio di un flusso OAuth. Passare alla sezione Implementazione di un flusso OAuth.
	FinishLogin	Funzione che estrae il access_token e altre proprietà correlate al flusso OAuth.
	Refresh	(facoltativo) Funzione che recupera un nuovo token di accesso da un token di aggiornamento.
	Disconnessione	(facoltativo) Funzione che invalida il token di accesso corrente dell'utente.
	Etichetta	(facoltativo) Valore di testo che consente di eseguire l'override dell'etichetta predefinita per questo AuthenticationKind.
Aad	AuthorizationUri	`text` valore o funzione unaria che restituisce l'endpoint di autorizzazione dell'ID Di Microsoft Entra (ad esempio: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Passare alla sezione Autenticazione DELL'ID di Microsoft Entra.
	Conto risorse	`text` valore o funzione unaria che restituisce il valore della risorsa MICROSOFT Entra ID per il servizio.
	Ambito	(facoltativo) `text` valore o funzione unaria che restituisce l'elenco di ambiti da richiedere come parte del flusso di autenticazione. Più valori di ambito devono essere separati da uno spazio. Il valore dell'ambito deve essere il nome dell'ambito, senza un URI ID applicazione (ad esempio: `Data.Read`). Se non specificato, viene richiesto l'ambito `user_impersonation` .
UsernamePassword	UsernameLabel	(facoltativo) Valore di testo per sostituire l'etichetta predefinita per la casella di testo Nome utente nell'interfaccia utente delle credenziali.
	PasswordLabel	(facoltativo) Valore di testo per sostituire l'etichetta predefinita per la casella di testo Password nell'interfaccia utente delle credenziali.
	Etichetta	(facoltativo) Valore di testo che consente di eseguire l'override dell'etichetta predefinita per questo AuthenticationKind.
Finestre	UsernameLabel	(facoltativo) Valore di testo per sostituire l'etichetta predefinita per la casella di testo Nome utente nell'interfaccia utente delle credenziali.
	PasswordLabel	(facoltativo) Valore di testo per sostituire l'etichetta predefinita per la casella di testo Password nell'interfaccia utente delle credenziali.
	Etichetta	(facoltativo) Valore di testo che consente di eseguire l'override dell'etichetta predefinita per questo AuthenticationKind.
Chiave	KeyLabel	(facoltativo) Valore di testo per sostituire l'etichetta predefinita per la casella di testo Chiave API nell'interfaccia utente delle credenziali.
	Etichetta	(facoltativo) Valore di testo che consente di eseguire l'override dell'etichetta predefinita per questo AuthenticationKind.

L'esempio seguente illustra il record di autenticazione per un connettore che supporta OAuth, Key, Windows, Basic (Nome utente e password) e credenziali anonime.

Esempio:

Authentication = [
    OAuth = [
        StartLogin = StartLogin,
        FinishLogin = FinishLogin,
        Refresh = Refresh,
        Logout = Logout
    ],
    Key = [],
    UsernamePassword = [],
    Windows = [],
    Anonymous = []
]

Accesso alle credenziali correnti

Le credenziali correnti possono essere recuperate usando la Extension.CurrentCredential funzione .

Le funzioni dell'origine dati M abilitate per l'estendibilità ereditano automaticamente l'ambito delle credenziali dell'estensione. Nella maggior parte dei casi non è necessario accedere in modo esplicito alle credenziali correnti, ma esistono eccezioni, ad esempio:

Passaggio delle credenziali in un'intestazione personalizzata o in un parametro della stringa di query, ad esempio quando si usa il tipo di autenticazione della chiave API.
Impostazione delle proprietà stringa di connessione per le estensioni ODBC o ADO.NET.
Controllo delle proprietà personalizzate in un token OAuth.
Uso delle credenziali come parte di un flusso OAuth v1.

La Extension.CurrentCredential funzione restituisce un oggetto record. I campi contenuti sono specifici del tipo di autenticazione. La tabella seguente contiene i dettagli.

Campo	Descrizione	Usato da
AuthenticationKind	Contiene il nome del tipo di autenticazione assegnato a questa credenziale (UsernamePassword, OAuth e così via).	Tutte le date
Username	Valore nome utente	UsernamePassword, Windows
Password	Valore password. In genere usato con UsernamePassword, ma è impostato anche per Key.	Key, UsernamePassword, Windows
access_token	Valore del token di accesso OAuth.	OAuth
Proprietà	Record contenente altre proprietà personalizzate per una determinata credenziale. In genere usato con OAuth per archiviare altre proprietà( ad esempio la refresh_token) restituite con il access_token durante il flusso di autenticazione.	OAuth
Chiave	Valore della chiave API. Si noti che il valore della chiave è disponibile anche nel campo Password. Per impostazione predefinita, il motore mashup inserisce questa chiave in un'intestazione di autorizzazione come se questo valore fosse una password di autenticazione di base (senza nome utente). Se questo tipo di comportamento non è quello desiderato, è necessario specificare l'opzione ManualCredentials = true nel record delle opzioni.	Chiave
EncryptConnection	Valore logico che ha determinato se richiedere una connessione crittografata all'origine dati. Questo valore è disponibile per tutti i tipi di autenticazione, ma è impostato solo se EncryptConnection è specificato nella definizione origine dati.	Tutte le date

L'esempio di codice seguente accede alle credenziali correnti per una chiave API e lo usa per popolare un'intestazione personalizzata (x-APIKey).

Esempio:

MyConnector.Raw = (_url as text) as binary =>
let
    apiKey = Extension.CurrentCredential()[Key],
    headers = [

        #"x-APIKey" = apiKey,
        Accept = "application/vnd.api+json",
        #"Content-Type" = "application/json"
    ],
    request = Web.Contents(_url, [ Headers = headers, ManualCredentials = true ])
in
    request

Implementazione di un flusso OAuth

Il tipo di autenticazione OAuth consente a un'estensione di implementare la logica personalizzata per il servizio. A tale scopo, un'estensione fornisce funzioni per StartLogin (restituendo l'URI di autorizzazione per avviare il flusso OAuth) e FinishLogin (scambiando il codice di autorizzazione per un token di accesso). Le estensioni possono facoltativamente implementare Refresh (scambiando un token di aggiornamento per un nuovo token di accesso) e Logout (in scadenza anche i token di aggiornamento e di accesso correnti).

Nota

Le estensioni di Power Query vengono valutate nelle applicazioni in esecuzione nei computer client. I connettori dati non devono usare segreti riservati nei flussi OAuth, perché gli utenti possono esaminare l'estensione o il traffico di rete per apprendere il segreto. Passare a Proof Key for Code Exchange by OAuth Public Clients RFC (noto anche come PKCE) per altri dettagli sulla fornitura di flussi che non si basano su segreti condivisi. Un'implementazione di esempio di questo flusso è disponibile nel sito GitHub.

Esistono due set di firme di funzione OAuth: la firma originale che contiene un numero minimo di parametri e una firma avanzata che accetta più parametri. La maggior parte dei flussi OAuth può essere implementata usando le firme originali. È anche possibile combinare e associare i tipi di firma nell'implementazione. Le chiamate di funzione sono corrispondenze in base al numero di parametri (e ai relativi tipi). I nomi dei parametri non vengono presi in considerazione.

Per altri dettagli, vedere l'esempio di GitHub.

Firme OAuth originali

StartLogin = (dataSourcePath, state, display) => ...;

FinishLogin = (context, callbackUri, state) => ...;

Refresh = (dataSourcePath, refreshToken) =>  ...;

Logout = (accessToken) => ...;

Firme OAuth avanzate

Note sulle firme avanzate:

Tutte le firme accettano un clientApplication valore di record, riservato per un uso futuro.
Tutte le firme accettano un oggetto dataSourcePath (noto anche come resourceUrl nella maggior parte dei campioni).
La Refresh funzione accetta un oldCredential parametro, che è il precedente record restituito dalla FinishLogin funzione (o la chiamata precedente a Refresh).

StartLogin = (clientApplication, dataSourcePath, state, display) => ...;

FinishLogin = (clientApplication, dataSourcePath, context, callbackUri, state) => ...;

Refresh = (clientApplication, dataSourcePath, oldCredential) =>  ...;

Logout = (clientApplication, dataSourcePath, accessToken) => ...;

Autenticazione di Microsoft Entra ID

Il Aad tipo di autenticazione è una versione specializzata di OAuth per Microsoft Entra ID. Usa lo stesso client MICROSOFT Entra ID dei connettori Power Query predefiniti che supportano l'autenticazione dell'account aziendale. Altre informazioni sono disponibili nella guida introduttiva Configurazione di Microsoft Entra per un connettore personalizzato.

Nota

Se si implementa il proprio flusso OAuth per Microsoft Entra ID, gli utenti che hanno abilitato l'accesso condizionale per il tenant potrebbero riscontrare problemi durante l'aggiornamento tramite il servizio Power BI. Questo non influisce sull'aggiornamento basato sul gateway, ma influisce su un connettore certificato che supporta l'aggiornamento dal servizio Power BI. Gli utenti potrebbero riscontrare un problema derivante dal connettore usando un'applicazione client pubblica durante la configurazione delle credenziali basate sul Web tramite il servizio Power BI. Il token di accesso generato da questo flusso verrà infine usato in un computer diverso( ovvero il servizio Power BI in un data center di Azure, non nella rete aziendale) rispetto a quello usato originariamente per l'autenticazione (ovvero il computer dell'utente che configura le credenziali dell'origine dati nella rete aziendale). Il tipo predefinito Aad funziona per risolvere questo problema usando un client MICROSOFT Entra ID diverso durante la configurazione delle credenziali nel servizio Power BI. Questa opzione non sarà disponibile per i connettori che usano il OAuth tipo di autenticazione.

La maggior parte dei connettori deve fornire valori per i AuthorizationUri campi e Resource . Entrambi i campi possono essere text valori o una singola funzione di argomento che restituisce un oggetto text value.

AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize"

AuthorizationUri = (dataSourcePath) => FunctionThatDeterminesAadEndpointFromDataSourcePath(dataSourcePath)

Resource = "77256ee0-fe79-11ea-adc1-0242ac120002"   // Microsoft Entra ID resource value for your service - Guid or URL

Resource = (dataSourcePath) => FunctionThatDeterminesResourceFromDataSourcePath(dataSourcePath)

I connettori che usano un identificatore basato su URI non devono fornire un Resource valore. Per impostazione predefinita, il valore è uguale al percorso radice del parametro Uri del connettore. Se la risorsa ID Microsoft Entra dell'origine dati è diversa dal valore di dominio (ad esempio, usa un GUID), è necessario specificare un Resource valore.

Esempi di tipi di autenticazione Aad

Nel caso seguente, l'origine dati supporta l'ID Microsoft Entra cloud globale usando il tenant comune (nessun supporto B2B di Azure). La richiesta dell'ambito predefinito restituisce un token con tutti gli ambiti precedentemente autorizzati per l'ID applicazione client di Power Query.

Authentication = [
    Aad = [
        AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
        Resource = "77256ee0-fe79-11ea-adc1-0242ac120002", // Entra Application ID URI or app guid
        Scope = ".default"
    ]
]

Nel caso seguente, l'origine dati supporta l'individuazione del tenant basata su OpenID Connect (OIDC) o su un protocollo simile. Questa possibilità consente al connettore di determinare l'endpoint ID Microsoft Entra corretto da usare in base a uno o più parametri nel percorso dell'origine dati. Questo approccio di individuazione dinamica consente al connettore di supportare Azure B2B.


// Implement this function to retrieve or calculate the service URL based on the data source path parameters
GetServiceRootFromDataSourcePath = (dataSourcePath) as text => ...;

GetAuthorizationUrlFromWwwAuthenticate = (url as text) as text =>
    let
        // Sending an unauthenticated request to the service returns
        // a 302 status with WWW-Authenticate header in the response. The value will
        // contain the correct authorization_uri.
        // 
        // Example:
        // Bearer authorization_uri="https://login.microsoftonline.com/{tenant_guid}/oauth2/authorize"
        responseCodes = {302, 401},
        endpointResponse = Web.Contents(url, [
            ManualCredentials = true,
            ManualStatusHandling = responseCodes
        ])
    in
        if (List.Contains(responseCodes, Value.Metadata(endpointResponse)[Response.Status]?)) then
            let
                headers = Record.FieldOrDefault(Value.Metadata(endpointResponse), "Headers", []),
                wwwAuthenticate = Record.FieldOrDefault(headers, "WWW-Authenticate", ""),
                split = Text.Split(Text.Trim(wwwAuthenticate), " "),
                authorizationUri = List.First(List.Select(split, each Text.Contains(_, "authorization_uri=")), null)
            in
                if (authorizationUri <> null) then
                    // Trim and replace the double quotes inserted before the url
                    Text.Replace(Text.Trim(Text.Trim(Text.AfterDelimiter(authorizationUri, "=")), ","), """", "")
                else
                    error Error.Record("DataSource.Error", "Unexpected WWW-Authenticate header format or value during authentication.", [
                        #"WWW-Authenticate" = wwwAuthenticate
                    ])
        else
            error Error.Unexpected("Unexpected response from server during authentication.");

<... snip ...>

Authentication = [
    Aad = [
        AuthorizationUri = (dataSourcePath) =>
            GetAuthorizationUrlFromWwwAuthenticate(
                GetServiceRootFromDataSourcePath(dataSourcePath)
            ),
        Resource = "https://myAadResourceValue.com", // Microsoft Entra ID resource value for your service - Guid or URL
        Scope = ".default"
    ]
]

Altri tipi di autenticazione

Per informazioni su altri tipi di autenticazione non trattati in questo articolo, ad esempio l'accesso Single Sign-On basato su Kerberos, vedere l'articolo sulle funzionalità aggiuntive del connettore per altre informazioni.

Condividi tramite