Adquisición de tokens de acceso

  • 8 minutos

Cuando adquiere un token de acceso, siempre necesario para insertar contenido de Power BI, esto implica adquirir un token de Azure AD. Cuando se usa el escenario Para los clientes, la aplicación usa el token de Azure AD para generar un token de inserción.

En resumen:

  • El token de acceso en el escenario Para la organización es el token de Azure AD que contiene las notificaciones que la aplicación usa para identificar los permisos concedidos.
  • El token de acceso en el escenario Para los clientes es un token de inserción que representa datos sobre contenido de Power BI y cómo la aplicación puede acceder a ellos. La aplicación genera el token de inserción mediante una operación de API REST de Power BI que requiere un token de Azure AD.

Adquisición de tokens de Azure AD

Use la Biblioteca de autenticación de Microsoft (MSAL) para desarrollar una lógica de aplicación que adquiera tokens de Azure AD de la Plataforma de identidad de Microsoft. MSAL es compatible con distintas arquitecturas y plataformas de aplicación, incluidas .NET, JavaScript, Java, Python, Android e iOS.

Sugerencia

Al desarrollar una aplicación web de ASP.NET Core, se recomienda usar la biblioteca de autenticación de Microsoft Identity Web. Esta biblioteca es un conjunto de paquetes conocidos como Microsoft.Identity.Web. Puede instalarla desde NuGet o Visual Studio.

Hay diferentes técnicas para adquirir un token de Azure AD mediante MSAL. En algunos casos, se requiere la interacción del usuario mediante un explorador web, mientras que en otros no es necesaria. En general, el método que elija para adquirir un token de Azure AD depende de si la aplicación es una aplicación cliente pública (por ejemplo, una aplicación de escritorio o móvil) o una aplicación cliente confidencial (como una aplicación web). El escenario de inserción también influye en su elección.

En esta unidad no se pretenden describir las técnicas para adquirir tokens de Azure AD. Para más información, consulte Adquisición y almacenamiento en caché de tokens con la biblioteca de autenticación de Microsoft (MSAL).

Sugerencia

Cuando las aplicaciones de ejemplo de la herramienta de configuración de inserción coincidan con los requisitos de la aplicación, considere la posibilidad de copiar el código de ejemplo para adquirir tokens de Azure AD.

Para permitir que la aplicación adquiera tokens de Azure AD, su archivo de configuración debe contener los valores siguientes:

  • TenantId: obligatorio solo para la entidad de servicio. Es el valor del identificador de inquilino de Azure AD.
  • ClientId - Requerido. Es el valor del identificador de la aplicación (o cliente) de Azure AD.
  • ClientSecret o ClientCertificate: son solo obligatorios para la entidad de servicio.
  • PbiUsername: obligatorio solo para la cuenta de usuario maestra.
  • PbiPassword: obligatorio solo para la cuenta de usuario maestra.

Importante

Tanto si usa certificados, secretos de cliente o credenciales de cuenta de usuario maestra, debe seguir los pasos necesarios para protegerlos del acceso y uso no autorizados. Se recomienda usar Azure Key Vault, que protege claves criptográficas, certificados y secretos en la nube.

Adquisición de tokens de inserción

Use la operación GenerateTokenRequestV2 de la API REST de Microsoft Power BI para solicitar un token de inserción. Hay otras operaciones relacionadas que generan tokens de inserción para otros tipos de contenido de Power BI. Todas las operaciones de API requieren un token de Azure AD.

Sugerencia

Al desarrollar una aplicación .NET, se recomienda instalar el paquete Microsoft.PowerBI.Api. Puede instalarla desde NuGet o Visual Studio.

Tenga en cuenta el código siguiente que muestra cómo generar un token de inserción. El token contiene notificaciones para todos los informes y conjuntos de datos de un área de trabajo, y permite a los usuarios de la aplicación crear o editar informes. Concretamente, hace lo siguiente:

  1. Se conecta a Power BI.
  2. Declara una variable denominada reportTokenRequests para almacenar las solicitudes de tokens de informes.
  3. Muestra todos los informes del área de trabajo, creando una lista de objetos EmbeddedReport (mediante una clase auxiliar). En cada objeto se describe el identificador, el nombre y la dirección URL de inserción del informe. La aplicación requiere el identificador del informe para generar un token. El nombre es necesario para presentar a los usuarios en un menú y la dirección URL de inserción es necesaria para insertar el informe. El código agrega una solicitud de token de informe, lo que permite la edición de informes, a la variable reportTokenRequests.
  4. Declara una variable denominada datasetTokenRequests que almacena las solicitudes de tokens de conjuntos de datos.
  5. Muestra todos los conjuntos de datos del área de trabajo, creando una lista de objetos EmbeddedDataset (mediante una clase auxiliar). En cada objeto se describe el identificador, el nombre y la dirección URL de inserción del conjunto de datos. La aplicación requiere el identificador del conjunto de datos para generar un token. El nombre puede ser necesario para presentarlo a los usuarios en un menú y la dirección URL de inserción es necesaria para insertar el conjunto de datos. El código agrega una solicitud de token de conjunto de datos a la variable datasetTokenRequests.
  6. Genera una solicitud de token de área de trabajo (necesaria cuando los usuarios crean informes) que se agrega a la variable workspaceRequests.
  7. Usa el método GenerateTokenRequestV2 para agrupar las solicitudes de tokens de informes, de conjuntos de datos y de áreas de trabajo.
  8. Usa GenerateTokenAsync para generar un token de inserción.
  9. Almacena el token de inserción en una variable de cadena.
// Connect to Power BI
var client = GetPowerBiClient();

// Get reports in the workspace
var reports = (await client.Reports.GetReportsInGroupAsync(_workspaceId)).Value;

var reportList = new List<EmbeddedReport>();
var reportTokenRequests = new List<GenerateTokenRequestV2Report>();

foreach (var report in reports)
{
    reportList.Add(new EmbeddedReport
    {
        Id = report.Id.ToString(),
        Name = report.Name,
        EmbedUrl = report.EmbedUrl
    });

    reportTokenRequests.Add(new GenerateTokenRequestV2Report(report.Id, allowEdit: true));
}

// Get datasets in the workspace
var datasets = (await client.Datasets.GetDatasetsInGroupAsync(_workspaceId)).Value;

var datasetList = new List<EmbeddedDataset>();
var datasetTokenRequests = new List<GenerateTokenRequestV2Dataset>();

foreach (var dataset in datasets)
{
    datasetList.Add(new EmbeddedDataset
    {
        Id = dataset.Id.ToString(),
        Name = dataset.Name,
        EmbedUrl = dataset.QnaEmbedURL
    });

    datasetTokenRequests.Add(new GenerateTokenRequestV2Dataset(dataset.Id));
}

// Generate token request for the workspace
var workspaceRequests = new GenerateTokenRequestV2TargetWorkspace[] {
    new GenerateTokenRequestV2TargetWorkspace(_workspaceId)
};

// Bundle token requests for reports, datasets, and the workspace
var tokenRequest = new GenerateTokenRequestV2(
    reports: reportTokenRequests,
    datasets: datasetTokenRequests,
    targetWorkspaces: workspaceRequests
);

// Generate the embed token
string embedToken = (await client.EmbedToken.GenerateTokenAsync(tokenRequest)).Token;

La aplicación debe generar el valor embedToken de la variable en la página HTML de inserción. Después, la lógica en el lado cliente puede usar el token de inserción para insertar contenido en un elemento div.

Nota

Para aprender a insertar contenido de Power BI, realice el módulo Inserción de contenido de Power BI.

Para permitir que la aplicación adquiera tokens de inserción, su archivo de configuración debe contener detalles sobre el contenido insertable. Puede incluir identificadores de informes y de conjuntos de datos específicos o, como es más habitual, los identificadores de grupos de las áreas de trabajo que contienen el contenido insertable.

Para más información, consulte Inserción de tokens: Generación de tokens.

Tokens de acceso de actualización

Los tokens de acceso tienen hora de expiración. Una vez generados, los usuarios de la aplicación tienen un tiempo limitado para interactuar con el contenido de Power BI que los usa. Para proporcionar a los usuarios de la aplicación una experiencia continua, la aplicación debe actualizar los tokens de acceso antes de que expiren mediante la API de cliente de Power BI.

Nota

Para obtener más información sobre la API de cliente, consulte el módulo Integración de contenido con las API de cliente de Power BI.

Para obtener más información, consulte Actualización del token de acceso.

Exploración de otros recursos

Para más información, vea la serie de vídeos Guía para desarrolladores de Power BI sobre la seguridad de Azure AD. Esta serie consta de seis vídeos que cubren la teoría en profundidad. Ted Pattison, miembro del equipo de asesoramiento al cliente (CAT) de Power BI en Microsoft, produjo esta serie de vídeos.