Microsoft Office 365 Scope

UiPath.MicrosoftOffice365.Activities.Office365ApplicationScope

Description

Usa a plataforma de identidade da Microsoft para estabelecer uma conexão autenticada entre o UiPath e seu aplicativo Microsoft 365. Essa conexão autenticada permite que um Robot chame a API do Microsoft Graph para ler e escrever recursos em seu nome.

Importante: A partir da versão beta 2.5.0, você pode usar as atividades Microsoft 365 mais recentes dentro da atividade Scope. Para saber como usar as atividades do Integration Service com o Microsoft 365 Application Scope, consulte Como usar as atividades Microsoft 365 sem as conexões do Integration Service.

Compatibilidade do projeto

Windows - Legado | Windows

Visão geral

Para estabelecer sua conexão autenticada, primeiro registre seu aplicativo Microsoft 365 em seu Azure Active Directory (usando sua conta pessoal, profissional e/ou escolar do Microsoft 365). Ao registrar seu aplicativo, você atribui as permissões da API do Microsoft Graph, que especificam os recursos que um Robô pode acessar em seu nome.

Após registrar seu aplicativo Microsoft 365, o Azure Active Directory atribui uma ID de aplicativo (cliente) exclusiva, que você insere na atividade Microsoft 365 Scope . A ID do aplicativo é usada para coletar as informações necessárias sobre o seu aplicativo registrado para iniciar a autenticação.

Para saber mais sobre o registro de seu aplicativo e atribuir permissão, consulte o guia de Configuração . Este guia fornece instruções passo a passo para configurar seu aplicativo Microsoft 365 para automação.

Observação: para obter detalhes sobre escopos e permissões de APIs, consulte Microsoft 365 e Google Workspace Cards - Permissões e escopos de APIs.

Tipos de autenticação

Tipos de autenticação	como usuário	Como um aplicativo (executado como serviço em segundo plano)	Assistido	Não Assistido	Sem supervisão (MFA ativado)	Detalhes
Token Interativo						Você tem a opção de registrar e usar seu próprio aplicativo do Azure AD (ou seja, OAuthApplication = Custom) ou aquele fornecido pela UiPath (OAuthApplication = UiPath).
Autenticação integrada do Windows (IWA)						Funciona apenas para usuários federados e se seu aplicativo registrado do Azure estiver configurado para oferecer suporte a IWA. Não funciona para autenticação multifator (MFA). Veja os detalhes aqui: IWA no GitHub
UsernameAndPassword						Não recomendado, fornecido apenas por motivos herdados (vai contra os princípios da autenticação moderna). Não funciona para a autenticação de múltiplos fatores (MFA). Veja os detalhes aqui: Usuário e senha no GitHub
ID do Aplicativo e Segredo						Recomendado para execuções autônomas ou quando você deseja acessar a API do Microsoft Graph como um aplicativo (um serviço/daemon em segundo plano) sem um usuário conectado.
IdDoAplicativo e Certificado						Disponível a partir da v1.9.0. Muito semelhante ao ID e segredo do aplicativo. A única diferença é o uso de um certificado como um segredo em vez de uma string de segredo do cliente. Consulte a documentação oficial.

Configuração

• Método de conexão — selecione o método de conexão que você deseja usar. As opções disponíveis no menu suspenso são:
  • Painel de propriedades - Configure os detalhes da conexão no painel de propriedades.
  • Ativo - Use ativos de credenciais do Orchestrator. Recomendamos que você use esta opção.

Método de conexão do ativo

Quando você seleciona essa opção, os campos de autenticação exibidos no Painel de propriedades ficam ocultos, porque todas as informações de autenticação estão armazenadas dentro do ativo.

• Ativos de conexão - Navegue pelas pastas do Orchestrator para selecionar um ativo. Este campo aceita variáveis IResource . Selecione o botão Gerenciar ativos para abrir o Orchestrator. A lista de ativos disponíveis depende do Orchestrator ao qual seu Studio e o Robô estão conectados.
  • Use o menu do botão Mais para selecionar Recarregar ativos se você tiver atualizado seus ativos no Orchestrator. Observe que se você adicionar um novo ativo no Orchestrator enquanto estiver usando o Studio Desktop, ele não ficará disponível imediatamente na atividade Scope.

Consulte o formato do ativo em Como usar atividades Microsoft 365 sem conexões do Integration Service.

Autenticação

• Endereço de email do usuário representado - O endereço de e-mail do usuário representado. Usado para permissões do aplicativo.

Nome de usuário e Senha (Não Assistido)

• Nome de usuário - O nome de usuário de sua conta do Microsoft 365.
• Senha - A senha de sua conta do Microsoft 365.

Comum

• TempoLimiteEmMs - Especifica o tempo que se deve aguardar (em milissegundos) para que a autenticação interativa (caixa de diálogo de consentimento) seja concluída antes de gerar um erro. Esse campo é compatível apenas com números inteiros e variáveis Int32 . O valor padrão é 30000ms (30 segundos).

Runtime

• Ativos de conexão do runtime — Navegue para selecionar um ativo. Esse campo permite que você selecione um ativo diferente para o tempo de execução. Use o menu do botão Mais para selecionar Caminho relativo e insira o caminho completo do ativo do Orchestrator contendo detalhes da conexão.

Método de conexão do Painel de propriedades

Observação: ao selecionar este método, você configura os campos de autenticação no Painel Propriedades, assim como nas versões anteriores deste pacote.

• Conexões - Selecione uma conta da lista. Você pode adicionar, excluir e escolher quais conexões usar.
• Escopos de autenticação - Consulte a seção do assistente Usando os escopos de autenticação abaixo.

Usando o assistente de Escopos de autenticação

Observação: Este assistente substitui o parâmetro Serviços disponível nas versões anteriores deste pacote.

A atividade Scope incorpora um seletor de permissões universais, oferecendo uma imagem clara de todos os escopos de autenticação usados, dos quais as atividades precisam para funcionar corretamente.

Todas as atividades filho incluídas na atividade Microsoft 365 Application Scope são detectadas automaticamente como escopos exigidos.

Se nenhum escopo for selecionado manualmente no assistente de Escopos, a função Detecção automática é aplicada por padrão no runtime, e a necessidade de configurar o assistente é eliminada. Todos os escopos mínimos exigidos são selecionados no runtime.

Você também pode adicionar um escopo manualmente após adicionar uma atividade filha ao Escopo do aplicativo Microsoft 365.

Autenticação

Importante: a Microsoft desativou a autenticação básica para o Exchange online. Isso afeta algumas de nossas atividades, como o escopo do Microsoft Office365. Recomendamos usar o protocolo OAuth nas atividades que o suportam.

• Tipo de Autenticação - O tipo de autenticação necessária para o seu aplicativo registrado. Selecione uma das cinco opções: InteractiveToken, IntegratedWindowsAuthentication, UsernameAndPassword, ApplicationIdAndSecret ou ApplicationIdAndCertificate. O valor padrão é InteractiveToken. Para obter mais informações sobre essas opções e qual delas selecionar, consulte a seção Automação autônoma versus assistida abaixo.
• Ambiente - O ambiente, seja o Azure Global ou as nuvens nacionais que são ambientes exclusivos e separados do Azure Global. Selecione uma das cinco opções: Padrão, Global, China, Alemanha ou Governança dos EUA. O valor padrão é Global.
• ID do aplicativo - A ID do aplicativo (cliente) exclusiva atribuída pelo Azure Active Directory quando você registrou seu aplicativo durante a Configuração. A ID do aplicativo (cliente) representa uma instância de um aplicativo Microsoft 365. Uma única organização pode ter várias IDs de aplicativos (clientes) para sua conta do Microsoft 365. Cada ID de aplicativo (cliente) contém suas próprias permissões e requisitos de autenticação. Por exemplo, você e seu colega podem registrar um aplicativo Microsoft 365 no Azure Active Directory da sua empresa com diferentes permissões. Seu aplicativo pode ser configurado para autorizar permissões para interagir apenas com arquivos, enquanto o aplicativo de seu colega está configurado para autorizar permissões para interagir com arquivos, e-mail e calendário. Se você inserir a ID do seu aplicativo (cliente) nessa propriedade e executar a automação Attended, a caixa de diálogo de consentimento seria limitada às permissões de arquivos (e, posteriormente, apenas as atividades Files poderiam ser usadas).
• Tenant - A ID do diretório exclusivo (tenant) atribuída pelo Azure Active Directory quando você registrou seu aplicativo durante a Configuração. Necessário para aplicativos com vários tenants e a autenticação integrada do Windows. O ID do diretório (tenant) pode ser encontrado na página de visão geral de seu aplicativo registrado (sob o ID do aplicativo (cliente)).
• Endereço de email do usuário representado - O endereço de e-mail do usuário representado.

Comum

• TempoLimiteEmMs - Especifica o tempo que se deve aguardar (em milissegundos) para que a autenticação interativa (caixa de diálogo de consentimento) seja concluída antes de gerar um erro. Esse campo é compatível apenas com números inteiros e variáveis Int32 . O valor padrão é 30000ms (30 segundos) (não mostrado).
• ContinuarComErro — se definido, continua a execução das atividades restantes mesmo se a atividade atual falhar.

Token Interativo

Observação: esse é o mesmo método de autenticação suportado no Integration Service, seja por meio do aplicativo UiPath público ou de um aplicativo personalizado privado (método Traga seu próprio aplicativo).

• Aplicativo OAuth — indica o aplicativo (cliente) a ser usado. Se UiPath for selecionado, IdDoAplicativo e Tenant serão ignorados. Este campo é compatível apenas com variáveis OAuthApplication . Selecione uma das duas opções:
  • UiPath - Padrão. Quando você quiser usar o aplicativo criado pela UiPath. Nesse caso, os valores de parâmetro do ID do aplicativo e do locatário são ignorados.
  • Personalizado - Quando você deseja criar seu próprio aplicativo com as permissões corretas. Nesse caso, um valor deve ser definido para o parâmetro Application ID .

Application ID e Certificate (Unattended)

• Certificado como Base64 - A representação em Base64 do certificado. Obrigatório se o Tipo de Autenticação estiver definido como ID do Aplicativo e Certificado.

• Senha do certificado - Uma senha opcional que pode ser necessária para usar o certificado, como uma Secure String.

Application ID and Secret (Unattended)

• Segredo do aplicativo - A string de segredo que o aplicativo usa para fornecer sua identidade. Obrigatório se o Tipo de Autenticação estiver definido como ID do Aplicativo e Segredo.
• Segredo seguro do aplicativo - O segredo do aplicativo (cliente), como um SecureString.

Nome de usuário e Senha (Não Assistido)

Essas propriedades aplicam-se apenas quando você executa automação não assistida. Ao especificar valores para essas propriedades, certifique-se de que o Tipo de autenticação esteja definido como Nome de usuário e Senha. Para obter mais informações, consulte a seção Nome de usuário e senha abaixo.

• Senha - A senha de sua conta do Microsoft 365.
• Senha segura - A senha de sua conta do Microsoft 365, como um SecureString.
• Nome de usuário - O nome de usuário de sua conta do Microsoft 365.

Como funciona

As etapas a seguir e o diagrama de sequência de mensagens são um exemplo de como a atividade funciona desde o tempo de design (ou seja, as dependências da atividade e as propriedades de entrada/saída) até o tempo de execução.

1. Conclua as etapas de Configuração .
2. Adicione a atividade Microsoft Office 365 Scope ao seu projeto.

3. Insira valores para as propriedades Authentication, Inpute Unattended (se aplicável).

   
   

   

   
   

Automação Attended vs. Unattended

A atividade Microsoft 365 Scope tem quatro fluxos de autenticação diferentes (Tipos de Autenticação) que você pode escolher ao adicionar a atividade ao seu projeto. Sua seleção depende do tipo de modo de automação que você planeja executar (não assistido ou assistido) e dos requisitos de autenticação de seu aplicativo (consulte seu administrador se não tiver certeza de quais requisitos de autenticação se aplicam ao seu aplicativo).

TipoDeAutenticação	Assistido	Não Assistido	Tipo de permissão da API
Token Interativo	X		Permissões delegadas
Autenticação do Windows Integrada		X	Permissões delegadas
UsernameAndPassword		X	Permissões delegadas
ID do Aplicativo e Segredo		X	Permissões do aplicativo
IdDoAplicativo e Certificado		X	Permissões do aplicativo

Importante:

Os tipos de autenticação integrada do Windows ou de Nome de usuário e Senha não funcionam quando a Autenticação Multi-Factor (MFA) está habilitada. Se seu aplicativo exigir MFA, você pode executar a automação assistida usando o tipo de autenticação Token Interativo ou automação não assistida usando o ID do Aplicativo e Segredo e o ID do Aplicativo e Certificado. Os tipos de autenticação Application ID e Secret e Application ID e Certificate são apropriados para automação e trabalho não assistidos, independentemente de o MFA estar habilitado ou desabilitado.

Ao registrar seu aplicativo, você deve selecionar um tipo de aplicativo. Considere os seguintes requisitos:

• Para cenários Assistidos (tipo de autenticação do Token Interativo) e Não Assistidos com Autenticação Integrada do Windows, use um aplicativo móvel/desktop (que usa o fluxo de código de autorização do OAuth 2.0).

• Para cenários não assistidos (Nome de Usuário e Senha, ID do Aplicativo e Segredo, ID do Aplicativo e Certificado), use um aplicativo confidencial/Web (que usa fluxo de credenciais do cliente OAuth 2.0).

Token Interativo

O tipo de autenticação do Token Interativo pode ser usado para automação assistida e quando a autenticação multi-factor (MFA) for necessária. Essa é a opção padrão e o que usamos em nossos exemplos. Se você estiver interessado em experimentar o pacote de atividades, essa opção é fácil de configurar e funciona bem para contas pessoais (usando o URI de redirecionamento padrão observado na etapa 7 da seção Registre seu aplicativo do Guia de configuração ).

Quando a atividade Microsoft 365 for executada pela primeira vez usando esse tipo de autenticação, você será solicitado a autorizar o acesso aos recursos (você concedeu permissões ao registrar seu aplicativo) por meio de uma caixa de diálogo consentimento .

Se você selecionar essa opção, as propriedades Username, Passworde Tenant deverão ser deixadas vazias.

Autenticação do Windows Integrada

O tipo de autenticação Autenticação Integrada do Windows pode ser usado para automação não assistida. Essa opção pode ser aplicada a aplicativos hospedados no Windows em execução em computadores que ingressaram em um domínio do Windows ou Azure Active Directory.

Você só deve selecionar esta opção se seu aplicativo registrado estiver configurado para oferecer suporte à autenticação integrada do Windows (informações adicionais podem ser encontradas no GitHub).

Se você selecionar esta opção, as propriedades Username e Password devem ser deixadas vazias. A propriedade Tenant é opcional.

UsernameAndPassword

O tipo de autenticação Nome de Usuário e Senha pode ser usado para automação não assistida.

Embora não seja recomendado pela Microsoft, você pode usar esse tipo de autenticação em aplicativos clientes públicos. O uso desse tipo de autenticação impõe restrições ao seu aplicativo. Por exemplo, os aplicativos que usam esse fluxo não poderão fazer login de um usuário que precise realizar a autenticação multifator (acesso condicional). Isso também não permitirá que seu aplicativo se beneficie do logon único.

Se você selecionar essa opção, as propriedades Nome de usuário e Senha serão obrigatórias e a propriedade Locatário será opcional para aplicativos de locatário único (necessário para aplicativos de vários locatários).

Observação: a propriedade IdDoAplicativo é necessária ao selecionar o tipo de autenticação Nome de usuário e Senha. Você pode registrar seu aplicativo Microsoft 365 usando sua conta pessoal, profissional e/ou escolar.

ID do Aplicativo e Segredo

No que diz respeito à autenticação com Application (client) ID e Application (client) Secret, tenha em atenção o seguinte:

• As permissões de APIs apropriadas devem ser configuradas para o aplicativo Azure para que as atividades Microsoft 365 funcionem corretamente (por exemplo, as permissões de aplicativos Group.Create, Group.Read.All e Group.ReadWrite.All devem ser configuradas para o Microsoft Graph ao usar atividades Groups).
• Algumas atividades não podem ser usadas com esse tipo de autenticação porque a API do Microsoft Graph correspondente não oferece suporte a permissões de aplicativo. Consulte a documentação oficial da Microsoft.
• Para atividades de email - Get Mail, Forward Mail, Send Maile Move Email - é obrigatório especificar um valor para o parâmetro Account .

IdDoAplicativo e Certificado

Para autenticar usando um certificado como segredo, siga estas etapas:

1. No portal do Azure:

   • Localize seu aplicativo Microsoft 365 registrado.
   • Selecione Certificados e segredos e carregue seu arquivo de certificado (chave pública). Ele pode ter um dos seguintes tipos de arquivo: .cer, .pem, .crt.
     
     

     

     
     
2. Converta o conteúdo bruto de seu arquivo .pfx que representa o certificado em um base64 string. Para fazer isso, use uma ferramenta baseada na web como Base64.Guru ou atribua Convert.ToBase64String(System.IO.File.ReadAllBytes(pfxFilePath)) a uma variável String .
3. Na atividade Microsoft 365 Scope:

• Defina o Tipo de autenticação como o ID do aplicativo e Certificado.
• Defina CertificarComoBase64 como a representação base64 do certificado.

• Se for necessária uma senha para usar o certificado, defina também o valor para a propriedade Senha do Certificado .

  Observação: a mesma descrição da seção ID do aplicativo e segredo também se aplica à ID do aplicativo e Certificado.

Solução de problemas

Se você tiver algum problema com a autenticação, consulte Solução de problemas - Autenticação.