Gestione dell'autenticazione

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.

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.

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

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.

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 = "44445555-eeee-6666-ffff-7777aaaa8888"   // 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 = "44445555-eeee-6666-ffff-7777aaaa8888", // 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.