> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/automatizacao/connecting-azure-automation.md).

# Ligar o Azure Automation

Ligue uma Azure Automation Account ao RealmJoin Portal com o módulo RealmJoin PowerShell, para que o RealmJoin possa implementar, executar e monitorizar runbooks no seu tenant.

## Visão geral

Para permitir que o RealmJoin Portal forneça [runbooks](https://docs.realmjoin.com/pt/automatizacao/runbooks.md) para automatizar tarefas diárias, tem de ligar uma [Azure Automation](https://learn.microsoft.com/en-us/azure/automation/overview) Conta. Ela atua como o anfitrião dos seus runbooks e fornece as [permissões](https://docs.realmjoin.com/pt/automatizacao/connecting-azure-automation/azure-ad-roles-and-permissions.md) de que os runbooks precisam para funcionar no seu ambiente.

A Conta de Automação é configurada com o [módulo PowerShell do RealmJoin](https://docs.realmjoin.com/pt/implementacao/onboarding-realmjoin-portal/advanced-setup.md). O Portal gera para si um comando pronto a copiar — não há registo de aplicação para criar nem segredo de cliente para gerir.

{% hint style="info" %}
Os runbooks já estão configurados para o seu Tenant com o legado **RealmJoin Runbook Management** registo de aplicação? Então veja [Mudar para a aplicação gerida do RealmJoin](https://docs.realmjoin.com/pt/automatizacao/connecting-azure-automation/managed-app-migration.md). Mantém a sua Automation Account e os seus runbooks, e remove o segredo de cliente por Tenant.
{% endhint %}

## Considerações

Da Conta de Automação [Identidade gerida](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview) requer extensas [permissões](https://docs.realmjoin.com/pt/automatizacao/connecting-azure-automation/azure-ad-roles-and-permissions.md) no seu ambiente, como a capacidade de modificar objetos de grupo ou de utilizador no Entra ID ou de gerir caixas de correio no Exchange Online. Limite o acesso administrativo a esta conta para evitar a utilização indevida destes privilégios.

Ao utilizar uma Conta de Automação existente, note que o RealmJoin Portal cria, atualiza e remove automaticamente os runbooks provenientes do [repositório online partilhado de runbooks](https://github.com/realmjoin/realmjoin-runbooks). Esta funcionalidade pode não ser suportada numa Conta de Automação existente. Se não tiver a certeza, recomendamos criar uma Conta de Automação do Azure dedicada para os runbooks do RealmJoin — o que o comando de configuração faz por si.

## O que a configuração implementa

A execução do comando de configuração cria:

* O **Recursos Azure do RealmJoin** service principal no seu tenant Entra ID (se ainda não existir)
* Um **Conta de Automação** com uma identidade gerida atribuída pelo sistema, na região do grupo de recursos — ou a sua Conta de Automação existente, se indicar uma
* **Contribuidor** para o Service Principal do RealmJoin, com âmbito nessa Conta de Automação, para que o RealmJoin possa sincronizar e iniciar runbooks
* O **permissões de aplicação** para a identidade gerida que o módulo inclui — Microsoft Graph, Office 365 Exchange Online, Windows Defender ATP e SharePoint Online

O RealmJoin autentica-se no Azure com a sua própria aplicação multi-inquilino. Não é criado nenhum registo de aplicação nem segredo de cliente no seu Tenant, e o RealmJoin não recebe permissões fora dessa Conta de Automação.

{% hint style="warning" %}
Da identidade gerida **funções de diretório do Entra ID** — Intune Administrator, Exchange Administrator, User Administrator e assim por diante — são **não** atribuídas pelo comando de configuração. Ainda têm de ser concedidas separadamente, veja [Atribuir funções e permissões](https://docs.realmjoin.com/pt/automatizacao/connecting-azure-automation/azure-ad-roles-and-permissions.md#granting-roles-and-permissions). Sem elas, grande parte dos runbooks partilhados não funcionará.
{% endhint %}

## Pré-requisitos

### No Portal RealmJoin

* Uma função que concede acesso à área de Definições (`CanReadSettingsDetails`, consulte [Permissões Disponíveis](https://docs.realmjoin.com/pt/administracao-e-definicoes/permission/custom-roles/available-permissions.md)). A página de definições gera o comando de configuração incluindo um token de integração de curta duração.

### No Azure

* Uma subscrição Azure e uma **grupo de recursos existente** para implementar — o módulo não cria o grupo de recursos. Recomenda-se um grupo de recursos separado para a Conta de Automação.
* Opcionalmente, uma Conta de Automação existente. Se não indicar uma, será criada uma conta para si.

### Na máquina que executa o PowerShell

* **PowerShell 5.1** ou posterior (Windows PowerShell ou PowerShell 7)
* Acesso à [PowerShell Gallery](https://www.powershellgallery.com/packages/RealmJoin) para instalar o módulo RealmJoin
* O `Az.Accounts`, `Az.Resources` e `Az.Automation` módulos — o módulo RealmJoin instala-os automaticamente nas versões fixadas, para o utilizador atual

### Permissões da conta com a qual inicia sessão

* **Microsoft Entra ID:** permissão para criar Service Principals **e para conceder permissões de aplicação** — a configuração atribui funções de aplicação do Graph, do Exchange, do Defender e do SharePoint à identidade gerida. Na prática, isto significa *Administrador Global* ou *Administrador de Funções Privilegiadas*.
* **subscrição Azure:** permissão para implementar no grupo de recursos **e** para criar atribuições de função nele — por exemplo *Proprietário*, ou *Contribuidor* combinado com *Administrador de Acesso de Utilizador* / *Administrador de Controlo de Acesso Baseado em Funções*.
* O início de sessão ocorre através de `Connect-AzAccount`, que usa a aplicação **Azure PowerShell** de primeira parte. Tenants que restrinjam o consentimento do utilizador podem ter de conceder primeiro consentimento de administrador a essa aplicação.

{% hint style="warning" %}
Execute o comando numa **sessão local recém-aberta** sessão do PowerShell e evite **Azure Cloud Shell**. O módulo RealmJoin requer versões exatas dos módulos `Az.*` módulos. Se já estiver carregada uma versão diferente na sessão — o que normalmente acontece no Cloud Shell — o módulo termina com um conflito de versões que só pode ser resolvido ao abrir uma nova sessão.
{% endhint %}

## Configuração

{% stepper %}
{% step %}

#### Prepare o grupo de recursos

No Azure Portal, crie ou escolha o grupo de recursos que deve conter a Conta de Automação. Anote o respetivo nome e o ID da subscrição em que se encontra.

Se pretender usar um **existente** Conta de Automação, anote também o respetivo nome.
{% endstep %}

{% step %}

#### Copie o comando do RealmJoin Portal

No RealmJoin Portal, vá para **Definições → Runbooks** (<https://portal.realmjoin.com/settings/runbooks-configuration>).

A página indica que a configuração dos runbooks é gerida através do módulo PowerShell do RealmJoin e mostra um bloco de comandos. Use o **Copiar** para o copiar.

```powershell
$latest = [version](Find-Module RealmJoin -Repository PSGallery -ErrorAction Stop).Version
if (-not (Get-Module -ListAvailable RealmJoin | Where-Object Version -ge $latest)) {
    Install-Module RealmJoin -Force -AllowClobber -ErrorAction Stop
}
Import-Module RealmJoin -Force
Set-RJAutomationAccount -Token "<Token>" 6>&1
```

{% hint style="info" %}
**Sobre `6>&1`:** estes comandos comunicam o seu progresso no fluxo de Informação do PowerShell. A `6>&1` redireção mostra essa saída na consola — sem ela não verá quaisquer mensagens de progresso.
{% endhint %}
{% endstep %}

{% step %}

#### Adicione os parâmetros de destino

`Set-RJAutomationAccount` precisa de saber onde implementar. Preencha a última linha antes de o executar:

```powershell
Set-RJAutomationAccount -ResourceGroupName "rg-realmjoin" -SubscriptionId "<SubscriptionId>" -Token "<Token>" 6>&1
```

* `-ResourceGroupName` é obrigatório. Se o omitir, o PowerShell pedir-lho-á.
* `-SubscriptionId` é opcional — sem ele, é usada a subscrição do seu contexto Azure atual e ser-lhe-á pedido que escolha se houver várias disponíveis.
* `-AutomationAccountName` é opcional. Passe-o para definir o nome de uma nova Conta de Automação ou para usar uma **existente** conta; caso contrário, será criada uma nova com um nome gerado.

{% hint style="warning" %}
Apontar o comando para uma Conta de Automação existente também impõe as definições que o RealmJoin espera nela: uma identidade gerida atribuída pelo sistema, o SKU Basic e o acesso à rede pública. Verifique se isso corresponde aos seus requisitos antes de reutilizar uma conta.
{% endhint %}
{% endstep %}

{% step %}

#### Execute o comando

Cole o bloco numa nova sessão do PowerShell e execute-o. O token é válido por cerca de uma hora — se tiver expirado, recarregue a página de definições e copie novamente o comando.

Ser-lhe-á pedido para iniciar sessão com `Connect-AzAccount`. Se a sua conta tiver acesso a vários tenants ou subscrições, o módulo pede-lhe que escolha.

A implementação decorre em três passos — Service Principal, Automation Account, permissões — e apresenta cada recurso à medida que é criado. Uma única execução demora normalmente alguns minutos.

{% hint style="info" %}
Quer ver primeiro o que aconteceria? Adicione `-WhatIf` para uma pré-visualização What-If do Azure Resource Manager. Note que o início de sessão e a instalação dos `Az` módulos continuam a acontecer, porque a pré-visualização precisa de ambos.
{% endhint %}

{% hint style="info" %}
**Terminar sessão depois:** o início de sessão do Azure mantém-se ativo depois de o comando terminar. Quando acabar, execute `Disconnect-AzAccount` para terminar sessão da sessão existente.
{% endhint %}
{% endstep %}

{% step %}

#### Atribua as funções do Entra ID à identidade gerida

A configuração concede à identidade gerida as suas permissões de aplicação, mas não as suas funções de diretório do Entra ID. Atribua-as agora — veja [Atribuir funções e permissões](https://docs.realmjoin.com/pt/automatizacao/connecting-azure-automation/azure-ad-roles-and-permissions.md#granting-roles-and-permissions) a lista atual e um script que o faz.

O ID do objeto da identidade gerida é mostrado no Azure Portal na Conta de Automação, em Definições da conta > Identidade.

<figure><img src="https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2F4ecZSM3NW9PWJJlaNmR4%2Fimage.png?alt=media&amp;token=e5d5b56b-50f3-4f35-a41b-7cb4230dd3f3" alt=""><figcaption><p>Identidade gerida da Conta de Automação</p></figcaption></figure>
{% endstep %}

{% step %}

#### Verifique no Portal e inicie a primeira sincronização

Regresse a **Definições → Runbooks** e selecione **Atualizar**. O RealmJoin deteta a nova configuração e inicia a importação inicial dos runbooks. Deixe a página aberta até a sincronização estar concluída.

A subscrição, o grupo de recursos, o nome da Conta de Automação e a localização são agora apresentados em modo só de leitura em **Ligação ao Azure** — passam a ser mantidos pelo módulo PowerShell.
{% endstep %}
{% endstepper %}

## Definições que gere no Portal

Duas definições continuam editáveis em **Definições → Runbooks** após a configuração:

* **Branch** — a ramificação do [repositório partilhado de runbooks](https://github.com/realmjoin/realmjoin-runbooks) que pretende seguir. A configuração define isto como `production`, que é a escolha certa, a menos que tenha um motivo para divergir.
* **Ativar a sincronização do Hybrid Runbook Worker** e o grupo de workers a utilizar, veja [Hybrid Runbook Worker](https://docs.realmjoin.com/pt/automatizacao/runbooks/hybrid-runbook-worker.md). O grupo tem de estar registado na Conta de Automação antes de poder ser selecionado aqui.

Guardar qualquer um deles desencadeia uma sincronização dos runbooks.

Se mais tarde tiver problemas de configuração ou de permissões, o **Mostrar cmdlet** botão por baixo de Ligação ao Azure volta a apresentar o comando — executá-lo novamente é seguro e apenas aplica o que estiver em falta.

## Configuração legada (registo de aplicação por Tenant)

{% hint style="warning" %}
A configuração abaixo cria um **RealmJoin Runbook Management** registo de aplicação com um segredo de cliente no seu Tenant. Está documentado apenas como referência para Tenants que foram configurados desta forma no passado. Não o utilize para novas configurações — siga o [Configuração](#setup) acima, ou [mudar uma configuração existente para a aplicação gerida](https://docs.realmjoin.com/pt/automatizacao/connecting-azure-automation/managed-app-migration.md).
{% endhint %}

<details>

<summary>Mostrar a configuração legada</summary>

Neste percurso, a Conta de Automação foi criada manualmente no Azure Portal, as suas permissões foram atribuídas com dois scripts externos, e o RealmJoin autenticou-se com um registo de aplicação por Tenant e um segredo de cliente.

**Parte 1 — Criar uma Conta de Automação do Azure**

1. Navegue até ao seu [Azure Portal > Contas de Automação](https://portal.azure.com/#create/Microsoft.AutomationAccount) e crie uma nova Conta de Automação.
2. No separador Básico, escolha a sua Subscrição, Grupo de Recursos, Nome da Conta de Automação e Região.
3. No separador Avançado, certifique-se de que a Identidade gerida atribuída pelo sistema está ativada.
4. Selecione Rever + Criar e crie a sua Conta de Automação.
5. Navegue até ao grupo de recursos que contém a Conta de Automação e, no separador IAM, atribua a função de Contributor à Conta de Automação.

![Criar a Conta de Automação](https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FqjBLc2zH3XCCqfAViEsU%2Fimage.png?alt=media\&token=257816e0-eb8a-478c-973f-fb288324d8c8)

![Ativar a identidade gerida atribuída pelo sistema](https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FM9N3OxNzrzQXFxSaKIpP%2Fimage.png?alt=media\&token=1e7c4d5b-d604-415b-89e0-4816a7f04a26)

**Parte 2 — Atribuir permissões à Conta de Automação**

As permissões da identidade gerida não podem ser concedidas através do Azure Portal. Os [approle-and-directoryrole-granter](https://github.com/Workplace-Foundation/approle-and-directoryrole-granter) scripts atribuem tanto as permissões da aplicação como as funções do Entra ID a partir dos ficheiros JSON publicados no [repositório de runbooks](https://github.com/realmjoin/realmjoin-runbooks/tree/production/docs/other/json):

```powershell
. .\GrantAppPermToEntApp.ps1 -enterpriseAppObjId "<ManagedIdentityObjectId>" -permissionsTemplate .\AllRealmJoinRunbooks_collected_permissions.json
. .\AssignAzureADRoleToEntApp.ps1 -objectId "<ManagedIdentityObjectId>" -rolesTemplate .\AllRealmJoinRunbooks_collected_rbacroles.json
```

**Parte 3 — Criar o Service Principal para o RealmJoin**

No Portal, em Definições > Runbooks, introduziram-se primeiro o ID do Tenant, o ID da Subscrição e o Grupo de Recursos; a página mostrou então um excerto da Azure CLI para executar, que criou o **RealmJoin Runbook Management** registo de aplicação com direitos de Contributor no grupo de recursos:

```
az provider register --namespace Microsoft.Automation
az ad sp create-for-rbac -n "RealmJoin Runbook Management" --role contributor --scopes /subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>
```

**Parte 4 — Concluir o assistente**

De volta ao Portal, o `appId` e `palavra-passe` desse resultado foram introduzidos juntamente com o nome da Conta de Automação, a ramificação do repositório partilhado de runbooks (`production`) e a localização da Conta de Automação. A gravação iniciou a importação inicial dos runbooks.

![Ligação da Conta de Automação no RealmJoin Portal](https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FA0X3M2c9d13pxVt87Pf8%2Fimage.png?alt=media\&token=8e2f2b18-c3b1-4704-8cc8-eb4d43297dd1)

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/pt/automatizacao/connecting-azure-automation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
