Control de la autenticación

Artículo
01/23/2024

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 que se muestra 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 indique lo contrario.

Tipo de autenticación	Campo	Descripción
Anónimas		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 sustituir la etiqueta predeterminada para este AuthenticationKind.
Aad	AuthorizationUri	valor `text` o función de unario 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 Microsoft Entra ID.
	Resource	valor `text` o función de unario que devuelve el valor del recurso de Microsoft Entra ID para el servicio.
	Ámbito	(opcional) valor `text` o función de unario que devuelve la lista de ámbitos que se van a solicitar como parte del flujo de autenticación. Los valores de ámbito múltiples deben ir 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 ámbito `user_impersonation`.
UsernamePassword	UsernameLabel	(opcional) Valor de texto para reemplazar la etiqueta predeterminada del cuadro de texto Nombre de usuario en la interfaz de usuario de credenciales.
	PasswordLabel	(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 sustituir la etiqueta predeterminada para este AuthenticationKind.
Windows	UsernameLabel	(opcional) Valor de texto para reemplazar la etiqueta predeterminada del cuadro de texto Nombre de usuario en la interfaz de usuario de credenciales.
	PasswordLabel	(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 sustituir la etiqueta predeterminada para este AuthenticationKind.
Clave	KeyLabel	(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 sustituir la etiqueta predeterminada para este AuthenticationKind.

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

Ejemplo:

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 función Extension.CurrentCredential.

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, por ejemplo:

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 de API).
Establecer las propiedades de la cadena de conexión para las extensiones ODBC o ADO.NET.
Comprobar las propiedades personalizadas en un token de OAuth.
Usar las credenciales como parte de un flujo de OAuth v1.

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

Campo	Descripción	Usado por
AuthenticationKind	Contiene el nombre del tipo de autenticación asignado a esta credencial (UsernamePassword, OAuth, etc.).	All
Nombre de usuario	Valor de nombre de usuario	UsernamePassword, Windows
Contraseña	Valor de contraseña. Normalmente se usa con UsernamePassword, pero también se establece para Clave.	Clave, UsernamePassword, Windows
access_token	Valor de token de acceso OAuth.	OAuth
Propiedades	Registro que contiene otras propiedades personalizadas para una credencial determinada. Normalmente se usa con OAuth para almacenar otras propiedades (como el refresh_token) devueltas con el access_token durante el flujo de autenticación.	OAuth
Clave	El valor de la 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 de autorización 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.	Clave
EncryptConnection	Valor lógico que determina 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 del origen de datos.	All

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).

Ejemplo:

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 también pueden implementar las funciones de Refresh (intercambiar un token de actualización para un nuevo token de acceso) y Logout (expirar los tokens actuales de actualización y 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 conocer el secreto. Vaya a RFC - Clave de prueba para intercambio de código por clientes públicos de OAuth (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 hacer coincidir tipos de firma en la 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 información.

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 valor de registro clientApplication, 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 la 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 tipo de autenticación Aad es una versión especializada de OAuth para Microsoft Entra ID. Usa el mismo cliente de Microsoft Entra ID que los conectores integrados de Power Query que admiten la autenticación de cuentas de la organización. 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 tener problemas al actualizar mediante el servicio Power BI. Esto no afectará a la actualización basada en la puerta de enlace, pero sí a un conector certificado que admita la actualización desde el servicio Power BI. Los usuarios podrían encontrarse con un problema derivado del conector que utiliza una aplicación cliente pública al configurar las credenciales basadas en web a través del servicio Power BI. El token de acceso generado por este flujo se utilizará en última instancia en un equipo diferente (es decir, el servicio Power BI en un centro de datos Azure, no en la red de la empresa) al utilizado 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 de Aad integrado soluciona este problema utilizando un cliente Microsoft Entra ID diferente al configurar las credenciales en el servicio Power BI. Esta opción no estará disponible para los conectores que utilicen el tipo de autenticación OAuth.

La mayoría de los conectores deben proporcionar valores para los campos AuthorizationUri y Resource. Ambos campos pueden ser valores text 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 = "77256ee0-fe79-11ea-adc1-0242ac120002"   // 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 valor Resource. De forma predeterminada, el valor es igual a la ruta raíz del parámetro URI del conector. Si el recurso de Microsoft Entra ID del origen de datos es diferente del valor de dominio (por ejemplo, usa un GUID), se debe proporcionar un valor Resource.

Muestras de tipo de autenticación Aad

En el siguiente caso, el origen de datos admite Microsoft Entra ID en la nube global mediante el inquilino 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 = "77256ee0-fe79-11ea-adc1-0242ac120002", // 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 de Microsoft Entra ID correcto que se usará en función de uno o varios parámetros en la ruta 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, consulte el artículo sobre funcionalidad adicional del conector para obtener más información.

Compartir vía