Incorporar conteúdo do Power BI com a entidade de serviço e um segredo de aplicativo

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

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

Para autenticar, a entidade de serviço usa a ID do aplicativo Microsoft Entra e uma das seguintes opções:

• Um certificado
• Um segredo de aplicação

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

Nota

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

• Saiba mais sobre como obter tokens de acesso do Microsoft Entra ID usando chaves secretas ou certificados.
• Para proteger sua solução usando um certificado, conclua as instruções neste artigo e siga as etapas descritas em Incorporar conteúdo do Power BI com entidade de serviço e um certificado.

Método

Para usar a entidade de serviço e um ID de aplicativo para análises incorporadas, siga as etapas a seguir. As seções subsequentes descrevem essas etapas em detalhes.

1. Crie um aplicativo Microsoft Entra.

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

   Nota

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

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

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

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

5. Incorpore o seu conteúdo.

Importante

Um aplicativo Microsoft Entra não exige que você configure permissões delegadas ou permissões de aplicativo no portal do Azure quando ele tiver sido criado para uma entidade de serviço. Quando você cria um aplicativo Microsoft Entra para uma entidade de serviço acessar a API REST do Power BI, recomendamos que você evite adicionar permissões. Eles nunca são usados e podem causar erros difíceis de solucionar.

Etapa 1 - Criar um aplicativo Microsoft Entra

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

• Crie o aplicativo no portal do Azure.
• Crie o aplicativo usando o PowerShell.

Criar um aplicativo Microsoft Entra no portal do Azure

1. Inicie sessão no portal do Azure.

2. Pesquise e selecione Registos de aplicações.

   

3. Selecione Novo registo.

   

4. Preencha as informações necessárias:

   • Nome - Introduza um nome para a sua aplicação.
   • Tipos de conta suportados - Selecione os tipos de conta suportados.
   • (Opcional) URI de redirecionamento - Insira um URI, se necessário.

5. Selecione Registar.

6. Depois de 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.

   

7. Selecione Certificados & segredos.

   

8. Selecione Novo segredo do cliente.

   

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 secreto do cliente.

    

    Nota

    Depois de sair desta janela, o valor secreto do cliente fica oculto e não é possível visualizá-lo ou copiá-lo novamente.

Criar um aplicativo Microsoft Entra usando o PowerShell

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

• Instale a versão mais recente do PowerShell.
• Instale o SDK do Microsoft Graph PowerShell.

Depois que o script for executado, 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 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 criada a esse grupo de segurança.

Nota

Se você quiser habilitar o acesso da entidade de serviço para toda a organização, ignore esta etapa.

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

• Manualmente (no Azure)
• Utilizar o PowerShell

Criar um grupo de segurança manualmente

Para criar um grupo de segurança do Azure manualmente, 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ê gravou 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 administrador do serviço do Power BI

Para que um aplicativo Microsoft Entra acesse o conteúdo e as APIs do Power BI, um administrador do Power BI precisa habilitar as seguintes configurações:

• Incorporar conteúdo em aplicações
• Permitir que os principais de serviço utilizem as APIs do Power BI

No portal de Administração do Power BI, aceda a Definições do inquilino e desloque-se para baixo até Definições do programador.

• Habilite Incorporar conteúdo em aplicativos para toda a organização ou para o grupo de segurança específico que você criou na ID do Microsoft Entra.

  

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

  

  Importante

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

  Para restringir o acesso da entidade de serviço a configurações específicas de locatário, permita o acesso apenas 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 - Adicionar a entidade de serviço ao seu espaço de trabalho

Seu aplicativo Microsoft Entra pode acessar seus relatórios, painéis e modelos semânticos do Power BI somente quando tiver acesso ao seu 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 espaço de trabalho como membro ou administrador.

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

• Manualmente
• Utilizar o PowerShell
• Usar o Grupos - adicionar API de usuário de grupo

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

1. No serviço do Power BI, role até o espaço de trabalho para o qual você deseja habilitar o acesso. No menu Mais, selecione Acesso ao espaço de trabalho.

   

2. No painel Acesso, em Adicionar administradores, membros ou colaboradores, adicione uma das seguintes opções:

   • A sua entidade de serviço. O nome da entidade de serviço é o Nome para exibição do aplicativo Microsoft Entra, conforme aparece na guia Visão geral do aplicativo Microsoft Entra.
   • O grupo de segurança que inclui a entidade de serviço.

3. No menu suspenso, selecione Membro ou Administrador.

4. Selecione Adicionar.

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

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

Adicionar uma entidade de serviço como membro do espaço de trabalho usando o PowerShell

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

• Substitua <service-principal-object-ID> pela ID do objeto que você registrou anteriormente para a nova entidade de serviço.
• Substitua <workspace-name> pelo nome do espaço de trabalho ao qual você deseja 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 membro do espaço de trabalho usando o PowerShell

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

• Substitua <security-group-object-ID> pela ID do objeto que você registrou anteriormente para seu novo grupo de segurança.
• Substitua <workspace-name> pelo nome do espaço de trabalho ao qual você deseja 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 - Incorporar seu conteúdo

Você pode incorporar seu conteúdo em um aplicativo de exemplo ou em seu próprio aplicativo.

Depois que o conteúdo for incorporado, você estará pronto para passar para a produção.

Nota

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

Considerações e limitações

• Meu espaço de trabalho não é suportado ao usar a entidade de serviço.
• É necessária uma capacidade quando se passa para a produção.
• Não é possível entrar no portal do Power BI usando a entidade de serviço.
• Os 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.
• Incorporar para sua organização Os aplicativos não podem usar a entidade de serviço.
• O gerenciamento de fluxos de dados não é suportado.
• A entidade de serviço suporta apenas algumas APIs de administração somente leitura. Para habilitar o suporte da entidade de serviço para APIs de administração somente leitura, você precisa habilitar as configurações de administrador de serviço do Power BI em seu locatário. Para obter mais informações, consulte Habilitar a autenticação da entidade de serviço para APIs de administração somente leitura.
• Quando você usa a entidade de serviço com uma fonte de dados do Azure Analysis Services , a própria entidade de serviço deve ter permissões de instância do Azure Analysis Services. Usar um grupo de segurança que contenha a entidade de serviço para essa finalidade não funciona.

Conteúdos relacionados

• Registar uma aplicação
• Power BI Embedded para os seus clientes
• Objetos de aplicação e de principal de serviço no Microsoft Entra ID