Autenticação com um aplicativo externo

Os aplicativos externos são configurados em Admin > Apps externos no UiPath Cloud e usam o OAuth 2.0 para autenticação. Eles são compatíveis com vários cenários de autenticação:

• Acesso não assistido ou automatizado sem um login de usuário (concessão de credenciais do cliente)
• Integrações de terceiros que executam seu próprio fluxo do OAuth, como Copilot Studio ou ChatGPT (concessão de código de autorização)
• Aplicativos de área de trabalho ou dispositivos móveis em que nenhum segredo do cliente pode ser armazenado com segurança (concessão de código de autorização com PKCE)

Compreensão dos tipos de aplicativos externos

Ao criar um aplicativo externo, você faz duas escolhas que determinam como a autenticação funciona:

• Se o aplicativo é confidencial ou não confidencial.
• Se ele usa escopos de aplicativo ou escopos de usuário.

Apps confidenciais versus não confidenciais

	Confidencial	não confidencial
Segredo do cliente	Gerado na criação. Deve ser armazenado com segurança.	Não gerado
Quem autentica	O próprio aplicativo (não é necessário um usuário) ou um usuário por meio do aplicativo	Apenas um usuário por meio do aplicativo
Guias de escopo na interface gráfica	Escopo(s) do Aplicativo e Escopo(s) do Usuário	Somente escopo(s) do usuário

Use um aplicativo confidencial quando o segredo puder ser armazenado com segurança, para back-ends, servidores e pipelines de CI/CD.

Use um aplicativo não confidencial para aplicativos de desktop, aplicativos móveis ou aplicativos de página única baseados em navegador onde um segredo não pode ser mantido em segurança. Os aplicativos não confidenciais exigem PKCE.

Escopos de aplicativos versus escopos de usuários

As duas guias no mapa de interface gráfica de Apps externos para fluxos do OAuth fundamentalmente diferentes:

	Escopos do aplicativo	Escopos de usuários
OAuth grant type	Credenciais do cliente (client_credentials)	Código de autorização (authorization_code)
Identidade	O próprio aplicativo	Um usuário humano que faz login por meio do aplicativo
Declaração sub do token	do aplicativo client_id	O ID do usuário
Declaração sub_type do token	service.external	user
Como os servidores MCP veem isso	UserType.ExternalApp	UserType.User
Exige login do usuário	Não	Sim, o navegador redireciona para o login do UiPath
Atividades do Integration Service	Não compatível (sem contexto do usuário)	Compatível (contexto do usuário presente)
Acesso às pastas	O aplicativo deve ser atribuído explicitamente à pasta	O usuário deve ter a função apropriada na pasta. O aplicativo pode ser atribuído à pasta somente se também tiver escopos de aplicativo; um aplicativo com apenas escopos de Usuário não pode ser atribuído a uma pasta
Disponível em	Apenas aplicativos confidenciais	Tanto confidenciais quanto não confidenciais

Quando você salva o aplicativo externo, o Identity Server define quais tipos de concessão o cliente pode usar, com base nos tipos de escopo que você configurou:

• Apenas escopos de aplicativos → client_credentials é permitido
• Apenas escopos de usuário → authorization_code é permitido
• Ambos → ambos são permitidos

Se você solicitar manualmente um token de https://cloud.uipath.com/identity_/connect/token, você deve especificar explicitamente grant_type em cada solicitação de token. Omitir isso retorna um erro. O envio de um tipo de concessão que não era permitido para o cliente também falha.

Configuração da autenticação do escopo do aplicativo

Os escopos do aplicativo usam a concessão de credenciais do cliente. Esse é o único método de autenticação que funciona sem a interação do usuário.

Importante:

Os servidores UiPath MCP que expõem conectores do Integration Service falham quando acessados com credenciais do cliente. Para ferramentas suportadas pelo Integration Service, use a autenticação de escopo de usuário .

Pré-requisitos

• Você pode acessar Admin > Apps externos no UiPath.
• Você pode gerenciar o acesso a pastas no Orchestrator.

Crie o aplicativo externo

1. Acesse UiPath, selecione Admin e, em seguida, Apps externos.

2. Selecione Adicionar aplicativo.

3. Insira um nome e mantenha o tipo de aplicativo Confidencial .

4. Selecione a aba Escopo(s) do aplicativo .

   Importante:

   Adicione escopos na guia Escopo(s) do aplicativo , não na guia Escopo(s) do usuário .

5. Adicione os seguintes escopos:

   • OR.Execution: necessário para listar ferramentas. Os servidores MCP chamam a API ListReleases do Orchestrator para buscar metadados do processo ao lidar com tools/list, e esse ponto de extremidade é autorizado com OR.Execution.
   • OR.Jobs: necessário para executar ferramentas. Todos os tipos de servidor MCP que executam processos como ferramentas (UiPath, Codificado e Comando) chamam a API StartJobs do Orchestrator, que é autorizada com OR.Jobs.

6. Selecione Adicionar e, em seguida, copie o ID do Cliente e Segredo do cliente.

Atribuir o aplicativo externo à pasta

1. No Orchestrator, navegue até Tenant > Gerenciar acesso ou nas configurações de acesso da pasta específica.

2. Adicione o aplicativo externo com a função Automation User .

   Essa função inclui a permissão MCPServers.View necessária para acessar servidores MCP.

Autenticar usando o aplicativo externo

Escolha uma das seguintes opções com base em como você deseja que o Orchestrator resolva as permissões.

Opção A: apenas OR.Default (recomendada para simplicidade)

O token não traz escopos explícitos no nível de API. O Orchestrator resolve permissões por meio das funções atribuídas ao aplicativo externo em cada pasta. As chamadas de API entre pastas funcionam sem um cabeçalho de chave de pasta. Essa opção requer que o aplicativo externo tenha a função Automation User na pasta de destino.

uipath auth --client-id "<your-client-id>" \
  --client-secret "<your-client-secret>" \
  --base-url "https://cloud.uipath.com/{org}/{tenant}" \
  --scope "OR.Default"

Opção B: escopos explícitos

O token carrega declarações explícitas de escopo OR.Execution e OR.Jobs . O Orchestrator valida esses escopos diretamente em cada chamada de API. Essa opção requer o cabeçalho X-UIPATH-FolderKey , mas os Servidores MCP lidam com isso automaticamente.

uipath auth --client-id "<your-client-id>" \
  --client-secret "<your-client-secret>" \
  --base-url "https://cloud.uipath.com/{org}/{tenant}" \
  --scope "OR.Default OR.Execution OR.Jobs"

Resultado

A CLI obtém um token de acesso que você pode usar no cabeçalho Authorization para solicitações do Servidor MCP.

Compreensão das combinações de escopo

OR.Default é um escopo que você configura na interface gráfica dos Apps Externos. É um escopo especial que você inclui no parâmetro --scope ao solicitar um token. Os escopos solicitados determinam como o Orchestrator resolve permissões e como os servidores MCP roteia chamadas de API.

O fluxo MCP envolve duas chamadas de API do Orchestrator que exigem diferentes escopos:

• tools/list: os servidores MCP chamam odata/Releases/ListReleases para buscar metadados do processo. O controlador de Versões requer OR.Execution.
• tools/call: os servidores MCP chamam odata/Jobs/StartJobs para executar um processo. O controlador de trabalhos requer OR.Jobs.

A tabela a seguir resume como diferentes combinações de escopo se comportam:

Escopos na solicitação de token	Resolução de permissão do Orchestrator	X-UIPATH-FolderKey Cabeçalho	Comportamento dos servidores MCP
OR.Default Apenas	Atribuições de função no nível da pasta (por exemplo, Automation User na pasta de destino)	Não é necessário	Chamada de API única entre pastas
Apenas escopos específicos (por exemplo, OR.Execution OR.Jobs)	Declarações de escopo explícitas no token	Obrigatório em todas as chamadas de API	Chamadas de API por pasta (agrupadas por pasta)
OR.Default mais escopos específicos	Declarações de escopo explícitas (escopos específicos têm precedência)	Obrigatório em todas as chamadas de API	Chamadas de API por pasta (agrupadas por pasta)

Notas de comportamento:

• Solicitar apenas OR.Default é a configuração mais simples. O Orchestrator verifica as funções que o aplicativo externo recebeu em cada pasta. A função Automation User abrange o acesso a Versões e Trabalhos.
• A adição de escopos específicos, como OR.Execution ou OR.Jobs (com ou sem OR.Default), altera a forma como a resolução da pasta funciona. O Orchestrator verifica as declarações de escopo e as permissões de função da pasta, e o acesso é concedido se qualquer uma das verificações for aprovada. Isso requer o cabeçalho X-UIPATH-FolderKey em cada chamada de API. Os servidores MCP lidam com isso automaticamente detectando os escopos do token e fazendo chamadas por pasta quando necessário.
• OR.Default, os escopos OR.* específicos ignoram a resolução de funções no nível da pasta e concedem acesso em todas as pastas dentro do tenant. O cabeçalho X-UIPATH-FolderKey ainda é necessário para o roteamento de API.

Limitação conhecida: GetFoldersForCurrentUser

Ao executar servidores MCP localmente com credenciais do cliente (uipath run), o SDK Python chama orchestrator_/api/FoldersNavigation/GetFoldersForCurrentUser para resolver o caminho da pasta para uma chave da pasta. Esta API não é compatível com a autenticação de credenciais do cliente. Ela requer um token de usuário interativo.

Para contornar isso, defina a variável de ambiente UIPATH_FOLDER_KEY diretamente. Quando essa variável é definida, o SDK ignora totalmente a chamada GetFoldersForCurrentUser :

export UIPATH_FOLDER_KEY="<folder-guid>"
uipath run mcp-server

Você pode encontrar a pasta GUID na API do Orchestrator ou na URL da pasta.

Erro comum: credenciais da máquina versus app externo

O uso de credenciais de máquina (de Orchestrator > Máquinas) em vez de credenciais de aplicativos externos retorna invalid_scope . As credenciais da máquina são para autenticação de robôs, não para acesso à API.

Se você vir:

{"error":"invalid_scope","error_description":"..."}

Verifique se você está usando credenciais de Admin > Apps externos, não de Orchestrator > Máquinas.

Como configurar a autenticação de escopo de usuário

Os escopos do usuário usam a concessão do código de autorização. Um usuário deve fazer logon por meio do aplicativo externo, e o token carrega a identidade do usuário em vez da do aplicativo.

Use a autenticação de escopo de usuário nas seguintes situações:

• O servidor MCP expõe ferramentas apoiados por atividades do Integration Service (conectores).
• Você está se integrando a um cliente de terceiros que executa seu próprio fluxo do OAuth (Copilot Studio, ChatGPT).
• Você precisa de identidade por usuário, controle de acesso com base em quem fez login, não qual aplicativo está chamando.

Pré-requisitos

• Você pode acessar Admin > Apps externos no UiPath.
• Você pode gerenciar o acesso a pastas no Orchestrator.
• Você conhece o URL de redirecionamento do seu aplicativo cliente.

Crie o aplicativo externo

1. Acesse UiPath, selecione Admin e, em seguida, Apps externos.

2. Selecione Adicionar aplicativo.

3. Insira um nome e mantenha o tipo de aplicativo Confidencial .

4. Selecione a aba Escopo(s) de usuário .

   Importante:

   Adicione escopos na guia Escopo(s) do usuário , não na guia Escopo(s) do Aplicativo .

5. Adicione os seguintes escopos:

   • OR.Execution: necessário para listar ferramentas.
   • OR.Jobs: necessário para executar ferramentas (servidores codificados ou de comando).

6. Adicione um URL de redirecionamento. Este é o endereço para o qual o navegador do usuário é enviado após o login. Use o URL de retorno de chamada fornecido pelo seu aplicativo cliente.

   Para o Copilot Studio, use um URL fictício inicialmente e atualize-o após a conexão ser criada.

7. Selecione Adicionar e, em seguida, copie o ID do Cliente e Segredo do cliente.

Configurar o acesso à pasta

Como o aplicativo externo criado acima tem apenas escopos de Usuário, ele não pode ser atribuído a uma pasta em Gerenciar acesso. O acesso à pasta é concedido por meio da função do usuário; o token herda as permissões do usuário, não as do aplicativo.

1. No Orchestrator, navegue até Tenant > Gerenciar acesso ou nas configurações de acesso da pasta específica.

2. Atribua o usuário que fará login com a função Automation User, Automation Developer ou Folder Administrator .

   Essa função determina o que o usuário pode fazer na pasta e deve incluir a permissão MCPServers.View necessária para acessar os servidores MCP.

Se o aplicativo externo também tiver escopos de aplicativo definidos, você também pode atribuir o próprio aplicativo à pasta com a função Automation User . Isso é necessário apenas para fluxos de credenciais do cliente que não envolvem o logon de usuário.

Execute o fluxo de código de autorização

O aplicativo cliente inicia o fluxo.

1. Redirecione o usuário para o endpoint de autorização:

   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
   

2. O usuário faz login por meio do navegador e é redirecionado de volta para o URL de retorno de chamada com code parâmetro.

3. Troca o código de autorização por um token do seu aplicativo do lado do servidor:

   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &client_secret=<your-client-secret>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
   

Resultado

O ponto de extremidade do token retorna um token de acesso que você pode usar no cabeçalho Authorization para solicitações do Servidor MCP.

Variante: aplicativo não confidencial com PKCE

O mesmo fluxo funciona com um aplicativo externo não confidencial. As diferenças estão resumidas abaixo:

	Confidencial	não confidencial
Segredo do cliente	Incluído na troca de token	Não usado (não existe nenhum segredo)
PKCE	Opcional	Obrigatório
Atribuição de pasta	O app pode ser atribuído à pasta somente se também tiver escopos de aplicativo definidos. Com apenas escopos de usuário, o aplicativo não aparece em Gerenciar acesso , e apenas as funções de pasta do usuário são aplicadas	O aplicativo não pode ter escopos de aplicativo e nunca aparece em Gerenciar acesso; somente as funções da pasta do usuário se aplicam
Criar na IU	Selecionar confidencial	Selecionar Não confidencial

Para usar essa variante:

1. Ao criar o aplicativo externo, selecione Não confidencial em vez de Confidencial. Apenas a guia Escopo(s) do usuário está disponível. Adicione OR.Execution, adicione OR.Jobs para servidores codificados ou de comando e adicione o URL de redirecionamento.

2. Atribua apenas o usuário (não o aplicativo) à pasta com a função apropriada.

3. Use o seguinte fluxo de autorização baseado em PKCE:

   # 1. Generate PKCE code verifier and challenge
   code_verifier = <random 64-byte base64url string>
   code_challenge = BASE64URL(SHA256(code_verifier))
   
   # 2. Redirect user to authorize (with PKCE challenge)
   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
     &code_challenge=<code_challenge>
     &code_challenge_method=S256
   
   # 3. Exchange the code for a token (no client_secret; include code_verifier)
   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
     &code_verifier=<code_verifier>
   

O token resultante é idêntico ao token confidencial dos escopos do usuário: sub é o GUID do usuário, sub_type é user e o público é UiPath.Orchestrator. Os servidores MCP tratam-na da mesma forma que a variante confidencial.

Funcionalidades do token (escopos de usuários)

Essas características se aplicam tanto a aplicativos confidenciais e não confidenciais usando o fluxo de código de autorização:

• JWT com sub definido como o GUID do usuário e sub_type definido como user.
• Público: UiPath.Orchestrator.
• Os servidores MCP resolvem o token como identidade do usuário — na camada de Servidores MCP, o token segue o mesmo caminho de código que o login interativo.
• O roteamento de chave de pasta não se aplica (chamada do Orchestrator entre pastas únicas).
• As atividades do Integration Service funcionam (o contexto do usuário está presente).
• Token de atualização: retornado quando offline_access é incluído no parâmetro scope ; não é retornado sem ele. A vida útil do token de atualização é de 60 dias.

Conexão do Copilot Studio a um servidor UiPath MCP

Use este procedimento para conectar um agente do Microsoft Copilot Studio a um Servidor UiPath MCP usando a autenticação manual do OAuth 2.0.

Pré-requisitos

• Você pode gerenciar aplicativos externos.
• Você pode gerenciar o acesso a pastas no Orchestrator.
• Você pode configurar conexões no Copilot Studio.

Etapas

1. Na UiPath, acesse Admin > Apps externos e selecione Adicionar aplicativo.

2. Defina o tipo de aplicativo como Confidencial.

3. Em Recursos, adicione o Acesso à API do Orchestrator com o escopo OR.Execution e adicione-o como um escopo Aplicativo e um escopo Usuário.

   Se o Servidor MCP for do tipo Codificado ou de Comando, adicione também OR.Jobs em ambos os escopos.

   Adicionar o escopo na aba Escopo(s) do aplicativo é o que faz a etapa 6 funcionar; um aplicativo com apenas escopos de Usuário não pode ser atribuído a uma pasta em Gerenciar acesso.

4. Insira uma URL de redirecionamento fictícia para agora (por exemplo, https://cloud.uipath.com).

5. Salve o aplicativo e, em seguida, copie o ID do cliente e o Segredo do cliente.

6. No Orchestrator, atribua o aplicativo externo à pasta que contém o Servidor MCP com a função Automation User . Isso funciona porque o aplicativo recebeu escopos de aplicativo na etapa 3; um aplicativo com apenas escopos de usuário não pode ser atribuído a uma pasta. Atribua também a função de tenant Allow to be Automation User.

7. No Copilot Studio, adicione a URL do servidor MCP com autenticação manual OAuth 2.0 , usando os seguintes valores:

   • ID do Cliente: o valor copiado na etapa 5.
   • Segredo do cliente: o valor copiado na etapa 5.
   • URL de autorização: https://cloud.uipath.com/identity_/connect/authorize
   • URL do token: https://cloud.uipath.com/identity_/connect/token
   • URL de atualização: https://cloud.uipath.com/identity_/connect/token
   • Escopo: OR.Default

8. Selecione Criar no Copilot Studio. O Copilot Studio gera um URL de redirecionamento, o campo fica acinzentado antes da criação.

9. Copie o URL de redirecionamento gerado e adicione-o aos URLs de redirecionamento do aplicativo externo em UiPath Admin > Apps externos.

10. Retorne ao Copilot Studio e selecione Conectar.

Resultado

O Copilot Studio está conectado ao Servidor MCP da UiPath. O usuário faz login por meio do fluxo do OAuth quando o agente acessa as ferramentas do MCP.

Conectar o ChatGPT a um servidor UiPath MCP

Use este procedimento para aplicativos ChatGPT novos ou não publicados onde o Registro Dinâmico de Cliente (DCR) não funciona.

O ChatGPT alterou seus URIs de redirecionamento de /connector_platform_oauth_redirect para /connector/oauth/{callback_id}. Os aplicativos já publicados ainda funcionam com o DCR. Apps novos ou não publicados exigem a configuração manual do OAuth.

Pré-requisitos

• Você pode gerenciar aplicativos externos.
• Você pode criar aplicativos no ChatGPT.

Obter o URL de retorno de chamada do ChatGPT

1. Acesse ChatGPT, selecione seu perfil, selecione Apps e depois Criar aplicativo.
2. Digite o nome do aplicativo, a descrição e a URL do Servidor MCP do UiPath.
3. Selecione Configurações avançadas.
4. Em Método de registro, altere de DCR para Cliente OAuth Definido pelo Usuário.
5. Copie o URL de retorno de chamada (https://chatgpt.com/connector/oauth/{callback_id}).
6. Mantenha esta guia do navegador aberta.

Crie o aplicativo externo no UiPath

1. Acesse Admin > Apps externos e selecione Adicionar aplicativo.

2. Selecione Confidencial como o tipo de aplicativo.

3. Adicione OR.Execution, OR.Jobs e OR.Folders nas guias Escopo(s) do Aplicativo e Escopo(s) do Usuário .

   Adicionar os escopos na aba Escopo(s) do aplicativo é o que permite que a próxima etapa (atribuição de pastas) funcione; um aplicativo com apenas escopos de Usuário não pode ser atribuído a uma pasta em Gerenciar acesso.

4. No campo Redirecionar URL , cole o URL de retorno de chamada copiado do ChatGPT.

5. Salve o aplicativo e, em seguida, copie o ID do cliente e o Segredo do cliente.

Atribuir o aplicativo externo à pasta

1. No Orchestrator, abra a pasta que contém o Servidor MCP.
2. Navegue até Gerenciar acesso > Atribuir.
3. Adicione o aplicativo externo com a função Automation User .

Configurar o ChatGPT

1. Retorne à guia do navegador ChatGPT.
2. Insira o ID do cliente OAuth e o Segredo do cliente copiados do aplicativo externo.
3. Em Registro do cliente > Método de autenticação do ponto de extremidade do token, client_secret_basic.
4. Em Escopos > Escopos padrão, desative quaisquer escopos padrão existentes.
5. Em Escopos > Escopos de base, adicione OR.Default.
6. Selecione Criar.

Resultado

O ChatGPT está conectado ao servidor MCP da UiPath. Os usuários autenticam-se por meio do fluxo manual do OAuth quando o aplicativo acessa as ferramentas MCP.

Comportamento de OR.Default

OR.Default referenciado em fluxos de escopo do aplicativo e escopo do usuário, mas comporta-se de forma diferente em cada contexto:

Context	Comportamento
Escopos do aplicativo, no parâmetro --scope na solicitação do token	Controla como o Orchestrator resolve permissões. Quando OR.Default é o único escopo, o Orchestrator usa atribuições de função de pasta em vez de declarações de escopo explícitas. Consulte Entendendo combinações de escopo.
Escopos do usuário, no parâmetro scope da solicitação de autorização	Usado como o parâmetro de escopo na solicitação de autorização. No nível do Orchestrator, ele habilita um modo de autorização permissivo onde o acesso é concedido se a verificação de escopo ou as permissões de função da pasta do usuário forem aprovadas. Os servidores MCP não usam OR.Default para tokens com escopo de usuário, ele sempre faz chamadas únicas de pasta cruzada, independentemente de quais escopos o token carrega.

Em nenhum dos casos, OR.Default é um escopo configurado na IU de Apps Externos. Aparece apenas no parâmetro de escopo no momento da solicitação de token ou autorização.