Gestion de l’authentification

Types d’authentification

Une extension peut prendre en charge un ou plusieurs types d’authentification. Chaque méthode d’authentification est un type d’identifiant différent. L’interface utilisateur d’authentification affichée pour les utilisateurs finaux dans Power Query est pilotée par le type d’informations d’identification prises en charge par une extension.

La liste des types d’authentification pris en charge est définie dans le cadre de la définition de type de source de données d’une extension. Chaque valeur d’authentification est un enregistrement avec des champs spécifiques. Le tableau suivant répertorie les champs attendus pour chaque type. Tous les champs sont obligatoires, sauf indication contraire.

L’exemple suivant montre l’enregistrement d’authentification d’un connecteur prenant en charge OAuth, Key, Windows, Basic (nom d’utilisateur et mot de passe) et les informations d’identification anonymes.

Exemple :

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

Accès aux informations d’identification actuelles

Les informations d’identification actuelles peuvent être récupérées à l’aide de la Extension.CurrentCredential fonction.

Les fonctions de source de données M qui ont été activées pour l'extensibilité héritent automatiquement du domaine d'authentification de votre extension. Dans la plupart des cas, vous n’avez pas besoin d’accéder explicitement aux informations d’identification actuelles, mais il existe des exceptions, telles que :

• Transmission des informations d’identification dans un paramètre de chaîne de requête ou d’en-tête personnalisé (par exemple, lorsque vous utilisez le type d’authentification de clé API).
• Définition des propriétés de chaîne de connexion pour les extensions ODBC ou ADO.NET.
• Vérification des propriétés personnalisées sur un jeton OAuth.
• Utilisation des informations d’identification dans le cadre d’un flux OAuth v1.

La Extension.CurrentCredential fonction retourne un objet d’enregistrement. Les champs qu’il contient sont spécifiques au type d’authentification. Le tableau suivant contient des détails.

L’exemple de code suivant accède aux informations d’identification actuelles d’une clé API et l’utilise pour remplir un en-tête personnalisé (x-APIKey).

Exemple :

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

Implémentation d’un flux OAuth

Le type d’authentification OAuth permet à une extension d’implémenter une logique personnalisée pour son service. Pour ce faire, une extension fournit des fonctions pour StartLogin (renvoyant l’URI d’autorisation pour lancer le flux OAuth) et FinishLogin (échange du code d’autorisation pour un jeton d’accès). Les extensions peuvent éventuellement implémenter Refresh (échange d’un jeton d’actualisation pour un nouveau jeton d’accès) et Logout (expiration des jetons d’actualisation et d’accès actuels) également.

Il existe deux ensembles de signatures de fonction OAuth : la signature d’origine qui contient un nombre minimal de paramètres et une signature avancée qui accepte davantage de paramètres. La plupart des flux OAuth peuvent être implémentés à l’aide des signatures d’origine. Vous pouvez également combiner et mettre en correspondance des types de signature dans votre implémentation. Les appels de fonction sont des correspondances en fonction du nombre de paramètres (et de leurs types). Les noms des paramètres ne sont pas pris en compte.

Pour plus d’informations, accédez à l’exemple GitHub .

Signatures OAuth d’origine

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

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

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

Logout = (accessToken) => ...;

Signatures OAuth avancées

Remarques sur les signatures avancées :

• Toutes les signatures acceptent une valeur d’enregistrement clientApplication , qui est réservée à une utilisation ultérieure.
• Toutes les signatures acceptent un dataSourcePath (également appelé resourceUrl dans la plupart des exemples).
• La Refresh fonction accepte un oldCredential paramètre, qui est le précédent record retourné par votre FinishLogin fonction (ou appel précédent à Refresh).

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

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

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

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

Authentification par Microsoft Entra ID

Le Aad type d’authentification est une version spécialisée d’OAuth pour Microsoft Entra ID. Il utilise le même client Microsoft Entra ID que les connecteurs Power Query intégrés qui prennent en charge l’authentification de compte d’organisation. Vous trouverez plus d’informations dans le guide de démarrage rapide Configuration de Microsoft Entra pour un connecteur personnalisé .

La plupart des connecteurs doivent fournir des valeurs pour les champs AuthorizationUri et Resource. Les deux champs peuvent être des valeurs de text, ou une fonction à argument unique qui retourne un 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)

Les connecteurs qui utilisent un identificateur basé sur uri n’ont pas besoin de fournir une Resource valeur. Par défaut, la valeur est égale au chemin racine du paramètre Uri du connecteur. Si la ressource Microsoft Entra ID de la source de données est différente de la valeur de domaine (par exemple, elle utilise un GUID), une Resource valeur doit être fournie.

Exemples de type d’authentification Aad

Dans le cas suivant, la source de données prend en charge l'ID Microsoft Entra global pour le cloud en utilisant le client commun (sans prise en charge d'Azure B2B). La demande de l’étendue .default retourne un jeton avec toutes les étendues précédemment autorisées pour l’ID d’application cliente 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"
    ]
]

Dans le cas suivant, la source de données prend en charge la découverte de locataires basée sur OpenID Connect (OIDC) ou un protocole similaire. Cette capacité permet au connecteur de déterminer le point de terminaison d’ID Microsoft Entra approprié à utiliser en fonction d’un ou de plusieurs paramètres dans le chemin de la source de données. Cette approche de découverte dynamique permet au connecteur de prendre en charge 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"
    ]
]

Autres types d’authentification

Pour plus d’informations sur d’autres types d’authentification non abordés dans cet article, tels que l’authentification unique basée sur Kerberos, consultez l’article sur les fonctionnalités de connecteur supplémentaires pour en savoir plus.