Обработка аутентификации

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

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

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

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

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

Example:

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 и т. д.).	All
Имя пользователя	Значение имени пользователя	ИмяПользователяПароль, Windows
Пароль	Значение пароля. Обычно используется с именем пользователя и паролем, но также задаётся для ключа.	Ключ, Имя пользователя и пароль, Windows
access_token	Значение маркера доступа OAuth.	OAuth
Свойства	Запись, содержащая другие настраиваемые свойства для заданных учетных данных. Обычно используется с OAuth для хранения других свойств (таких как refresh_token), возвращаемых вместе с access_token во время процесса аутентификации.	OAuth
Key	Значение ключа API. Обратите внимание, что значение ключа также доступно в поле "Пароль". По умолчанию модуль mashup вставляет этот ключ в заголовок авторизации, как если бы это значение было основным паролем проверки подлинности (без имени пользователя). Если этот тип поведения не является нужным, необходимо указать параметр ManualCredentials = true в записи параметров.	Key
EncryptConnection	Логическое значение, определяющее, требуется ли зашифрованное подключение к источнику данных. Это значение доступно для всех типов проверки подлинности, но устанавливается только в том случае, если EncryptConnection указан в определении источника данных .	All

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

Example:

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, так как пользователи могут проверить расширение или сетевой трафик, чтобы узнать секрет. Перейдите к спецификации RFC «Ключ доказательства для обмена кодом для публичных клиентов OAuth» (также известной как 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 ID при настройке учетных данных в службе Power BI. Этот параметр не будет доступен соединителям, используюющим OAuth тип проверки подлинности.

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

Соединители, использующие идентификатор на основе 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 = "44445555-eeee-6666-ffff-7777aaaa8888", // 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, см. в дополнительной статье о функциональных возможностях соединителя .

Обратная связь

Была ли эта страница полезна?

Last updated on 2024-12-04