Обработка операций проверки подлинности

Статья
01/19/2024

Типы проверки подлинности

Расширение может поддерживать один или несколько видов проверки подлинности. Каждый тип проверки подлинности — это другой тип учетных данных. Пользовательский интерфейс проверки подлинности, отображаемый конечным пользователям в Power Query, зависит от типа учетных данных, поддерживаемых расширением.

Список поддерживаемых типов проверки подлинности определяется как часть определения типа источника данных расширения. Каждое значение проверки подлинности — это запись с определенными полями. В следующей таблице перечислены ожидаемые поля для каждого вида. Все поля обязательны, если не отмечено в противном случае.

Тип проверки подлинности	Поле	Description
Анонимные		Тип анонимной проверки подлинности (также называемый `Implicit`) не имеет полей.
OAuth	StartLogin	Функция, предоставляющая сведения о URL-адресе и состоянии для запуска потока OAuth. Перейдите в раздел "Реализация потока OAuth".
	ГотовоLogin	Функция, извлекающая access_token и другие свойства, связанные с потоком OAuth.
	Refresh	(необязательно) Функция, извлекающая новый маркер доступа из маркера обновления.
	Выход	(необязательно) Функция, которая недействительно указывает текущий маркер доступа пользователя.
	Этикетка	(необязательно) Текстовое значение, позволяющее переопределить метку по умолчанию для этого AuthenticationKind.
Аад	AuthorizationUri	`text` значение или унарная функция, возвращающая конечную точку авторизации идентификатора Microsoft Entra (например: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Перейдите в раздел проверки подлинности идентификатора Microsoft Entra.
	Ресурс	`text` значение или унарная функция, возвращающая значение ресурса идентификатора Microsoft Entra для службы.
	Область	(необязательно) `text` значение или унарная функция, которая возвращает список областей для запроса в рамках потока проверки подлинности. Несколько значений области должны быть разделены пробелом. Значение области должно быть именем области без URI идентификатора приложения (например: `Data.Read`). Если она не указана, `user_impersonation` запрашивается область.
UsernamePassword	UsernameLabel	(необязательно) Текстовое значение для замены метки по умолчанию для текстового поля имени пользователя в пользовательском интерфейсе учетных данных.
	PasswordLabel	(необязательно) Текстовое значение для замены метки по умолчанию для текстового поля "Пароль " в пользовательском интерфейсе учетных данных.
	Этикетка	(необязательно) Текстовое значение, позволяющее переопределить метку по умолчанию для этого AuthenticationKind.
Windows	UsernameLabel	(необязательно) Текстовое значение для замены метки по умолчанию для текстового поля имени пользователя в пользовательском интерфейсе учетных данных.
	PasswordLabel	(необязательно) Текстовое значение для замены метки по умолчанию для текстового поля "Пароль " в пользовательском интерфейсе учетных данных.
	Этикетка	(необязательно) Текстовое значение, позволяющее переопределить метку по умолчанию для этого AuthenticationKind.
Ключ	KeyLabel	(необязательно) Текстовое значение для замены метки по умолчанию для текстового поля ключа API в пользовательском интерфейсе учетных данных.
	Этикетка	(необязательно) Текстовое значение, позволяющее переопределить метку по умолчанию для этого AuthenticationKind.

В следующем примере показана запись проверки подлинности для соединителя, который поддерживает OAuth, Key, Windows, Basic (имя пользователя и пароль) и анонимные учетные данные.

Пример:

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

Доступ к текущим учетным данным

Текущие учетные данные можно получить с помощью Extension.CurrentCredential функции.

Функции источника данных M, которые были включены для расширения, автоматически наследуют область учетных данных расширения. В большинстве случаев вам не нужно явно обращаться к текущим учетным данным, однако существуют исключения, например:

Передача учетных данных в настраиваемом параметре заголовка или строки запроса (например, при использовании типа проверки подлинности ключа API).
Задание свойств строка подключения для расширений ODBC или ADO.NET.
Проверка пользовательских свойств маркера OAuth.
Использование учетных данных в рамках потока OAuth версии 1.

Функция Extension.CurrentCredential возвращает объект записи. Поля, содержащиеся в нем, относятся к типу проверки подлинности. В следующей таблице содержатся сведения.

Поле	Description	Где используется
AuthenticationKind	Содержит имя типа проверки подлинности, назначенного этому учетным данным (UsernamePassword, OAuth и т. д.).	Все
Username	Значение имени пользователя	UsernamePassword, Windows
Пароль	Значение пароля. Обычно используется с Именем пользователяPassword, но он также задан для ключа.	Ключ, UsernamePassword, Windows
access_token;	Значение маркера доступа OAuth.	OAuth
Свойства	Запись, содержащая другие настраиваемые свойства для заданных учетных данных. Обычно используется с OAuth для хранения других свойств (например, refresh_token), возвращаемых access_token во время потока проверки подлинности.	OAuth
Ключ	Значение ключа API. Обратите внимание, что значение ключа также доступно в поле "Пароль". По умолчанию модуль mashup вставляет этот ключ в заголовок авторизации, как если бы это значение было основным паролем проверки подлинности (без имени пользователя). Если этот тип поведения не является нужным, необходимо указать параметр ManualCredentials = true в записи параметров.	Ключ
EncryptConnection	Логическое значение, определяющее, требуется ли зашифрованное подключение к источнику данных. Это значение доступно для всех типов проверки подлинности, но устанавливается только в том случае, если EncryptConnection указан в определении источника данных.	Все

Следующий пример кода обращается к текущим учетным данным ключа API и использует его для заполнения пользовательского заголовка (x-APIKey).

Пример:

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

Реализация потока OAuth

Тип проверки подлинности OAuth позволяет расширению реализовать пользовательскую логику для своей службы. Для этого расширение предоставляет функции StartLogin (возвращая URI авторизации для запуска потока OAuth) и FinishLogin (обмен кодом авторизации для маркера доступа). Расширения могут также реализовать Refresh (обмен маркером обновления для нового маркера доступа) и Logout (истекает срок действия текущих маркеров обновления и доступа).

Примечание.

Расширения Power Query оцениваются в приложениях, работающих на клиентских компьютерах. Соединители данных не должны использовать конфиденциальные секреты в потоках OAuth, так как пользователи могут проверить расширение или сетевой трафик, чтобы узнать секрет. Дополнительные сведения о предоставлении потоков, не зависящих от общих секретов, см. в разделе проверки подлинности ключа для обмена кодом от OAuth Public Client RFC (также известного как PKCE). Пример реализации этого потока можно найти на сайте GitHub.

Существует два набора подписей функции OAuth: исходная сигнатура, содержащая минимальное количество параметров, и расширенная сигнатура, принимаюющая дополнительные параметры. Большинство потоков OAuth можно реализовать с помощью исходных подписей. Вы также можете смешивать и сопоставлять типы подписей в реализации. Вызовы функций соответствуют количеству параметров (и их типам). Имена параметров не учитываются.

Дополнительные сведения см. в примере GitHub.

Исходные подписи OAuth

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

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

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

Logout = (accessToken) => ...;

Расширенные подписи OAuth

Примечания о расширенных подписях:

Все подписи принимают clientApplication значение записи, зарезервированное для будущего использования.
Все подписи принимают ( dataSourcePath также называются resourceUrl в большинстве примеров).
Функция Refresh принимает oldCredential параметр, который является предыдущим record , возвращенным функцией FinishLogin (или предыдущим вызовом Refresh).

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

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

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

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

Проверка подлинности идентификатора Microsoft Entra

Тип Aad проверки подлинности — это специализированная версия OAuth для идентификатора Microsoft Entra. Он использует тот же клиент Идентификатора Microsoft Entra, что и встроенные соединители Power Query, поддерживающие проверку подлинности учетной записи организации. Дополнительные сведения см. в кратком руководстве по настройке Microsoft Entra для пользовательского соединителя .

Примечание.

Если вы реализуете собственный поток OAuth для идентификатора Microsoft Entra, пользователи, которые включили условный доступ для своего клиента, могут столкнуться с проблемами при обновлении с помощью служба Power BI. Это не влияет на обновление на основе шлюза, но повлияет на сертифицированный соединитель, поддерживающий обновление из служба Power BI. Пользователи могут столкнуться с проблемой, возникшую из соединителя с помощью общедоступного клиентского приложения при настройке учетных данных на основе веб-сайтов с помощью служба Power BI. Маркер доступа, созданный этим потоком, в конечном счете будет использоваться на другом компьютере (то есть служба Power BI в центре обработки данных Azure, а не в сети компании), чем тот, который использовался для первоначальной проверки подлинности (то есть компьютер пользователя, который настраивает учетные данные источника данных в сети компании). Встроенный Aad тип работает над этой проблемой с помощью другого клиента Идентификатора Microsoft Entra при настройке учетных данных в служба Power BI. Этот параметр не будет доступен соединителям, используюющим OAuth тип проверки подлинности.

Большинство соединителей должны предоставлять значения для AuthorizationUri полей и Resource полей. Оба поля могут быть text значениями или одной функцией аргумента, возвращающей значение 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)

Соединители, использующие идентификатор на основе URI, не должны предоставлять Resource значение. По умолчанию значение равно корневому пути параметра URI соединителя. Если ресурс идентификатора источника данных Microsoft Entra ID отличается от значения домена (например, он использует GUID), Resource необходимо указать значение.

Примеры типа проверки подлинности Aad

В следующем случае источник данных поддерживает глобальный облачный идентификатор Microsoft Entra с помощью общего клиента (без поддержки Azure B2B). Запрос области .default возвращает маркер со всеми ранее авторизованными областями для идентификатора клиентского приложения 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"
    ]
]

В следующем случае источник данных поддерживает обнаружение клиентов на основе OpenID Connect (OIDC) или аналогичного протокола. Эта возможность позволяет соединителю определить правильную конечную точку идентификатора Microsoft Entra ID, используемую на основе одного или нескольких параметров в пути к источнику данных. Этот подход динамического обнаружения позволяет соединителю поддерживать 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"
    ]
]

Другие типы проверки подлинности

Дополнительные сведения о других типах проверки подлинности, не описанных в этой статье, например единый вход на основе Kerberos, см . в дополнительной статье о функциональных возможностях соединителя .

Поделиться через