Conteúdo inserido do Power BI com a entidade de serviço e um segredo do aplicativo

  • Artigo

A entidade de serviço é um método de autenticação que pode ser usado para permitir que o aplicativo Microsoft Entra acesse o conteúdo e as APIs do serviço do Power BI.

Quando você cria um aplicativo do Microsoft Entra, um objeto da entidade de serviço é criado. O objeto da entidade de serviço, também conhecida simplesmente como entidade de serviço, permite que o Microsoft Entra ID autentique seu aplicativo. Depois de autenticado, o aplicativo poderá acessar os recursos de locatário do Microsoft Entra.

Para fazer a autenticação, a entidade de serviço usa a ID do Aplicativo no Microsoft Entra e uma das opções a seguir:

  • Um certificado
  • Um segredo do aplicativo

Este artigo descreve a autenticação da entidade de serviço usando uma ID de aplicativo e um segredo de aplicativo.

Observação

Recomendamos que você proteja os seus serviços de back-end usando certificados, em vez de chaves secretas.

Método

A fim de usar a entidade de serviço e uma ID de aplicativo para uma análise integrada, siga as etapas a seguir. As seções subsequentes descrevem essas etapas em detalhes.

  1. Crie um aplicativo do Microsoft Entra.

    1. Crie um segredo para seu aplicativo do Microsoft Entra.
    2. Obtenha a ID do aplicativo e o segredo do aplicativo.

    Observação

    Todas essas etapas são descritas na etapa 1. Para obter mais informações sobre como criar um aplicativo do Microsoft Entra, consulte criar um aplicativo do Microsoft Entra.

  2. Crie um grupo de segurança do Microsoft Entra.

  3. Habilite as configurações de administração do serviço do Power BI.

  4. Adicione a entidade de serviço ao seu espaço de trabalho.

  5. Insira seu conteúdo.

Importante

Um aplicativo do Microsoft Entra não exige que você configure nenhuma permissão delegada ou de aplicativo no portal do Azure quando ele foi criado para uma entidade de serviço. Ao criar um aplicativo do Microsoft Entra para uma entidade de serviço acessar a API REST do Power BI, recomendamos que você evite adicionar permissões. Elas nunca são usadas e podem causar erros difíceis de solucionar.

Etapa 1 - Criar um aplicativo do Microsoft Entra

Crie um aplicativo do Microsoft Entra usando um destes métodos:

Criar um aplicativo do Microsoft Entra no portal do Azure

  1. Entre no portal do Azure.

  2. Localize e selecione Registros de aplicativo.

    Captura de tela do portal do Azure, com o registro do aplicativo na caixa de pesquisa. Essa caixa e o ícone Registros de aplicativo estão realçados.

  3. Selecione Novo registro.

    Captura de tela da página Registros de aplicativo no portal do Azure. Novo registro está realçado.

  4. Preencha as informações obrigatórias:

    • Nome – digite um nome para seu aplicativo.
    • Tipos de conta com suporte – selecione os tipos de conta com suporte.
    • (Opcional) URI de redirecionamento – insira um URI, se necessário.

  5. Selecione Registrar.

  6. Após registrar seu aplicativo, a ID do Aplicativo estará disponível na guia Visão geral. Copie e salve a ID do Aplicativo para uso posterior.

    Captura de tela da página Visão geral do novo aplicativo. A ID do Aplicativo é indecifrável e está realçada.

  7. Selecione Certificados e segredos.

    Captura de tela da página Visão geral do novo aplicativo. No painel de navegação, Certificados e segredos estão realçados.

  8. Selecione Novo segredo do cliente.

    Captura de tela que mostra parte da página Certificados e segredos do aplicativo. Em Segredos do cliente, o botão Novo segredo do cliente está realçado.

  9. Na janela Adicionar um segredo do cliente, insira uma descrição, especifique quando deseja que o segredo do cliente expire e selecione Adicionar.

  10. Copie e salve o valor do segredo do cliente.

    Captura de tela da página Certificados e segredos do aplicativo. Em Segredos do cliente, um novo segredo está visível. Seu valor indecifrável está realçado.

    Observação

    Depois de sair dessa janela, o valor do segredo do cliente fica oculto e você não pode visualizá-lo ou copiá-lo novamente.

Crie um aplicativo do Microsoft Entra usando o PowerShell

O exemplo de script do PowerShell a seguir cria um novo aplicativo do Microsoft Entra e uma entidade de serviço. Antes de executar este script:

Após a execução do script, anote as seguintes informações na saída do script:

  • A ID do cliente do novo aplicativo
  • A ID do objeto da nova entidade de serviço
  • O valor do segredo da entidade de serviço
# Sign in as a user who's allowed to create an app.
Connect-MgGraph -Scopes "Application.ReadWrite.All" 

# Create a new Azure AD web application.
$web = @{
    RedirectUris = "https://localhost:44322"
    HomePageUrl = "https://localhost:44322"
}
$params = @{
    DisplayName = "myAzureADApp"
    Web = $($web)
}
$app = New-MgApplication @params
Write-Host "Client ID of new app: " $($app.AppId)

# Create a service principal.
$ServicePrincipalID=@{
  "AppId" = $($app.AppId)
  }
$sp = New-MgServicePrincipal -BodyParameter $($ServicePrincipalId)
Write-Host "Object ID of new service principal: " $($sp.Id)

# Create a key for the service principal.
$credential = Add-MgServicePrincipalPassword -ServicePrincipalId $($sp.Id)
Write-Host "Credential of new service principal: " $($credential.SecretText)

Etapa 2 - Criar um grupo de segurança do Microsoft Entra

Sua entidade de serviço não tem acesso a nenhum de seus conteúdo e APIs do Power BI. Para conceder acesso à entidade de serviço, crie um grupo de segurança no Microsoft Entra ID. Em seguida, adicione a entidade de serviço que você criou a esse grupo de segurança.

Observação

Caso queira habilitar o acesso à entidade de serviço para toda a organização, ignore essa etapa.

Há duas maneiras de criar um grupo de segurança do Microsoft Entra:

Criar manualmente um grupo de segurança

Para criar manualmente um grupo de segurança no Azure, siga as instruções em Criar um grupo básico e adicionar membros.

Criar um grupo de segurança usando o PowerShell

O script de exemplo a seguir cria um novo grupo de segurança. Ele também adiciona a entidade de serviço que você criou anteriormente ao novo grupo de segurança.

  • Antes de executar o script, substitua <app-client-ID> pela ID do cliente que você registrou anteriormente para seu novo aplicativo.
  • Depois de executar o script, anote a ID do objeto do novo grupo de segurança, que você pode encontrar na saída do script.
# Sign in as an admin.
Connect-MgGraph -Scopes "Application.ReadWrite.All"

# Get the service principal that you created earlier.
$servicePrincipal = Get-MgServicePrincipal -Filter "AppId eq '<app-client-ID>'"

# Create an Azure AD security group.
$group = New-MgGroup -DisplayName "securitygroup1" -SecurityEnabled -MailEnabled:$False -MailNickName "notSet"
Write-Host "Object ID of new security group: " $($group.Id)

# Add the service principal to the group.
New-MgGroupMember -GroupId $($group.Id) -DirectoryObjectId $($servicePrincipal.Id)

Etapa 3 – Habilitar as configurações de administração do serviço do Power BI

Para um aplicativo do Microsoft Entra acessar o conteúdo e as APIs do Power BI, um administrador de Power BI precisa habilitar a seguinte configuração:

  • Inserir conteúdo em aplicativos
  • Permitir que as entidades de serviço usem APIs do Power BI

No Portal de Administração do Power BI, acesse Configurações de locatário e role para baixo até Configurações do desenvolvedor.

  • Habilite Inserir conteúdo em aplicativos para toda a organização ou para o grupo de segurança específico criado no Microsoft Entra ID.

    Captura de tela das Configurações do desenvolvedor na seção Configurações de locatário do Portal de administração. A opção para inserir conteúdo nos aplicativos está ativada.

  • Habilite Permitir que as entidades de serviço usem as APIs do Power BI para toda a organização ou para o grupo de segurança específico criado no Microsoft Entra ID.

    Captura de tela da seção Configurações do desenvolvedor. A opção para permitir que as entidades de serviço usem APIs do Power BI está ativada para um grupo de segurança.

    Importante

    As entidades de serviço têm acesso a quaisquer configurações de locatário para as quais estejam habilitadas. Dependendo das configurações de administrador, isso inclui grupos de segurança específicos ou de toda a organização.

    Para restringir o acesso da entidade de serviço a configurações de locatário específicas, permita o acesso somente a grupos de segurança específicos. Como alternativa, você pode criar um grupo de segurança dedicado para entidades de serviço e excluí-lo das configurações de locatário desejadas.

Etapa 4 – Adicione a entidade de serviço ao seu workspace

Seu aplicativo do Microsoft Entra pode acessar seus relatórios, painéis e modelos semânticos do Power BI somente quando tiver acesso ao espaço de trabalho do Power BI. Você fornece esse acesso adicionando a entidade de serviço do aplicativo ou seu grupo de segurança ao seu workspace como membro ou administrador.

Há três maneiras de adicionar uma entidade de serviço ou grupo de segurança ao seu workspace:

Adicionar uma entidade de serviço ou um grupo de segurança manualmente

  1. No serviço do Power BI, role até o workspace para o qual você deseja habilitar o acesso. Em seu menu Mais, selecione Acesso do workspace.

    Captura de tela que mostra o menu Mais expandido para um workspace. Nesse menu, o acesso ao Workspace está realçado.

  2. No painel Acesso, em Adicionar administradores, membros ou colaboradores, adicione um dos seguintes:

    • Sua entidade de serviço. O nome da entidade de serviço é o Nome de exibição de seu aplicativo do Microsoft Entra como ele aparece na guia de visão geral do aplicativo do Microsoft Entra.
    • O grupo de segurança que inclui sua entidade de serviço.

  3. No menu suspenso, selecione Membro ou Administrador.

  4. Selecione Adicionar.

Adicionar uma entidade de serviço ou um grupo de segurança usando o PowerShell

As seções a seguir fornecem scripts de exemplo do PowerShell para adicionar uma entidade de serviço e um grupo de segurança a um workspace do Power BI como membro.

Adicionar uma entidade de serviço como um membro do workspace usando o PowerShell

O script a seguir adiciona uma entidade de serviço como um membro do workspace. Antes de executar o script:

  • Substitua <service-principal-object-ID> pela ID de objeto que você registrou anteriormente para sua nova entidade de serviço.
  • Substitua <workspace-name> pelo nome do workspace ao qual você gostaria de conceder acesso à entidade de serviço.
# Sign in to Power BI.
Login-PowerBI

# Set up the service principal ID.
$SPObjectID = "<service-principal-object-ID>"

# Get the workspace.
$pbiWorkspace = Get-PowerBIWorkspace -Filter "name eq '<workspace-name>'"

# Add the service principal to the workspace.
Add-PowerBIWorkspaceUser -Id $($pbiWorkspace.Id) -AccessRight Member -PrincipalType App -Identifier $($SPObjectID)

Adicionar um grupo de segurança como um membro do workspace usando o PowerShell

O script a seguir adiciona um grupo de segurança como um membro do workspace. Antes de executar o script:

  • Substitua <security-group-object-ID> pela ID de objeto que você registrou anteriormente para seu novo grupo de segurança.
  • Substitua <workspace-name> pelo nome do workspace ao qual você gostaria de conceder acesso ao grupo de segurança.
# Sign in to Power BI.
Login-PowerBI

# Set up the security group object ID.
$SGObjectID = "<security-group-object-ID>"

# Get the workspace.
$pbiWorkspace = Get-PowerBIWorkspace -Filter "name eq '<workspace-name>'"

# Add the security group to the workspace.
Add-PowerBIWorkspaceUser -Id $($pbiWorkspace.Id) -AccessRight Member -PrincipalType Group -Identifier $($SGObjectID)

Etapa 5 – Inserir seu conteúdo

Você pode inserir o conteúdo em um aplicativo de exemplo ou no próprio aplicativo.

Depois de inserir o conteúdo, você estará pronto para passar para a produção.

Observação

Para proteger seu conteúdo usando um certificado, siga as etapas descritas em Inserir conteúdo do Power BI com a entidade de serviço e um certificado.

Considerações e limitações

  • Não há suporte para Meu Workspace ao usar a entidade de serviço.
  • É necessária capacidade ao passar para produção.
  • Você não pode entrar no portal do Power BI usando a entidade de serviço.
  • Direitos de administrador do Power BI são necessários para habilitar a entidade de serviço nas configurações do desenvolvedor no Portal de Administração do Power BI.
  • Os aplicativos inseridos para sua organização não podem usar a entidade de serviço.
  • Não há suporte para gerenciamento de fluxos de dados.
  • A entidade de serviço dá suporte apenas a algumas APIs de administração somente leitura. Para habilitar o suporte da entidade de serviço para APIs de administração somente leitura, habilite as configurações de administrador do serviço do Power BI em seu locatário. Para obter mais informações, confira Habilitar a autenticação de entidade de serviço para APIs de administração somente leitura.
  • Quando você usa uma entidade de serviço com uma fonte de dados do Azure Analysis Services, a própria entidade de serviço precisa ter permissões de uma instância do Azure Analysis Services. O uso de um grupo de segurança que contenha a entidade de serviço para essa finalidade não funciona.

Conteúdo relacionado