Gestion de l’authentification

Article
03/21/2024

Types d’authentification

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

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

Type d’authentification	Champ	Description
Anonyme		Le genre d’authentification Anonyme (également appelé `Implicit`) n’a pas de champs.
OAuth	StartLogin	Fonction qui fournit les informations d’URL et d’état pour démarrer un flux OAuth. Accédez à la section Implémentation d’un Flow OAuth.
	FinishLogin	Fonction qui extrait le jeton d’accès (access_token) et d’autres propriétés liées au flux OAuth.
	Refresh	(facultatif) Fonction qui récupère un nouveau jeton d’accès à partir d’un jeton d’actualisation.
	Logout	(facultatif) Fonction qui invalide le jeton d’accès actuel de l’utilisateur.
	Étiquette	(facultatif) Valeur de texte qui vous permet de remplacer l’étiquette par défaut pour ce AuthenticationKind.
Aad	AuthorizationUri	Valeur `text` ou fonction unaire qui renvoie le point de terminaison d'autorisation Microsoft Entra ID (exemple : `"https://login.microsoftonline.com/common/oauth2/authorize"`). Accédez à la section Authentification Microsoft Entra ID.
	Ressource	Valeur `text` ou fonction unaire qui renvoie la valeur de la ressource Microsoft Entra ID pour votre service.
	Étendue	(facultatif)`text` Valeur ou fonction unaire qui retourne la liste des étendues à demander dans le cadre du flux d’authentification. Les valeurs d'étendue multiples doivent être séparées par un espace. La valeur de l’étendue doit être le nom de l’étendue, sans URI d’ID d’application (exemple : `Data.Read`). Lorsqu’elle n’est pas fournie, l’étendue `user_impersonation` est demandée.
UsernamePassword	UsernameLabel	(facultatif) Valeur de texte pour remplacer l’étiquette par défaut de la zone de texte Nom d’utilisateur sur l’interface utilisateur des informations d’identification.
	PasswordLabel	(facultatif) Valeur de texte pour remplacer l’étiquette par défaut de la zone de texte Mot de passe sur l’interface utilisateur des informations d’identification.
	Étiquette	(facultatif) Valeur de texte qui vous permet de remplacer l’étiquette par défaut pour ce AuthenticationKind.
Windows	UsernameLabel	(facultatif) Valeur de texte pour remplacer l’étiquette par défaut de la zone de texte Nom d’utilisateur sur l’interface utilisateur des informations d’identification.
	PasswordLabel	(facultatif) Valeur de texte pour remplacer l’étiquette par défaut de la zone de texte Mot de passe sur l’interface utilisateur des informations d’identification.
	Étiquette	(facultatif) Valeur de texte qui vous permet de remplacer l’étiquette par défaut pour ce AuthenticationKind.
Clé	KeyLabel	(facultatif) Valeur de texte pour remplacer l’étiquette par défaut de la zone de texte Clé API sur l’interface utilisateur des informations d’identification.
	Étiquette	(facultatif) Valeur de texte qui vous permet de remplacer l’étiquette par défaut pour ce AuthenticationKind.

L’exemple suivant affiche l’enregistrement d’authentification pour un connecteur qui prend 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 en utilisant la fonction Extension.CurrentCredential.

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

Passer les informations d’identification dans un en-tête personnalisé ou un paramètre de chaîne de requête (par exemple quand vous utilisez le type d’authentification Clé API).
Définir des propriétés de chaîne de connexion pour les extensions ODBC ou ADO.NET.
Vérifier des propriétés personnalisées sur un jeton OAuth.
Utiliser des informations d’identification dans le cadre d’un flux OAuth v1.

La fonction Extension.CurrentCredential retourne un objet d’enregistrement. Les champs qu’il contient sont spécifiques au type d’authentification. La table suivante contient les détails.

Champ	Description	Utilisé par
AuthenticationKind	Contient le nom du type d’authentification affecté à ces informations d’identification (UsernamePassword, OAuth, etc.).	Tous
Nom d’utilisateur	Valeur du nom d’utilisateur	UsernamePassword, Windows
Mot de passe	Valeur du mot de passe Généralement utilisé avec UsernamePassword, mais il est aussi défini pour Key.	Clé, UsernamePassword, Windows
access_token	Valeur du jeton d’accès OAuth.	OAuth
Propriétés	Enregistrement contenant d’autres propriétés personnalisées pour des informations d’identification données. Généralement utilisé avec OAuth pour stocker d’autres propriétés (comme le refresh_token) renvoyées avec le access_token pendant le flux d’authentification.	OAuth
Clé	Valeur de la clé API. Notez que la valeur de la clé est également disponible dans le champ Mot de passe. Par défaut, le moteur mashup insère cette clé dans un en-tête d'autorisation comme s’il s’agissait d’un mot de passe d’authentification de base (sans nom d’utilisateur). Si ce genre de comportement ne correspond pas à votre souhait, vous devez spécifier l’option ManualCredentials = true dans l’enregistrement des options.	Clé
EncryptConnection	Valeur logique qui a déterminé s’il fallait exiger une connexion chiffrée à la source de données. Cette valeur est disponible pour tous les genres d’authentification, mais n’est définie que si EncryptConnection est spécifié dans la définition de Source de données.	Tous

L’exemple de code suivant accède aux informations d’identification actuelles d’une clé API et l’utilise pour renseigner 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 cela, une extension fournit des fonctions pour StartLogin (renvoyer l’URI d’autorisation pour initier le flux OAuth) et FinishLogin (échanger le code d’autorisation contre un jeton d’accès). Les extensions peuvent éventuellement implémenter aussi les fonctions 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).

Remarque

Les extensions Power Query sont évaluées dans les applications s’exécutant sur des machines clientes. Les connecteurs de données ne doivent pas utiliser de secrets confidentiels dans leurs flux OAuth, car les utilisateurs peuvent inspecter l’extension ou le trafic réseau pour découvrir le secret. Accédez à Proof Key for Code Exchange by OAuth Public Clients RFC (aussi appelé PKCE) pour plus d’informations sur la fourniture de flux qui ne reposent pas sur des secrets partagés. Vous trouverez un exemple d’implémentation de ce flux sur notre site GitHub.

Il existe deux jeux de signatures de fonction OAuth : la signature d’origine contenant un nombre minimal de paramètres et une signature avancée acceptant plus de paramètres. La plupart des flux OAuth peuvent être implémentés en utilisant les signatures d’origine. Vous pouvez également combiner et faire correspondre des types de signature dans votre implémentation. Les appels de fonction sont des correspondances basées sur le nombre de paramètres (et leurs types). Les noms des paramètres ne sont pas pris en considération.

Accédez à l'exemple GitHub pour plus de détails.

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 future.
Toutes les signatures acceptent un dataSourcePath (également appelé resourceUrl dans la plupart des exemples).
La fonction Refresh accepte un paramètre oldCredential, qui est le record précédent retourné par votre fonction FinishLogin (ou l’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 Microsoft Entra ID

Le type d’authentification Aad 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 des comptes d'organisation. Vous trouverez plus d’informations dans le guide de démarrage rapide Configuration de Microsoft Entra pour un connecteur personnalisé.

Remarque

Si vous implémentez votre propre flux OAuth pour Microsoft Entra ID, les utilisateurs qui ont activé l’accès conditionnel pour leur client peuvent rencontrer des problèmes lors de l’actualisation en utilisant le service Power BI. Ceci n’aura pas d’impact sur l’actualisation basée sur la passerelle, mais va affecter un connecteur certifié qui prend en charge l’actualisation à partir du service Power BI. Les utilisateurs peuvent avoir un problème de recherche de radical lié au connecteur en utilisant une application cliente publique lors de la configuration des informations d’identification web via le service Power BI. Le jeton d’accès généré par ce flux sera finalement utilisé sur un autre ordinateur (c’est-à-dire le service Power BI dans un centre de données Azure et non pas sur le réseau de l’entreprise) que celui utilisé pour l’authentification initiale (c’est-à-dire l’ordinateur de l’utilisateur qui configure les informations d’identification de la source de données sur le réseau de l’entreprise). Le type intégré Aad contourne ce problème en utilisant un autre client Microsoft Entra ID lors de la configuration des identifiants dans le service Power BI. Cette option ne sera pas disponible pour les connecteurs qui utilisent le type d’authentification OAuth.

La majorité des connecteurs doivent fournir des valeurs pour les AuthorizationUri et Resource champs. Les deux champs peuvent être des valeurs text ou une fonction avec un seul argument qui retourne une 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)

Les connecteurs utilisant un dentificateur basé sur un URI n’ont pas besoin de fournir de 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 valeur Resource doit être fournie.

Exemples de types d’authentification Aad

Dans l’incident suivant, la source de données prend en charge Microsoft Entra ID dans le cloud global à l’aide du client commun (pas de prise en charge 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 = "77256ee0-fe79-11ea-adc1-0242ac120002", // Entra Application ID URI or app guid
        Scope = ".default"
    ]
]

Dans l'incident 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 d’identifier le point de terminaison Microsoft Entra ID correct à utiliser en fonction d’un ou plusieurs paramètres dans le chemin d’accès 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"
    ]
]

D'autres types d’authentification

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