Autenticação apenas de aplicações para scripts autónomos no PowerShell do Exchange Online e no PowerShell de Conformidade & de Segurança do PowerShell

Cenários de auditoria e relatórios no Microsoft 365 geralmente envolvem scripts autônomos no PowerShell do Exchange Online e na Segurança e Conformidade do PowerShell. No passado, a entrada autônoma exigia que você armazenasse o nome de usuário e a senha em um arquivo local ou em um cofre secreto acessado no tempo de execução. No entanto, como todos sabemos, armazenar credenciais de utilizador localmente não é uma boa prática de segurança.

A autenticação baseada em certificados (CBA) ou a autenticação apenas de aplicação, conforme descrito neste artigo, suporta cenários de automatização e scripts autónomos através de aplicações Microsoft Entra e certificados autoassinados.

Como funciona?

O módulo do PowerShell do Exchange Online utiliza a Biblioteca de Autenticação do Active Directory para obter um token apenas de aplicação com o ID da aplicação, o ID do inquilino (organização) e o thumbprint do certificado. O objeto da aplicação aprovisionado no Microsoft Entra ID tem uma Função de Diretório atribuída, que é devolvida no token de acesso. O RBAC (controle de acesso baseado em função) da sessão é configurado usando as informações de função de diretório disponíveis no token.

Exemplos de ligação

Os exemplos seguintes mostram como utilizar o módulo do PowerShell do Exchange Online com autenticação apenas de aplicação:

• Ligar através de um thumbprint de certificado:

  Observação

  O parâmetro CertificateThumbprint só é suportado no Microsoft Windows.

  O certificado tem de ser instalado no computador onde está a executar o comando. O certificado deve ser instalado no repositório de certificados do usuário.

  • PowerShell do Exchange Online:

    Connect-ExchangeOnline -CertificateThumbPrint "012THISISADEMOTHUMBPRINT" -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

  • Segurança e Conformidade do PowerShell:

    Connect-IPPSSession -CertificateThumbPrint "012THISISADEMOTHUMBPRINT" -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

• Ligar através de um objeto de certificado:

  O certificado não precisa de ser instalado no computador onde está a executar o comando. Pode armazenar o objeto de certificado remotamente. O certificado é obtido quando o script é executado.

  • PowerShell do Exchange Online:

    Connect-ExchangeOnline -Certificate <%X509Certificate2 Object%> -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

  • Segurança e Conformidade do PowerShell:

    Connect-IPPSSession -Certificate <%X509Certificate2 Object%> -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

• Ligar através de um certificado local:

  Observação

  A utilização de um comando ConvertTo-SecureString para armazenar a palavra-passe do certificado localmente derrota a finalidade de um método de ligação seguro para cenários de automatização. Utilizar um comando Get-Credential para lhe pedir a palavra-passe do certificado de forma segura não é ideal para cenários de automatização. Por outras palavras, não existe realmente uma forma automatizada e segura de ligar através de um certificado local.

  • PowerShell do Exchange Online:

    Connect-ExchangeOnline -CertificateFilePath "C:\Users\navin\Desktop\automation-cert.pfx" -CertificatePassword (Get-Credential).password -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

  • Segurança e Conformidade do PowerShell:

    Connect-IPPSSession -CertificateFilePath "C:\Users\navin\Desktop\automation-cert.pfx" -CertificatePassword (Get-Credential).password -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contosoelectronics.onmicrosoft.com"
    

Configurar autenticação somente no aplicativo

A integração inicial é necessária para autenticação usando objetos do aplicativo. O aplicativo e a entidade de serviço são usados de forma intercambiável, mas um aplicativo é como um objeto de classe, enquanto uma entidade de serviço é como uma instância da classe. Para obter mais informações, veja Objetos de principal de serviço e aplicação no ID do Microsoft Entra.

Para obter um fluxo visual detalhado sobre a criação de aplicações no Microsoft Entra ID, consulte https://aka.ms/azuread-app.

1. Registe a aplicação no Microsoft Entra ID.

2. Atribuir permissões de API para o aplicativo.

   Um objeto de aplicação tem a permissão de API DelegadaDo Microsoft Graph>User.Read por predefinição. Para que o objeto de aplicação aceda a recursos no Exchange, precisa da permissão da API de Aplicaçãodo Office 365 Exchange Online>Exchange.ManageAsApp.

3. Gerar um certificado autoassinado

   • Para autenticação apenas de aplicação no Microsoft Entra ID, normalmente utiliza um certificado para pedir acesso. Qualquer pessoa que tenha o certificado e a respetiva chave privada pode utilizar a aplicação com as permissões concedidas à aplicação.

   • Crie e configure um certificado X.509 autoassinado, que é utilizado para autenticar a sua Aplicação no ID do Microsoft Entra, ao mesmo tempo que pede o token de acesso apenas à aplicação.

   • Este procedimento é semelhante à geração de uma palavra-passe para contas de utilizador. O certificado pode ser auto-assinado também. Veja esta secção mais à frente neste artigo para obter instruções para gerar certificados no PowerShell.

     Observação

     Criptografia: os certificados de Próxima Geração (CNG) não são suportados para autenticação apenas de aplicações com o Exchange. Os certificados CNG são criados por predefinição nas versões modernas do Windows. Você deve usar um certificado de um provedor de chave CSP. Esta secção abrange dois métodos suportados para criar um certificado CSP.

4. Anexar o certificado à aplicação Microsoft Entra

5. Atribuir funções do Microsoft Entra à aplicação

   O aplicativo precisa ter as funções apropriadas RBAC atribuídas. Uma vez que as aplicações são aprovisionadas no Microsoft Entra ID, pode utilizar qualquer uma das funções incorporadas suportadas.

Passo 1: Registar a aplicação no Microsoft Entra ID

1. Abra o centro de administração do Microsoft Entra em https://portal.azure.com/.

2. Na caixa Procurar na parte superior da página, comece a escrever Registos de aplicações e, em seguida, selecione Registos de aplicações nos resultados na secção Serviços .

   

   Em alternativa, para aceder diretamente à página Registos de aplicações , utilize https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade.

3. Na página registros de aplicativo, selecione novo registro.

   

   Na página Registrar um aplicativo que é aberta, defina as seguintes configurações:

   • Nome: digite algo descritivo. Por exemplo, ExO Windows PowerShell CBA.

   • Tipos de conta suportados: verifique se as Contas apenas neste diretório organizacional (<Apenas YourOrganizationName> - Inquilino único) estão selecionadas.

     Observação

     Para tornar a aplicação multi-inquilino para cenários delegados do Exchange Online , selecione o valor Contas em qualquer diretório organizacional (Qualquer diretório do Microsoft Entra - Multi-inquilino).

   • URI de Redirecionamento (opcional): esta definição é opcional. Se precisar de utilizá-lo, configure as seguintes definições:

     • Plataforma: selecione Web.
     • URI: introduza o URI para onde o token de acesso é enviado.

     Observação

     Não pode criar credenciais para aplicações nativas, porque não pode utilizar aplicações nativas para aplicações automatizadas.

     

   Quando terminar na página Registos de aplicações , selecione Registar.

4. É levado para a página Descrição geral da aplicação que acabou de registar. Deixe esta página aberta. Você precisará usá-las na próxima etapa.

Etapa 2: atribuir permissões de API para o aplicativo

Escolha um dos seguintes métodos nesta secção para atribuir permissões de API à aplicação:

• Selecione e atribua as permissões da API a partir do portal.
• Modifique o manifesto da aplicação para atribuir permissões de API. (As organizações Microsoft 365 GCC High e DoD devem utilizar este método)

Selecionar e atribuir as permissões da API a partir do portal

1. Na página Descrição Geral da aplicação, selecione Permissões de API na secção Gerir .

   

2. Na página Permissões da API da aplicação, selecione Adicionar uma permissão.

   

3. Na lista de opções Pedir permissões de API que é aberta, selecione o separador APIs que a minha organização utiliza , comece a escrever Office 365 Exchange Online na caixa Procurar e, em seguida, selecione-o nos resultados.

   

4. Na lista de opções Que tipo de permissões a sua aplicação necessita? que é apresentada, selecione Permissões da aplicação.

5. Na lista de permissões apresentada, expanda Exchange, selecione Exchange.ManageAsApp e, em seguida, selecione Adicionar permissões.

   

6. Novamente na página de permissões da API da aplicação, verifique se o Exchange Online> exchange do Office 365.ManageAsApp está listado e contém os seguintes valores:

   • Tipo: Aplicação.

   • Consentimento do administrador obrigatório: Sim.

   • Estado: o valor incorreto atual não é concedido para <a Organização>.

     Altere este valor ao selecionar Conceder consentimento do administrador para <a Organização>, ler a caixa de diálogo de confirmação que é aberta e, em seguida, selecionar Sim.

     

     O valor Estado é agora Concedido para <a Organização>.

     

7. Para a entradauser.read predefinida do Microsoft Graph>, selecione ...>Revogue o consentimento do administrador e, em seguida, selecione Sim na caixa de diálogo de confirmação que é aberta para devolver o Estado ao valor em branco predefinido.

   

8. Feche a página atual de permissões da API (não a guia do navegador) para retornar à página de registros de aplicativos. Utilize a página Registos de aplicações num passo futuro.

Modificar o manifesto da aplicação para atribuir permissões de API

1. Na página Descrição Geral da aplicação, selecione Manifesto na secção Gerir .

   

2. Na página Manifesto da aplicação, localize a requiredResourceAccess entrada (na linha 42 ou cerca de) e faça com que a entrada se pareça com o seguinte fragmento de código:

   "requiredResourceAccess": [
       {
           "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
           "resourceAccess": [
               {
                   "id": "dc50a0fb-09a3-484d-be87-e023b12c6440",
                   "type": "Role"
               }
           ]
       },
       {
           "resourceAppId": "00000003-0000-0000-c000-000000000000",
           "resourceAccess": [
               {
                   "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d",
                   "type": "Scope"
               }
           ]
       }
   ],
   

   Observação

   Os ambientes Microsoft 365 GCC High ou DoD têm acesso apenas ao PowerShell de Conformidade & de Segurança. Utilize os seguintes valores para a requiredResourceAccess entrada:

   "requiredResourceAccess": [
       {
           "resourceAppId": "00000007-0000-0ff1-ce00-000000000000",
           "resourceAccess": [
               {
                   "id": "455e5cd2-84e8-4751-8344-5672145dfa17",
                   "type": "Role"
               }
           ]
       },
       {
           "resourceAppId": "00000003-0000-0000-c000-000000000000",
           "resourceAccess": [
               {
                   "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d",
                   "type": "Scope"
               }
           ]
       }
   ],
   

   Quando terminar na página Manifesto , selecione Guardar.

3. Ainda na página Manifesto , selecione Permissões de API na secção Gerir .

   

4. Na página permissões de API, verifique se o Exchange Online> exchange do Office 365.ManageAsApp está listado e contém os seguintes valores:

   • Tipo: Aplicação.

   • Consentimento do administrador obrigatório: Sim.

   • Estado: O valor incorreto atual não é concedido para <a organização> para a entradaExchange.ManageAsAppdo Office 365 Exchange Online>.

     Altere o valor Estado ao selecionar Conceder consentimento do administrador para <a Organização>, ler a caixa de diálogo de confirmação que é aberta e, em seguida, selecionar Sim.

     

     O valor Estado é agora Concedido para <a Organização>.

     

5. Para a entradauser.read predefinida do Microsoft Graph>, selecione ...>Revogue o consentimento do administrador e, em seguida, selecione Sim na caixa de diálogo de confirmação que é aberta para devolver o Estado ao valor em branco predefinido.

   

6. Feche a página atual de permissões da API (não a guia do navegador) para retornar à página de registros de aplicativos. Utilize a página Registos de aplicações num passo futuro.

Etapa 3: Criar um certificado autoassinado

Crie um certificado X.509 auto-assinado usando um dos seguintes métodos:

• (Recomendado) Use os cmdlets New-SelfSignedCertificate, Exportar-e Certificar e Export-PfxCertificate em uma sessão elevada (executar como administrador) do Windows PowerShell para solicitar um certificado autoassinado.cer e .pfx exportá-lo para e (SHA1 por padrão). Por exemplo:

  # Create certificate
  $mycert = New-SelfSignedCertificate -DnsName "contoso.org" -CertStoreLocation "cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange
  
  # Export certificate to .pfx file
  $mycert | Export-PfxCertificate -FilePath mycert.pfx -Password (Get-Credential).password
  
  # Export certificate to .cer file
  $mycert | Export-Certificate -FilePath mycert.cer
  

• Use o script de script Create-SelfSignedCertificate para gerar certificados SHA1.

  .\Create-SelfSignedCertificate.ps1 -CommonName "MyCompanyName" -StartDate 2021-01-06 -EndDate 2022-01-06
  

Passo 4: Anexar o certificado à aplicação Microsoft Entra

Depois de registrar o certificado com seu aplicativo, você pode usar a chave privada (.pfx arquivo) ou a miniatura para autenticação.

1. No separador Aplicações próprias na página Registo de aplicações no final do Passo 2, selecione a sua aplicação.

   Se precisar de voltar à página Registo de aplicações , utilize https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps, verifique se o separador Aplicações próprias está selecionado e, em seguida, selecione a sua aplicação.

   

2. Na página da aplicação que é aberta, selecione Certificados & segredos na secção Gerir .

   

3. Na página Certificados & segredos , selecione Carregar certificado.

   

   Na caixa de diálogo que é aberta, navegue até o certificado autoassinado (.cerarquivo) que você criou na Etapa 3.

   

   Ao terminar, selecione Adicionar.

   O certificado agora é mostrado na seção Certificados.

   

4. Feche a página atual de Certificados e segredos e, em seguida, a página de registros de aplicativoshttps://portal.azure.com/ para retornar à página principal. Você precisará usá-las na próxima etapa.

Passo 4b: Apenas cenários delegados do Exchange Online: Conceder consentimento do administrador para a aplicação multi-inquilino

Se tiver feito a aplicação multi-inquilino para cenários delegados do Exchange Online no Passo 1, terá de conceder o consentimento do administrador à permissão Exchange.ManageAsApp para que a aplicação possa executar cmdlets no Exchange Online em cada organização de inquilino. Para tal, gere um URL de consentimento do administrador para cada inquilino do cliente. Antes de qualquer pessoa utilizar a aplicação multi-inquilino para ligar ao Exchange Online na organização do inquilino, um administrador no inquilino do cliente deve abrir o seguinte URL:

https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<client-id>&scope=https://outlook.office365.com/.default

• <tenant-id> é o ID de inquilino do cliente.
• <client-id> é o ID da aplicação multi-inquilino.
• O âmbito predefinido é utilizado para conceder permissões de aplicação.

Para obter mais informações sobre a sintaxe do URL, veja Pedir as permissões de um administrador de diretórios.

Passo 5: Atribuir funções do Microsoft Entra à aplicação

Você tem duas opções:

• Atribuir funções do Microsoft Entra à aplicação
• Atribuir grupos de funções personalizados à aplicação através de principais de serviço: este método só é suportado quando se liga ao PowerShell do Exchange Online ou ao PowerShell de Conformidade do & de Segurança no modo de API REST. O PowerShell de Conformidade & de Segurança suporta o modo de API REST na v3.2.0 ou posterior.

Atribuir funções do Microsoft Entra à aplicação

As funções suportadas do Microsoft Entra estão descritas na seguinte tabela:

¹ As funções Administrador Global e Administrador do Exchange fornecem as permissões necessárias para qualquer tarefa no PowerShell do Exchange Online. Por exemplo:

• Gerenciamento de destinatários.
• Recursos de proteção e segurança. Por exemplo, relatórios antispam, antimalware, antiphishing e relatórios associados.

A função Administrador de Segurança não tem as permissões necessárias para essas mesmas tarefas.

² A Microsoft recomenda que utilize funções com menos permissões. A utilização de contas com permissões mais baixas ajuda a melhorar a segurança da sua organização. O Administrador Global é uma função altamente privilegiada que deve ser limitada a cenários de emergência quando não pode utilizar uma função existente.

Para obter instruções gerais sobre a atribuição de funções no Microsoft Entra ID, consulte Atribuir funções do Microsoft Entra aos utilizadores.

1. No Centro de administração do Microsoft Entra em https://portal.azure.com/, comece a escrever funções e administradores na caixa Procurar na parte superior da página e, em seguida, selecione Funções e administradores do Microsoft Entra nos resultados na secção Serviços .

   

   Em alternativa, para aceder diretamente à página funções e administradores do Microsoft Entra , utilize https://portal.azure.com/#view/Microsoft_AAD_IAM/AllRolesBlade.

2. Na página Funções e administradores que é aberta, localize e selecione uma das funções suportadas por clicando no nome da função (não na caixa de seleção) nos resultados.

   • PowerShell do Exchange Online: por exemplo, localize e selecione a função de administrador do Exchange .

     

   • Segurança & o PowerShell de Conformidade: por exemplo, localize e selecione a função Administrador de Conformidade .

     

3. Na página Atribuições que é aberta, selecione Adicionar tarefas.

   • PowerShell do Exchange Online:

     

   • Segurança e Conformidade do PowerShell:

     

4. No menu desdobrável Adicionar atribuições que é aberto, encontre e selecione o aplicativo que você criou na Etapa 1.

   

   Quando terminar a lista de opções Adicionar tarefas , selecione Adicionar.

5. Novamente na página Atribuições , verifique se a função foi atribuída à aplicação.

   • PowerShell do Exchange Online:

     

   • Segurança e Conformidade do PowerShell:

     

Atribuir grupos de funções personalizados à aplicação com principais de serviço

Para obter informações sobre como criar grupos de funções personalizados, consulte Criar grupos de funções no Exchange Online e Criar Grupos de funções de colaboração de & de e-mail no portal do Microsoft Defender. O grupo de funções personalizado que atribuir à aplicação pode conter qualquer combinação de funções incorporadas e personalizadas.

Para atribuir grupos de funções personalizados à aplicação através de principais de serviço, efetue os seguintes passos:

1. No Microsoft Graph PowerShell, execute os seguintes comandos para armazenar os detalhes da aplicação Microsoft Entra que registou no Passo 1 numa variável:

   Connect-MgGraph -Scopes AppRoleAssignment.ReadWrite.All,Application.Read.All
   
   $<VariableName1> = Get-MgServicePrincipal -Filter "DisplayName eq '<AppName>'"
   

   Por exemplo:

   Connect-MgGraph -Scopes AppRoleAssignment.ReadWrite.All,Application.Read.All
   
   $AzureADApp = Get-MgServicePrincipal -Filter "DisplayName eq 'ExO PowerShell CBA'"
   

   Para obter informações detalhadas sobre a sintaxe e os parâmetros, veja Get-MgServicePrincipal.

2. Na mesma janela do PowerShell, ligue-se ao PowerShell do Exchange Online ou ao PowerShell de Conformidade do & de Segurança e execute os seguintes comandos para:

   • Crie um objeto de principal de serviço para a aplicação Microsoft Entra.
   • Armazene os detalhes do principal de serviço numa variável a utilizar no próximo passo.

   New-ServicePrincipal -AppId $<VariableName1>.AppId -ObjectId $<VariableName1>.Id -DisplayName "<Descriptive Name>"
   
   $<VariableName2> = Get-ServicePrincipal -Identity "<Descriptive Name>"
   

   Por exemplo:

   New-ServicePrincipal -AppId $AzureADApp.AppId -ObjectId $AzureADApp.Id -DisplayName "SP for Azure AD App ExO PowerShell CBA"
   
   $SP = Get-ServicePrincipal -Identity "SP for Azure AD App ExO PowerShell CBA"
   

   Para obter informações detalhadas sobre a sintaxe e os parâmetros, veja New-ServicePrincipal.

3. No PowerShell do Exchange Online ou no PowerShell de Conformidade do & de Segurança, execute o seguinte comando para adicionar o principal de serviço como membro do grupo de funções personalizado:

   Add-RoleGroupMember -Identity "<CustomRoleGroupName>" -Member <$<VariableName2>.Identity | $<VariableName2>.ObjectId | $<VariableName2>.Id>
   

   Por exemplo:

   Add-RoleGroupMember -Identity "Contoso View-Only Recipients" -Member $SP.Identity
   

   Para obter informações detalhadas sobre sintaxe e parâmetros, veja Add-RoleGroupMember.