> For the complete documentation index, see [llms.txt](https://docs.powerembedded.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.powerembedded.com.br/documentacao-tecnica/instalacao-do-power-embedded/tutorial-de-instalacao.md).

# Tutorial de Instalação

Para facilitar a instalação do **Power Embedded**, elaboramos este tutorial com o passo a passo necessário para configurar o ambiente e realizar a integração com o **Azure**.

### Criando o Aplicativo do Power Embedded no Azure AD

Nesta etapa, será criado no **Azure AD** o aplicativo que será utilizado pelo Power Embedded para realizar a integração com o ambiente da organização.

Para iniciar, acesse o Microsoft Entra ID no portal do Azure e navegue até App Registrations ( registro de aplicativos)

1. **Definição do nome do Aplicativo:** Na tela de registros de aplicativo, clique em **"Novo Registro"**

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2FnCUtXntMBXmplv2MiVTT%2Fimage.png?alt=media&amp;token=5e931d7b-ee23-45f4-a433-88f666c6b6e7" alt=""><figcaption></figcaption></figure>

2. **ID do Aplicativo**: Na tela de registro, informe um **nome para o aplicativo**, de acordo com o padrão de identificação utilizado pela organização. Como sugestão, utilizamos o nome **PowerEmbedde-App.** \
   Após informar o nome, clique em **Registrar**, localizado na parte inferior da página.

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2FKBdra9O6FovhKJukLIIJ%2Fimage.png?alt=media&amp;token=c41b5f43-6267-4749-a380-64307dcf9af2" alt=""><figcaption></figcaption></figure>

3. Após a criação, você será direcionado para a tela de **visão geral (Overview)** do aplicativo.

   Localize o campo **ID do Aplicativo (cliente)** e copie o valor apresentado. Recomendamos salvá-lo temporariamente em um local seguro, pois ele será utilizado posteriormente na configuração do Power Embedded.

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2FQYSFlivKCdmUbQ4FV5l0%2Fimage.png?alt=media&amp;token=5bf2b835-f900-43be-945c-30b12bab7422" alt=""><figcaption></figcaption></figure>

Esse valor deverá ser informado no campo **ID do Cliente do Power BI**, disponível nas configurações da organização no **Power Embedded**.<br>

4. **Criando Segredo do Aplicativo:** No menu lateral do aplicativo, acesse **Certificados e Segredos** e, em seguida, clique em **Novo Segredo do Cliente**.

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2FNRvjcq1hLLjVDr9VZkbd%2Fimage.png?alt=media&amp;token=d5c3a0d8-0a52-4fe7-9383-106a6ec285b5" alt=""><figcaption></figcaption></figure>

Na tela de criação do segredo:

* Informe uma **descrição** para identificar o segredo.
* Selecione o período de **validade** desejado.
* Clique em **Add** para criar o segredo.

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2FPsUggB1mnWVotZ4bJbPo%2Fimage.png?alt=media&amp;token=24bb28f8-026a-49f5-b053-fd8940af41f7" alt=""><figcaption></figcaption></figure>

OBS: Recomendamos utilizar uma validade de **24 meses**, reduzindo a necessidade de renovação frequente.

{% hint style="info" icon="message" %}
**Importante:** o client secret possui uma data de expiração. Quando o segredo expirar, a autenticação utilizada pelo Power Embedded deixará de funcionar. Nesse caso, será necessário criar um novo segredo e atualizar a chave nas configurações do Power Embedded.
{% endhint %}

5. **Valor do Segredo**:  Após clicar em **Add**, o segredo será criado e aparecerá na lista de **Client secrets**.

   Localize o campo **Valor** e copie o valor utilizando o botão de cópia ao lado.

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2FbTHTLsSre1zFaPvROek9%2Fimage.png?alt=media&amp;token=452f3952-6411-43ef-8e5d-c95de0c67b00" alt=""><figcaption></figcaption></figure>

{% hint style="danger" icon="exclamation" %}
**Atenção:** o valor do segredo é exibido apenas no momento da criação. Depois que essa tela for fechada, o valor não poderá ser consultado novamente no Azure. Caso a chave seja perdida, será necessário criar um novo **Client Secret**.
{% endhint %}

Após copiar o valor, armazene-o temporariamente em um local seguro.

Esse valor deverá ser informado no campo **Chave de Acesso do Cliente do Power BI**, disponível na tela de configuração do **Power Embedded**.

{% hint style="info" icon="message" %}
**Importante:** o **Application (client) ID** e o **Client Secret Value** são informações diferentes e ambos serão necessários para configurar a integração. O primeiro identifica o aplicativo; o segundo é utilizado como credencial para autenticação.
{% endhint %}

### Sincronizar usuários e grupos do Azure AD (Entra ID)

Para permitir que o Power Embedded consulte e importe **usuários e grupos** do ambiente da organização, é necessário configurar as permissões do aplicativo no **Microsoft Graph**.

Na mesma tela de **Registro de aplicativo**, siga as etapas abaixo.

1. **Acessar as permissões da API:** No menu lateral, clique em **Permissão de APIs** e, em seguida, em **Add a permissão**.

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2FRwV3kNaBrh0gp1fRpODA%2Fimage.png?alt=media&amp;token=66dafa74-632f-46d4-9209-b81163f0aea8" alt=""><figcaption></figcaption></figure>

2. **Selecionar o Microsoft Graph:** Na tela de seleção de APIs, clique em **Microsoft Graph**. Em seguida, selecione **Adicionar uma permissão**

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2FLHAKHO0gk9fj6AoiBzrR%2Fimage.png?alt=media&amp;token=3a1acfc0-4676-448e-a8c8-dbbec78f19a4" alt=""><figcaption></figcaption></figure>

3. **Adicionar a permissão de diretório:** Na lista de permissões, pesquise por **Directory** e selecione **Directory.Read.All**. Essa permissão permite que o aplicativo consulte informações do diretório, incluindo usuários e grupos. \
   Após selecionar a permissão, clique em **Adicionar permissão**.

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2F9n4PcHwkGQc2huklAG9u%2Fimage.png?alt=media&amp;token=415140c0-36c1-4a50-b716-7f16578a3c08" alt=""><figcaption></figcaption></figure>

Caso queira utilizar uma permissão menos privilegiada, pode liberar apenas as permissões "**User.Read.All**" e "**Group.Read.All**".

> Alternativa de menor privilégio: caso a organização prefira conceder apenas as permissões necessárias para consulta de usuários e grupos, é possível utilizar User.Read.All e Group.Read.All em vez de Directory.Read.All.

4. **Conceder o consentimento do administrador:** Após adicionar as permissões, é necessário conceder o consentimento de administrador para que o aplicativo possa utilizá-las.

   Para isso, clique em **Grant admin consent for**.

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2FmAKRK3WzYxQQrQXwXGYN%2Fimage.png?alt=media&amp;token=5db52ecc-1f9a-46a8-9e3e-00ec110de235" alt=""><figcaption></figcaption></figure>

Após concluir essa configuração e as demais etapas da instalação, o Power Embedded estará autorizado a consultar o diretório do **Microsoft Entra ID**, permitindo a importação de **usuários e grupos** para o portal.

{% hint style="info" icon="message" %}
**Importante:** o consentimento de administrador deve ser concedido por um usuário que possua as permissões necessárias no Microsoft Entra ID
{% endhint %}

### Adicionando o usuário do Power Embedded a um novo grupo do AD

Para conceder permissões no **Portal de Administração do Power BI** ao **Service Principal** que você acabou de criar, é obrigatório que ele faça parte de um **grupo de segurança do Azure AD (Entra ID)**.

1. Pesquise por **"Grupos"** na barra de pesquisas e recursos na parte superior central.
2. Clique no botão **" Novo Grupo"**&#x20;

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2FATSmkqamFQ1Zo8pf5jgI%2Fimage.png?alt=media&amp;token=b26c8a3e-bf8e-40b0-b67e-a3d4bc9f3194" alt=""><figcaption></figcaption></figure>

3. No campo tipo de grupo, selecione **Segurança**.

   Em seguida, informe um nome para o grupo **"PowerEmbedded-Group"**. O nome fica a critério da organização e pode seguir o padrão utilizado para identificação de grupos no ambiente.
4. Abaixo, no campo Membro, sclique em "nenhum membro selecionado".&#x20;

   Na tela de seleção, pesquise pelo nome do **Service Principal** criado anteriormente **"PowerEmbedded-App"**

   Selecione o aplicativo na lista e clique em **Selecionar.**

<figure><img src="https://2938845060-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft2gQSHbraGsYbDGTmWAa%2Fuploads%2FifxujnGtsJvyNcVeAQKr%2Fimage.png?alt=media&amp;token=b67bb25a-c09c-4d92-8481-d898e327f29e" alt=""><figcaption></figcaption></figure>

Após adicionar o Service Principal, revise as configurações do grupo e clique em **Criar.**

{% hint style="info" icon="message" %}
**Importante:** o grupo criado nesta etapa será utilizado nas configurações do **Portal de Administração do Power BI** para limitar a aplicação das permissões ao Service Principal do Power Embedded.
{% endhint %}