Autenticarse con una aplicación externa

Las aplicaciones externas se configuran en Admin > External Apps en UiPath Cloud y utilizan OAuth 2.0 para la autenticación. Admiten varios escenarios de autenticación:

• Acceso desatendido o automatizado sin inicio de sesión de usuario (concesión de credenciales de cliente)
• Integraciones de terceros que realizan su propio flujo OAuth, como Copilot Studio o ChatGPT (concesión de código de autorización)
• Aplicaciones de escritorio o móviles en las que no se puede almacenar ningún secreto de cliente de forma segura (concesión de código de autorización con PKCE)

Comprender los tipos de aplicaciones externas

Al crear una aplicación externa, tomas dos decisiones que determinan cómo funciona la autenticación:

• Si la aplicación es confidencial o no confidencial.
• Si utiliza ámbitos de aplicación o ámbitos de usuario.

Aplicaciones confidenciales frente a no confidenciales

	Confidencial	no confidenciales
Secreto de cliente	Generado en la creación. Debe almacenarse de forma segura.	No generado
Quién se autentica	La propia aplicación (no se necesita usuario) o un usuario a través de la aplicación	Solo un usuario a través de la aplicación
Pestañas de ámbito en la IU	Ámbito(s) de aplicación y ámbito(s) de usuario	Solo ámbitos de usuario

Usa una aplicación confidencial cuando el secreto se pueda almacenar de forma segura, para backends, servidores y procesos de CI/CD.

Utiliza una aplicación no confidencial para aplicaciones de escritorio, aplicaciones móviles o aplicaciones de una sola página basadas en navegador en las que no se puede mantener un secreto a salvo. Las aplicaciones no confidenciales requieren PKCE.

Ámbitos de aplicación frente a ámbitos de usuario

Las dos pestañas en la IU de External Apps se asignan a flujos OAuth fundamentalmente diferentes:

	Ámbitos de aplicación	Ámbitos de usuario
OAuth grant type	Credenciales de cliente (client_credentials)	Código de autorización (authorization_code)
Identidad	La propia aplicación	Un usuario humano que inicia sesión a través de la aplicación
Reclamación de token sub	La aplicación client_id	El ID del usuario
Reclamación de token sub_type	service.external	user
Cómo lo ven los servidores MCP	UserType.ExternalApp	UserType.User
Requiere inicio de sesión de usuario	No	Sí, el navegador redirecciona al inicio de sesión de UiPath
Actividades de Integration Service	No compatible (sin contexto de usuario)	Compatible (contexto de usuario presente)
Acceso de la carpeta	La aplicación debe asignarse explícitamente a la carpeta	El usuario debe tener el rol adecuado en la carpeta. La aplicación puede asignarse a la carpeta solo si también tiene ámbitos de aplicación; una aplicación con solo ámbitos de usuario no se puede asignar a carpeta
Disponible el	Solo aplicaciones confidenciales	Tanto confidencial como no confidencial

Al guardar la aplicación externa, Identity Server establece qué tipos de concesión puede utilizar el cliente, en función de los tipos de ámbito que hayas configurado:

• Solo ámbitos de aplicación → client_credentials está permitido
• Solo ámbitos de usuario → authorization_code está permitido
• Ambos → ambos están permitidos

Si solicitas manualmente un token de https://cloud.uipath.com/identity_/connect/token, debes especificar explícitamente grant_type en cada solicitud de token. Omitirlo devuelve un error. El envío de un tipo de concesión que no estaba permitido para el cliente también falla.

Configurar la autenticación del ámbito de la aplicación

Los ámbitos de aplicación utilizan la concesión de credenciales de cliente. Este es el único método de autenticación que funciona sin interacción del usuario.

Importante:

Los servidores MCP de UiPath que exponen conectores de Integration Service fallan cuando se accede a ellos con credenciales de cliente. Para las herramientas respaldadas por Integration Service, utiliza la autenticación de ámbito de usuario en su lugar.

Requisitos previos

• Puedes acceder a Admin > Apps externas en UiPath.
• Puedes gestionar el acceso a las carpetas en Orchestrator.

Crear la aplicación externa

1. Ve a UiPath, selecciona Admin y luego Apps externas.

2. Selecciona Añadir aplicación.

3. Introduce un nombre y mantén el tipo de aplicación Confidencial .

4. Selecciona la pestaña Ámbitos de aplicación .

   Importante:

   Añade ámbitos en la pestaña Ámbitos de aplicación , no en la pestaña Ámbitos de usuario .

5. Añade los siguientes ámbitos:

   • OR.Execution: necesario para las herramientas de listado. Los servidores MCP llaman a la API ListReleases de Orchestrator para obtener los metadatos del proceso al gestionar tools/list, y ese punto final está autorizado con OR.Execution.
   • OR.Jobs: necesario para ejecutar herramientas. Todos los tipos de servidor MCP que ejecutan procesos como herramientas (UiPath, Coded y Command) llaman a la API StartJobs de Orchestrator, que está autorizada con OR.Jobs.

6. Selecciona Añadir y, a continuación, copia el ID de cliente y el Secreto de cliente.

Asignar la aplicación externa a la carpeta

1. En Orchestrator, ve a Tenant > Gestionar acceso o a la configuración de acceso de la carpeta específica.

2. Añade la aplicación externa con el rol de Automation User .

   Este rol incluye el permiso MCPServers.View necesario para acceder a los servidores MCP.

Autenticarse utilizando la aplicación externa

Elige una de las siguientes opciones en función de cómo quieres que Orchestrator resuelva los permisos.

Opción A: solo OR.Default (recomendada por simplicidad)

El token no lleva ámbitos explícitos en el nivel de API. Orchestrator resuelve los permisos a través de los roles asignados a la aplicación externa en cada carpeta. Las llamadas a la API entre carpetas funcionan sin un encabezado de clave de carpeta. Esta opción requiere que la aplicación externa tenga el rol de Automation User en la carpeta 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"

Opción B: ámbitos explícitos

El token lleva reclamaciones de ámbito OR.Execution y OR.Jobs explícitas. Orchestrator valida estos ámbitos directamente en cada llamada a la API. Esta opción requiere el encabezado X-UIPATH-FolderKey , pero los servidores MCP lo gestionan automáticamente.

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

La CLI obtiene un token de acceso que puedes utilizar en el encabezado Authorization para las solicitudes del servidor MCP.

Comprender las combinaciones de ámbitos

OR.Default no es un ámbito que se configura en la IU de Apps externas. Es un ámbito especial que incluyes en el parámetro --scope al solicitar un token. Los ámbitos que solicitas determinan cómo Orchestrator resuelve los permisos y cómo los servidores MCP enrutan las llamadas a la API.

El flujo de MCP implica dos llamadas a la API de Orchestrator que requieren diferentes ámbitos:

• tools/list: llamadas de servidores MCP odata/Releases/ListReleases para obtener metadatos del proceso. El controlador de versiones requiere OR.Execution.
• tools/call: los servidores MCP llaman a odata/Jobs/StartJobs para ejecutar un proceso. El controlador de trabajos requiere OR.Jobs.

La siguiente tabla resume cómo se comportan las diferentes combinaciones de ámbitos:

Ámbitos a solicitud de token	Resolución de permisos de Orchestrator	X-UIPATH-FolderKey Encabezado	Comportamiento de los servidores MCP
OR.Default Solo	Asignaciones de roles a nivel de carpeta (por ejemplo, Automation User en la carpeta de destino)	No es necesario	Llamada única a la API entre carpetas
Solo ámbitos específicos (por ejemplo, OR.Execution OR.Jobs)	Reclamaciones de ámbito explícitas en el token	Obligatorio en cada llamada a la API	Llamadas a la API por carpeta (agrupadas por carpeta)
OR.Default más ámbitos específicos	Reclamaciones de ámbito explícitas (los ámbitos específicos tienen prioridad)	Obligatorio en cada llamada a la API	Llamadas a la API por carpeta (agrupadas por carpeta)

Notas de comportamiento:

• Solicitar solo OR.Default es la configuración más sencilla. Orchestrator comprueba los roles que se han asignado a la aplicación externa en cada carpeta. El rol de Automation User cubre tanto el acceso a Versiones como a Trabajos.
• Añadir ámbitos específicos como OR.Execution o OR.Jobs (con o sin OR.Default) cambia la forma en que funciona la resolución de carpetas. Orchestrator comprueba tanto las reclamaciones de ámbito como los permisos de rol de carpeta, y se concede acceso si se aprueba cualquiera de las comprobaciones. Esto requiere el encabezado X-UIPATH-FolderKey en cada llamada a la API. Los servidores MCP gestionan esto automáticamente detectando los ámbitos del token y realizando llamadas por carpeta cuando es necesario.
• Sin OR.Default, los ámbitos específicos de OR.* omiten la resolución de roles a nivel de carpeta y conceden acceso a todas las carpetas dentro del tenant. El encabezado X-UIPATH-FolderKey sigue siendo necesario para el enrutamiento de la API.

Limitación conocida: GetFoldersForCurrentUser

Al ejecutar servidores MCP localmente con credenciales de cliente (uipath run), el SDK de Python llama a orchestrator_/api/FoldersNavigation/GetFoldersForCurrentUser para resolver la ruta de la carpeta en una clave de carpeta. Esta API no admite la autenticación de credenciales de cliente, requiere un token de usuario interactivo.

Para evitarlo, establece la variable de entorno UIPATH_FOLDER_KEY directamente. Cuando se establece esta variable, el SDK omite la llamada GetFoldersForCurrentUser por completo:

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

Puedes encontrar el GUID de la carpeta en la API de Orchestrator o en la URL de la carpeta.

Error común: credenciales de máquina frente a aplicación externa

El uso de credenciales de máquina (desde Orchestrator > Máquinas) en lugar de credenciales de aplicaciones externas devuelve errores invalid_scope . Las credenciales de la máquina son para la autenticación del robot, no para el acceso a la API.

Si ves:

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

Comprueba que estás utilizando credenciales desde Admin > Apps externas, no desde Orchestrator > Máquinas.

Configurar la autenticación del ámbito de usuario

Los ámbitos de usuario utilizan la concesión de código de autorización. Un usuario debe iniciar sesión a través de la aplicación externa, y el token lleva la identidad del usuario en lugar de la de la aplicación.

Utiliza la autenticación de ámbito de usuario en las siguientes situaciones:

• El servidor MCP expone herramientas respaldadas por actividades de Integration Service (conectores).
• Estás integrando con un cliente de terceros que realiza su propio flujo OAuth (Copilot Studio, ChatGPT).
• Necesitas identidad por usuario, control de acceso basado en quién inició sesión, no en qué aplicación está llamando.

Requisitos previos

• Puedes acceder a Admin > Apps externas en UiPath.
• Puedes gestionar el acceso a las carpetas en Orchestrator.
• Conoces la URL de redirección de tu aplicación cliente.

Crear la aplicación externa

1. Ve a UiPath, selecciona Admin y luego Apps externas.

2. Selecciona Añadir aplicación.

3. Introduce un nombre y mantén el tipo de aplicación Confidencial .

4. Selecciona la pestaña Ámbitos de usuario .

   Importante:

   Añade ámbitos en la pestaña Ámbitos de usuario , no en la pestaña Ámbitos de aplicación .

5. Añade los siguientes ámbitos:

   • OR.Execution: necesario para las herramientas de listado.
   • OR.Jobs: necesario para ejecutar herramientas (servidores codificados o de comando).

6. Añade una URL de redirección. Esta es la dirección a la que se envía el navegador del usuario después de iniciar sesión. Utiliza la URL de devolución de llamada proporcionada por tu aplicación cliente.

   Para Copilot Studio, utiliza inicialmente una URL ficticia y actualízala después de crear la conexión.

7. Selecciona Añadir y, a continuación, copia el ID de cliente y el Secreto de cliente.

Configurar el acceso a la carpeta

Debido a que la aplicación externa creada anteriormente solo tiene ámbitos de usuario, no se puede asignar a una carpeta en Administrar acceso. El acceso a la carpeta se concede a través del rol del usuario; el token hereda los permisos del usuario, no los de la aplicación.

1. En Orchestrator, ve a Tenant > Gestionar acceso o a la configuración de acceso de la carpeta específica.

2. Asigna el usuario que iniciará sesión con el rol Automation User, Automation Developer o Folder Administrator .

   Este rol determina lo que el usuario puede hacer en la carpeta y debe incluir el permiso MCPServers.View necesario para acceder a los servidores MCP.

Si la aplicación externa también tiene ámbitos de aplicación definidos, también puedes asignar la propia aplicación a la carpeta con el rol de Automation User . Esto es necesario solo para los flujos de credenciales de cliente que no implican el inicio de sesión del usuario.

Ejecutar el flujo de código de autorización

La aplicación cliente inicia el flujo.

1. Redirigir al usuario al punto final de autorización:

   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. El usuario inicia sesión a través del navegador y es redirigido a la URL de devolución de llamada con un parámetro code .

3. Intercambia el código de autorización por un token de tu aplicación del lado del 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

El punto final del token devuelve un token de acceso que puedes utilizar en el encabezado Authorization para las solicitudes del servidor MCP.

Variante: aplicación no confidencial con PKCE

El mismo flujo funciona con una aplicación externa no confidencial. Las diferencias se resumen a continuación:

	Confidencial	no confidenciales
Secreto de cliente	Incluido en el intercambio de tokens	No se utiliza (no existe ningún secreto)
PKCE	Opcional	Obligatorio
Asignación de carpetas	La aplicación solo se puede asignar a la carpeta si también tiene definidos los ámbitos de la aplicación. Con solo ámbitos de usuario, la aplicación no aparece en Gestionar acceso y solo se aplican los roles de carpeta del usuario	La aplicación no puede tener ámbitos de aplicación y nunca aparece en Gestionar acceso; solo se aplican los roles de carpeta del usuario
Crear en IU	Seleccionar confidencial	Seleccionar No confidencial

Para utilizar esta variante:

1. Al crear la aplicación externa, selecciona No confidencial en lugar de Confidencial. Solo está disponible la pestaña Ámbitos de usuario . Añade OR.Execution, añade OR.Jobs para servidores codificados o de comando, y añade la URL de redirección.

2. Asigna solo el usuario (no la aplicación) a la carpeta con el rol adecuado.

3. Utiliza el siguiente flujo de autorización basado en 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>
   

El token resultante es idéntico al token de ámbito de usuario confidencial: sub es el GUID del usuario, sub_type es user y la audiencia es UiPath.Orchestrator. Servidores MCP lo trata de la misma manera que la variante confidencial.

Características del token (ámbitos de usuario)

Estas características se aplican tanto a las aplicaciones confidenciales como a las no confidenciales que utilizan el flujo de código de autorización:

• JWT con sub establecido en el GUID del usuario y sub_type establecido en user.
• Audiencia: UiPath.Orchestrator.
• Los servidores MCP resuelven el token como identidad de usuario: en la capa de servidores MCP, el token sigue la misma ruta de código que el inicio de sesión interactivo.
• El enrutamiento de clave de carpeta no se aplica (llamada única de Orchestrator entre carpetas).
• Las actividades de Integration Service funcionan (el contexto de usuario está presente).
• Actualizar token: devuelto cuando offline_access se incluye en el parámetro scope ; no se devuelve sin él. La duración del token de actualización es de 60 días.

Conexión de Copilot Studio a un servidor MCP de UiPath

Utiliza este procedimiento para conectar un agente de Microsoft Copilot Studio a un servidor MCP de UiPath utilizando la autenticación manual OAuth 2.0.

Requisitos previos

• Puedes gestionar aplicaciones externas.
• Puedes gestionar el acceso a las carpetas en Orchestrator.
• Puedes configurar las conexiones en Copilot Studio.

Pasos

1. En UiPath, ve a Admin > Apps externas y selecciona Añadir aplicación.

2. Establece el tipo de aplicación en Confidencial.

3. En Recursos, añade Acceso a la API de Orchestrator con el ámbito OR.Execution , y añádelo como ámbito de Aplicación y como ámbito de Usuario.

   Si el servidor MCP es de tipo Codificado o Comando, añade también OR.Jobs en ambos ámbitos.

   Añadir el ámbito en la pestaña Ámbitos de la aplicación es lo que hace que el paso 6 funcione; una aplicación con solo ámbitos de usuario no se puede asignar a una carpeta en Administrar acceso.

4. Introduzca una URL de redireccionamiento ficticia por ahora (por ejemplo, https://cloud.uipath.com).

5. Guarda la aplicación y copia el ID de cliente y el Secreto de cliente.

6. En Orchestrator, asigna la aplicación externa a la carpeta que contiene el servidor MCP con el rol de Automation User . Esto funciona porque la aplicación recibió ámbitos de aplicación en el paso 3; una aplicación con solo ámbitos de usuario no se puede asignar a carpeta. Asigna también el rol de tenant Allow to be Automation User.

7. En Copilot Studio, añade la URL del servidor MCP con autenticación manual OAuth 2.0 , utilizando los siguientes valores:

   • ID de cliente: el valor copiado en el paso 5.
   • Secreto de cliente: el valor copiado en el paso 5.
   • URL de autorización: https://cloud.uipath.com/identity_/connect/authorize
   • URL del token: https://cloud.uipath.com/identity_/connect/token
   • Actualizar URL: https://cloud.uipath.com/identity_/connect/token
   • Ámbito: OR.Default

8. Selecciona Crear en Copilot Studio. Copilot Studio genera una URL de redirección, el campo aparece en gris antes de la creación.

9. Copia la URL de redirección generada y añádela a las URL de redirección de la aplicación externa en Administrador de UiPath > Apps externas.

10. Vuelve a Copilot Studio y selecciona Conectar.

Resultado

Copilot Studio está conectado al servidor MCP de UiPath. El usuario inicia sesión a través del flujo OAuth cuando el agente accede a las herramientas de MCP.

Conectar ChatGPT a un servidor MCP de UiPath

Utiliza este procedimiento para las aplicaciones de ChatGPT nuevas o no publicadas en las que el registro dinámico de clientes (DCR) no funciona.

ChatGPT cambió sus URI de redirección de /connector_platform_oauth_redirect a /connector/oauth/{callback_id}. Las aplicaciones ya publicadas siguen funcionando con DCR. Las aplicaciones nuevas o no publicadas requieren una configuración manual de OAuth.

Requisitos previos

• Puedes gestionar aplicaciones externas.
• Puedes crear aplicaciones en ChatGPT.

Obtener la URL de devolución de llamada de ChatGPT

1. Ve a ChatGPT, selecciona tu perfil, luego selecciona Apps y luego Crear aplicación.
2. Introduce el nombre de la aplicación, la descripción y la URL del servidor MCP de UiPath.
3. Selecciona Configuración avanzada.
4. En Método de registro, cambia de DCR a Cliente OAuth definido por el usuario.
5. Copia la URL de devolución de llamada (https://chatgpt.com/connector/oauth/{callback_id}).
6. Mantener abierta esta pestaña del navegador.

Crea la aplicación externa en UiPath

1. Ve a Admin > Apps externas y selecciona Añadir aplicación.

2. Selecciona Confidencial como tipo de aplicación.

3. Añade OR.Execution, OR.Jobs y OR.Folders en las pestañas Ámbito(s) de aplicación y Ámbito(s) de usuario .

   Añadir los ámbitos en la pestaña Ámbitos de la aplicación es lo que permite que funcione el siguiente paso (asignación de carpetas); una aplicación con solo ámbitos de usuario no se puede asignar a una carpeta en Administrar acceso.

4. En el campo URL de redirección , pegue la URL de devolución de llamada copiada de ChatGPT.

5. Guarda la aplicación y copia el ID de cliente y el Secreto de cliente.

Asignar la aplicación externa a la carpeta

1. En Orchestrator, abre la carpeta que contiene el servidor MCP.
2. Ve a Gestionar acceso > Asignar.
3. Añade la aplicación externa con el rol de Automation User .

Configurar ChatGPT

1. Vuelve a la pestaña del navegador ChatGPT.
2. Introduce el ID de cliente OAuth y el Secreto de cliente copiados de la aplicación externa.
3. En Registro de cliente > Método de autenticación de punto final de token, client_secret_basic.
4. En Ámbitos > Ámbitos predeterminados, desactiva cualquier ámbito predeterminado existente.
5. En Ámbitos > Ámbitos base, OR.Default.
6. Selecciona Crear.

Resultado

ChatGPT está conectado al servidor MCP de UiPath. Los usuarios se autentican a través del flujo OAuth manual cuando la aplicación accede a las herramientas de MCP.

Comportamiento de OR.Default

Se hace referencia a OR.Default tanto en los flujos de ámbito de aplicación como de ámbito de usuario, pero se comporta de forma diferente en cada contexto:

Context	Comportamiento
Ámbitos de la aplicación, en el parámetro --scope en la solicitud del token	Controla cómo Orchestrator resuelve los permisos. Cuando OR.Default es el único ámbito, Orchestrator utiliza asignaciones de roles de carpeta en lugar de reclamaciones de ámbito explícitas. Consulta Comprender las combinaciones de ámbitos.
Ámbitos de usuario, en el parámetro scope de la solicitud de autorización	Se utiliza como parámetro de ámbito en la solicitud de autorización. En el nivel de Orchestrator, habilita un modo de autorización permisivo en el que se concede acceso si se pasa la comprobación de ámbito o los permisos del rol de carpeta del usuario. Servidores MCP no utiliza OR.Default para tokens de ámbito de usuario, siempre realiza llamadas únicas entre carpetas independientemente de los ámbitos que lleve el token.

En ningún caso OR.Default es un ámbito que se configura en la IU de Apps externas. Solo aparece en el parámetro de ámbito en el momento de la solicitud de token o autorización.