Control de la autenticación

Tipos de autenticación

Una extensión puede admitir uno o varios tipos de autenticación. Cada tipo de autenticación es un tipo de credencial diferente. La interfaz de usuario de autenticación mostrada a los usuarios finales en Power Query está controlada por el tipo de credenciales que admite una extensión.

La lista de tipos de autenticación admitidos se define como parte de la definición del tipo de origen de datos de una extensión. Cada valor de autenticación es un registro con campos específicos. En la tabla siguiente se enumeran los campos esperados para cada tipo. Todos los campos son obligatorios a menos que se marque lo contrario.

Tipo de autenticación	Campo	Description
Anónimo		El tipo de autenticación Anónimo (también denominado `Implicit`) no tiene ningún campo.
OAuth	StartLogin	Función que proporciona la información de dirección URL y estado para iniciar un flujo de OAuth. Vaya a la sección Implementación de un flujo de OAuth .
	FinishLogin	Función que extrae el access_token y otras propiedades relacionadas con el flujo de OAuth.
	Actualizar	(opcional) Función que recupera un nuevo token de acceso de un token de actualización.
	Logout	(opcional) Función que invalida el token de acceso actual del usuario.
	Etiqueta	(opcional) Valor de texto que le permite invalidar la etiqueta predeterminada para este AuthenticationKind.
Aad	URI de autorización	`text` valor o función unaria que devuelve el punto de conexión de autorización de Microsoft Entra ID (ejemplo: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Vaya a la sección Autenticación de Id. de Entra de Microsoft .
	Resource	`text` valor o función unaria que devuelve el valor de recurso de ID de Microsoft Entra para su servicio.
	Ámbito	(opcional)`text` valor o función unaria que devuelve la lista de ámbitos que se van a solicitar como parte del flujo de autenticación. Varios valores de ámbito deben estar separados por un espacio. El valor de ámbito debe ser el nombre del ámbito, sin un URI de id. de aplicación (por ejemplo: `Data.Read`). Cuando no se proporciona, se solicita el `user_impersonation` ámbito.
Nombre de usuarioContraseña	EtiquetaNombreUsuario	(opcional) Valor de texto para reemplazar la etiqueta predeterminada del cuadro de texto Nombre de usuario en la interfaz de usuario de credenciales.
	EtiquetaContraseña	(opcional) Valor de texto para reemplazar la etiqueta predeterminada del cuadro de texto Contraseña en la interfaz de usuario de credenciales.
	Etiqueta	(opcional) Valor de texto que le permite invalidar la etiqueta predeterminada para este AuthenticationKind.
Windows	EtiquetaDeNombreDeUsuario	(opcional) Valor de texto para reemplazar la etiqueta predeterminada del cuadro de texto Nombre de usuario en la interfaz de usuario de credenciales.
	EtiquetaContraseña	(opcional) Valor de texto para reemplazar la etiqueta predeterminada del cuadro de texto Contraseña en la interfaz de usuario de credenciales.
	Etiqueta	(opcional) Valor de texto que le permite invalidar la etiqueta predeterminada para este AuthenticationKind.
Key	Etiqueta de Clave	(opcional) Valor de texto para reemplazar la etiqueta predeterminada del cuadro de texto Clave de API en la interfaz de usuario de credenciales.
	Etiqueta	(opcional) Valor de texto que le permite invalidar la etiqueta predeterminada para este AuthenticationKind.

En el ejemplo siguiente se muestra el registro de autenticación de un conector que admite OAuth, Key, Windows, Basic (nombre de usuario y contraseña) y credenciales anónimas.

Example:

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

Acceso a las credenciales actuales

Las credenciales actuales se pueden recuperar mediante la Extension.CurrentCredential función .

Las funciones del origen de datos M que se han habilitado para la extensibilidad heredan automáticamente el ámbito de credenciales de la extensión. En la mayoría de los casos, no es necesario acceder explícitamente a las credenciales actuales; sin embargo, hay excepciones, como:

Pasar la credencial en un encabezado personalizado o un parámetro de cadena de consulta (por ejemplo, cuando se usa el tipo de autenticación de clave API).
Establecer las propiedades de la cadena de conexión para las extensiones ODBC o ADO.NET.
Comprobación de propiedades personalizadas en un token de OAuth.
Usar las credenciales como parte de un flujo de OAuth v1.

La Extension.CurrentCredential función devuelve un objeto de registro. Los campos que contiene son específicos del tipo de autenticación. La tabla siguiente contiene detalles.

Campo	Description	Usado por
Tipo de Autenticación	Contiene el nombre del tipo de autenticación asignado a esta credencial (UsernamePassword, OAuth, etc.).	Todos
Nombre de usuario	Valor de nombre de usuario	Nombre de usuario y contraseña, Windows
Contraseña	Valor de contraseña. Normalmente se utiliza con usuario y contraseña, pero también se configura para clave.	Clave, Nombre de usuario y contraseña, Windows
access_token	Valor del token de acceso de OAuth.	OAuth
Propiedades	Registro que contiene otras propiedades personalizadas para una credencial determinada. Normalmente se usa con OAuth para almacenar otras propiedades (como la refresh_token) devuelta con el access_token durante el flujo de autenticación.	OAuth
Key	Valor de clave de API. Tenga en cuenta que el valor de clave también está disponible en el campo Contraseña. De forma predeterminada, el motor de mashup inserta esta clave en un encabezado authorization como si este valor fuera una contraseña de autenticación básica (sin nombre de usuario). Si este tipo de comportamiento no es lo que desea, debe especificar la opción ManualCredentials = true en el registro de opciones.	Key
EncryptConnection	Valor lógico que determinó si se requiere una conexión cifrada al origen de datos. Este valor está disponible para todos los tipos de autenticación, pero solo se establece si se especifica EncryptConnection en la definición de origen de datos.	Todos

En el ejemplo de código siguiente se accede a la credencial actual de una clave de API y se usa para rellenar un encabezado personalizado (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

Implementación de un flujo de OAuth

El tipo de autenticación OAuth permite que una extensión implemente lógica personalizada para su servicio. Para ello, una extensión proporciona funciones para StartLogin (devolver el URI de autorización para iniciar el flujo de OAuth) y FinishLogin (intercambiar el código de autorización de un token de acceso). Opcionalmente, las extensiones pueden implementar Refresh (intercambiar un token de actualización para un nuevo token de acceso) y Logout (expirar también las funciones actuales de actualización y de acceso).

Nota:

Las extensiones de Power Query se evalúan en aplicaciones que se ejecutan en máquinas cliente. Los conectores de datos no deben usar secretos confidenciales en sus flujos de OAuth, ya que los usuarios pueden inspeccionar la extensión o el tráfico de red para aprender el secreto. Vaya a Proof Key for Code Exchange by OAuth Public Clients RFC (también conocido como PKCE) para obtener más detalles sobre cómo proporcionar flujos que no se basan en secretos compartidos. Puede encontrar una implementación de ejemplo de este flujo en nuestro sitio de GitHub.

Hay dos conjuntos de firmas de función de OAuth: la firma original que contiene un número mínimo de parámetros y una firma avanzada que acepta más parámetros. La mayoría de los flujos de OAuth se pueden implementar mediante las firmas originales. También puede combinar y mezclar tipos de firma en su implementación. Las llamadas de función son coincidencias basadas en el número de parámetros (y sus tipos). Los nombres de parámetro no se tienen en cuenta.

Vaya al ejemplo de GitHub para obtener más detalles.

Firmas originales de OAuth

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

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

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

Logout = (accessToken) => ...;

Firmas avanzadas de OAuth

Notas sobre las firmas avanzadas:

Todas las firmas aceptan un clientApplication valor de registro, que está reservado para su uso futuro.
Todas las firmas aceptan una dataSourcePath (también denominada resourceUrl en la mayoría de los ejemplos).
La función Refresh acepta un parámetro oldCredential, que es el record anterior devuelto por tu función FinishLogin (o llamada anterior a Refresh).

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

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

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

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

Autenticación de Microsoft Entra ID

El Aad tipo de autenticación es una versión especializada de OAuth para el identificador de Microsoft Entra. Usa el mismo cliente de Entra ID de Microsoft que los conectores integrados de Power Query que admiten la autenticación mediante cuentas organizacionales. Puede encontrar más información en la guía de inicio rápido Configuración de Microsoft Entra para un conector personalizado .

Nota:

Si implementa su propio flujo de OAuth para Microsoft Entra ID, los usuarios que han habilitado el acceso condicional para su inquilino podrían encontrar problemas al actualizar al utilizar el servicio Power BI. Esto no afectará a la actualización basada en la puerta de enlace, pero afectaría a un conector certificado que admita la actualización desde el servicio Power BI. Es posible que los usuarios se encuentren con problemas derivados del conector al usar una aplicación cliente pública al configurar credenciales web a través del servicio Power BI. El token de acceso generado por este flujo se usará en última instancia en un equipo diferente (es decir, el servicio Power BI en un centro de datos de Azure, no en la red de la empresa) que el que se usa para autenticarse originalmente (es decir, el equipo del usuario que configura las credenciales del origen de datos en la red de la empresa). El tipo integrado Aad aborda este problema mediante un cliente diferente de id. de Microsoft Entra al configurar las credenciales en el servicio Power BI. Esta opción no estará disponible para los conectores que usan el tipo de OAuth autenticación.

La mayoría de los conectores deben proporcionar valores para los AuthorizationUri campos y Resource . Ambos campos pueden ser text valores o una única función de argumento que devuelve 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)

Los conectores que usan un identificador basado en URI no necesitan proporcionar un Resource valor. De forma predeterminada, el valor es igual a la ruta de acceso raíz del parámetro URI del conector. Si el recurso de ID de Microsoft Entra del origen de datos es diferente del valor de dominio (por ejemplo, usa un GUID), se debe proporcionar un valor Resource.

Ejemplos de tipos de autenticación de Aad

En el siguiente caso, la fuente de datos admite Microsoft Entra ID global en la nube mediante el tenant común (sin compatibilidad con Azure B2B). Al solicitar el ámbito .default , se devuelve un token con todos los ámbitos autorizados previamente para el identificador de aplicación cliente de 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"
    ]
]

En el siguiente caso, el origen de datos admite la detección de inquilinos basada en OpenID Connect (OIDC) o en un protocolo similar. Esta capacidad permite al conector determinar el punto de conexión correcto de Microsoft Entra ID para usarlo en función de uno o varios parámetros en la ruta de acceso del origen de datos. Este enfoque de detección dinámica permite que el conector admita 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"
    ]
]

Otros tipos de autenticación

Para obtener información sobre otros tipos de autenticación que no se tratan en este artículo, como el inicio de sesión único basado en Kerberos, visite el artículo sobre la funcionalidad del conector adicional para obtener más información.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-11-26