使用外部应用程序进行身份验证

外部应用程序在 UiPath Cloud 中的“管理员”>“External Apps”中配置，并使用 OAuth 2.0 进行身份验证。它们支持多种身份验证方案：

• 无需用户登录（授予客户端凭据）的无人值守或自动访问
• 执行各自 OAuth 流程的第三方集成，例如 Copilot Studio 或 ChatGPT（授权代码授予）
• 无法安全存储任何客户端密码的桌面或移动应用程序（使用 PKCE 授予授权代码）

了解外部应用程序类型

创建外部应用程序时，您需要做出两个选择，这两个选择决定了身份验证的工作方式：

• 应用程序是机密还是非机密。
• 是使用应用程序作用域还是用户作用域。

机密应用程序与非机密应用程序

	机密	非机密
客户端密码	创建时生成。必须妥善保存。	未生成
由谁进行身份验证	应用程序本身 (无需用户) 或通过应用程序访问的用户	仅通过应用程序的用户
用户界面中的“作用域”选项卡	应用程序作用域和用户作用域	仅限用户作用域

当可以为后端、服务器和 CI/CD 管道安全存储密码时，请使用机密应用程序。

对于无法保证密码安全的桌面应用程序、移动应用程序或基于浏览器的单页应用程序，请使用非机密应用程序。非机密应用程序需要 PKCE。

应用程序作用域 与用户作用域

“外部 Apps 用户界面”中的两个选项卡映射到完全不同的 OAuth 流：

	应用程序作用域	用户作用域
OAuth grant type	客户端凭据 ( client_credentials )	授权代码 ( authorization_code )
身份	应用程序本身	通过应用程序登录的人类用户
令牌sub声明	应用程序的 client_id	用户 ID
令牌sub_type声明	service.external	user
MCP 服务器如何解读	UserType.ExternalApp	UserType.User
需要用户登录	否	是，浏览器重定向到 UiPath 登录
Integration Service 活动	不支持（无用户上下文）	支持（存在用户上下文）
文件夹访问	必须将应用程序显式分配给该文件夹	用户必须在文件夹中具有适当的角色。只有当应用程序也具有应用程序作用域时，才能将其分配给文件夹；无法对仅具有“用户”作用域的应用程序分配文件夹
可用日期	仅限机密应用程序	机密和非机密

保存外部应用程序时，Identity Server 会根据您配置的作用域类型设置允许客户端使用的授权类型：

• 仅应用程序作用域 → 允许client_credentials
• 仅用户作用域 → 允许authorization_code
• 两者同时存在 → 允许同时存在

如果您手动向https://cloud.uipath.com/identity_/connect/token请求令牌，则必须在每个令牌请求中显式指定grant_type 。省略它会返回错误。发送客户端不允许的授权类型也会失败。

正在设置应用程序作用域身份验证

应用程序作用域使用客户端授予的凭据。这是唯一无需用户交互即可工作的身份验证方法。

重要提示：

使用客户端凭据访问时，公开 Integration Service 连接器的 UiPath MCP 服务器会失败。对于 Integration Service 支持的工具，请改用用户作用域身份验证。

先决条件

• 您可以在 UiPath 中访问“管理”>“外部 Apps” 。
• 您可以在 Orchestrator 中管理文件夹访问权限。

创建外部应用程序

1. 转到 UiPath，选择“ 管理员 ” ，然后选择“ 外部 Apps ” 。

2. 选择“添加应用程序”。

3. 输入名称并将应用程序类型保留为“机密” 。

4. 选择“应用程序作用域”选项卡。

   重要提示：

   在“应用程序作用域”选项卡下添加作用域，而不是在“用户作用域”选项卡下添加作用域。

5. 添加以下作用域：

   • OR.Execution ：对于列出工具为必要项。MCP 服务器在处理tools/list时调用 Orchestrator ListReleases API 以获取流程元数据，并且该端点已获得OR.Execution授权。
   • OR.Jobs ：执行工具所必需的。所有将流程作为工具运行的 MCP 服务器类型（UiPath、Coded 和 Command）都会调用 Orchestrator StartJobs API，该 API 已通过OR.Jobs授权。

6. 选择“添加” ，然后复制“客户端 ID”和“客户端密码” 。

将外部应用程序分配给文件夹

1. 在 Orchestrator 中，导航到“租户”>“管理访问权限” ，或导航到特定文件夹的访问权限设置。

2. 添加具有“自动化用户”角色的外部应用程序。

   此角色包括访问 MCP 服务器所需的MCPServers.View权限。

使用外部应用程序进行身份验证

根据您希望 Orchestrator 解析权限的方式选择以下选项之一。

选项 A：仅限OR.Default （为简单起见，建议使用）

该令牌不包含明确的 API 级作用域。Orchestrator 通过在每个文件夹中分配给外部应用程序的角色来解析权限。跨文件夹 API 调用无需文件夹密钥标头。此选项要求外部应用程序在目标文件夹中具有“自动化用户”角色。

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

选项 B：显式作用域

令牌包含明确的OR.Execution和OR.Jobs作用域声明。Orchestrator 直接在每次 API 调用时验证这些作用域。此选项需要X-UIPATH-FolderKey标头，但 MCP 服务器会自动处理此问题。

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"

结果

CLI 将获取访问令牌，您可以在 MCP 服务器请求的Authorization标头中使用该访问令牌。

了解作用域组合

OR.Default不是您在外部Apps用户界面中配置的作用域。这是您在请求令牌时包含在--scope参数中的特殊作用域。您请求的作用域将确定 Orchestrator 如何解析权限以及 MCP 服务器如何路由 API 调用。

MCP 流涉及需要不同作用域的两个 Orchestrator API 调用：

• tools/list ：MCP 服务器调用odata/Releases/ListReleases以获取流程元数据。发布控制器需要OR.Execution 。
• tools/call ：MCP 服务器调用odata/Jobs/StartJobs以执行流程。作业控制器需要OR.Jobs 。

下表总结了不同作用域组合的行为：

令牌请求时的作用域	Orchestrator 权限解析	X-UIPATH-FolderKey 页眉	MCP 服务器行为
OR.Default 仅	文件夹级别角色分配（例如，目标文件夹中的 Automation User）	非必填	单个跨文件夹 API 调用
仅限特定作用域（例如OR.Execution OR.Jobs ）	令牌中的显式作用域声明	每次 API 调用都需要	每个文件夹的 API 调用（按文件夹分组）
OR.Default 加上特定的作用域	显式作用域声明（特定作用域优先）	每次 API 调用都需要	每个文件夹的 API 调用（按文件夹分组）

行为说明：

• 仅请求OR.Default是最简单的设置。Orchestrator 会检查在每个文件夹中为外部应用程序分配的角色。Automation User角色包括版本和作业访问权限。
• 添加特定作用域，例如OR.Execution或OR.Jobs （带或不带OR.Default ）会更改文件夹解析的工作方式。Orchestrator 同时检查作用域声明和文件夹角色权限，当其中一项检查通过后，将授予访问权限。这需要在每次 API 调用时使用X-UIPATH-FolderKey标头。MCP 服务器会检测令牌的作用域并在需要时按文件夹进行调用，从而自动处理此问题。
• 如果没有OR.Default ，特定的OR.*作用域会绕过文件夹级别的角色解析，并授予租户中所有文件夹的访问权限。API 路由仍需要X-UIPATH-FolderKey标头。

已知限制：获取当前用户的文件夹

当使用客户端凭据 ( uipath run ) 在本地运行 MCP 服务器时，Python SDK 调用orchestrator_/api/FoldersNavigation/GetFoldersForCurrentUser以将文件夹路径解析为文件夹密钥。此 API 不支持客户端凭据身份验证，需要交互式用户令牌。

要解决此问题，请直接设置UIPATH_FOLDER_KEY环境变量。设置此变量后，SDK 会完全跳过GetFoldersForCurrentUser调用：

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

您可以在 Orchestrator API 或文件夹 URL 中找到文件夹 GUID。

常见错误：计算机凭据与外部应用程序

使用计算机凭据（来自Orchestrator > 计算机）而不是外部应用程序凭据，将返回invalid_scope错误。计算机凭据用于机器人身份验证，而不用于 API 访问。

如果您看到：

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

请验证您使用的是来自“管理员”>“External Apps”的凭据，而不是来自“Orchestrator”>“计算机”的凭据。

正在设置用户作用域身份验证

用户作用域使用授权代码授予。用户必须通过外部应用程序登录，令牌包含用户的身份，而不是应用程序的身份。

在以下情况下使用用户作用域身份验证：

• MCP 服务器公开由 Integration Service 活动（连接器）支持的工具。
• 您正在与执行自身 OAuth 流程（Copilot Studio、ChatGPT）的第三方客户端集成。
• 您需要基于用户的身份，需要根据登录者（而不是正在调用的应用程序）进行访问控制。

先决条件

• 您可以在 UiPath 中访问“管理”>“外部 Apps” 。
• 您可以在 Orchestrator 中管理文件夹访问权限。
• 您知道客户端应用程序的重定向 URL。

创建外部应用程序

1. 转到 UiPath，选择“ 管理员 ” ，然后选择“ 外部 Apps ” 。

2. 选择“添加应用程序”。

3. 输入名称并将应用程序类型保留为“机密” 。

4. 选择“用户作用域”选项卡。

   重要提示：

   在“用户作用域”选项卡下添加作用域，而不是在“应用程序作用域”选项卡下添加作用域。

5. 添加以下作用域：

   • OR.Execution ：对于列出工具为必要项。
   • OR.Jobs ：执行工具（Coded 或 Command 服务器）所必需的。

6. 添加重定向 URL 。这是登录后发送到用户浏览器的地址。使用客户端应用程序提供的回调 URL。

   对于 Copilot Studio，最初使用虚拟 URL，并在创建连接后更新该 URL。

7. 选择“添加” ，然后复制“客户端 ID”和“客户端密码” 。

配置文件夹访问权限

由于上面创建的外部应用程序只有“用户”作用域，因此无法在“管理访问权限”中将其分配给文件夹。文件夹访问权限通过用户角色授予；令牌继承用户的权限，而不是应用程序的权限。

1. 在 Orchestrator 中，导航到“租户”>“管理访问权限” ，或导航到特定文件夹的访问权限设置。

2. 分配将以Automation User 、 Automation Developer或Folder Administrator角色登录的用户。

   此角色决定用户可以在文件夹中执行的操作，并且必须包含访问 MCP 服务器所需的MCPServers.View权限。

如果外部应用程序也定义了应用程序作用域，则您还可以将应用程序本身分配给具有“自动化用户”角色的文件夹。仅不涉及用户登录的客户端凭据流程才需要。

运行授权代码流程

客户端应用程序启动流程。

1. 将用户重定向到授权端点：

   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. 用户通过浏览器登录，系统会通过code参数将其重定向回回调 URL。

3. 将授权代码交换为服务器端应用程序中的令牌：

   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>
   

结果

令牌端点返回一个访问令牌，您可以在 MCP 服务器请求的Authorization标头中使用该令牌。

变体：使用 PKCE 的非机密应用程序

同一流程适用于非机密外部应用程序。其中差异总结如下：

	机密	非机密
客户端密码	包含在令牌交换中	未使用 (不存在密码)
PKCE	可选	必需
文件夹分配	只有当应用程序还定义了应用程序作用域时，才能将其分配给文件夹。对于仅用户作用域，应用程序不会显示在“管理访问权限”中，并且仅用户的文件夹角色适用	应用程序不能具有应用程序作用域，并且永远不会出现在“管理访问权限”中；仅用户的文件夹角色适用
在用户界面中创建	选择机密信息	选择“非机密”

要使用此变体：

1. 创建外部应用程序时，请选择“非机密”而不是“机密” 。只有“用户”作用域选项卡可用。添加OR.Execution ，为编码服务器或命令服务器添加OR.Jobs ，并添加重定向 URL。

2. 仅将用户（不包括应用程序）分配到具有适当角色的文件夹。

3. 使用以下基于 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>
   

生成的令牌与机密用户作用域令牌相同： sub是用户 GUID， sub_type是user ，受众为UiPath.Orchestrator 。MCP 服务器将其视为机密变体。

令牌特征（用户作用域）

这些特征适用于使用授权代码流程的机密和非机密应用程序：

• 将sub设置为用户的 GUID，将sub_type设置为user JWT。
• 受众： UiPath.Orchestrator 。
• MCP 服务器将令牌解析为用户身份 — 在 MCP 服务器层，令牌遵循与交互式登录相同的代码路径。
• 文件夹密钥路由不适用（单个跨文件夹 Orchestrator 调用）。
• Integration Service 活动有效（存在用户上下文）。
• 刷新令牌：当scope参数中包含offline_access时返回；如果没有它，则不会返回。刷新令牌的生存期为 60 天。

将 Copilot Studio 连接到 UiPath MCP 服务器

遵循此过程，通过 OAuth 2.0 手动身份验证将 Microsoft Copilot Studio 智能体连接到 UiPath MCP 服务器。

先决条件

• 您可以管理外部应用程序。
• 您可以在 Orchestrator 中管理文件夹访问权限。
• 您可以在 Copilot Studio 中配置连接。

步骤

1. 在 UiPath 中，转到“管理”>“外部 Apps” ，然后选择“添加应用程序” 。

2. 将应用程序类型设置为机密。

3. 在“资源”下，添加作用域为OR.Execution “Orchestrator API 访问权限”，并将其同时添加为应用程序作用域和用户作用域。

   如果“MCP 服务器”是“编码”或“命令”类型，则还要在两个作用域下添加OR.Jobs 。

   在“应用程序作用域”选项卡下添加作用域才是第 6 步有效的关键；无法在“管理访问权限”中将仅具有“用户”作用域的应用程序分配给文件夹。

4. 暂时输入一个虚拟重定向 URL（例如https://cloud.uipath.com ）。

5. 保存应用程序，然后复制客户端 ID和客户端密码。

6. 在 Orchestrator 中，使用自动化用户角色将外部应用程序分配到包含 MCP 服务器的文件夹。这是因为在步骤 3 中为应用程序提供了应用程序作用域；无法为仅具有“用户”作用域的应用程序分配文件夹。同时分配租户角色Allow to be Automation User 。

7. 在 Copilot Studio 中，使用以下值通过OAuth 2.0 手动身份验证添加 MCP 服务器 URL：

   • 客户端 ID ：在步骤 5 中复制的值。
   • 客户端密码：在步骤 5 中复制的值。
   • 授权 URL ： https://cloud.uipath.com/identity_/connect/authorize
   • 令牌 URL ： https://cloud.uipath.com/identity_/connect/token
   • 刷新 URL ： https://cloud.uipath.com/identity_/connect/token
   • 作用域： OR.Default

8. 在 Copilot Studio 中选择“创建” 。Copilot Studio 会生成重定向 URL，创建前该字段显示为灰色。

9. 复制生成的重定向 URL，并将其添加到“UiPath管理员”>“外部 Apps”中的外部应用程序的重定向 URL 。

10. 返回 Copilot Studio 并选择“连接” 。

结果

Copilot Studio 已连接到 UiPath MCP 服务器。当智能体访问 MCP 工具时，用户通过 OAuth 流程登录。

将 ChatGPT 连接到 UiPath MCP 服务器

此过程用于无法使用动态客户端注册 (DCR) 的新版或未发布的 ChatGPT 应用程序。

ChatGPT 已将其重定向 URI 从/connector_platform_oauth_redirect更改为/connector/oauth/{callback_id} 。已发布的应用程序仍可使用 DCR。新的或未发布的应用程序需要手动 OAuth 设置。

先决条件

• 您可以管理外部应用程序。
• 您可以在 ChatGPT 中创建应用程序。

从 ChatGPT 获取回调 URL

1. 转到 ChatGPT，选择您的配置文件，然后选择Apps ，然后选择创建应用程序。
2. 输入应用程序名称、描述和来自 UiPath 的 MCP 服务器 URL。
3. 选择“高级设置” 。
4. 在“注册方法”下，从“DCR”更改为“用户定义的 OAuth 客户端” 。
5. 复制回调 URL ( https://chatgpt.com/connector/oauth/{callback_id} )。
6. 保持此浏览器标签页打开。

在 UiPath 中创建外部应用程序

1. 转到“管理”>“外部 Apps” ，然后选择“添加应用程序” 。

2. 选择“机密”作为应用程序类型。

3. 在“应用程序作用域”和“用户作用域”选项卡下添加OR.Execution 、 OR.Jobs和OR.Folders 。

   在“应用程序作用域”选项卡下添加作用域，以便进行下一步（文件夹分配）；无法在“管理访问权限”中将仅具有“用户”作用域的应用程序分配给文件夹。

4. 在“重定向 URL”字段中，粘贴从 ChatGPT 复制的回调 URL。

5. 保存应用程序，然后复制客户端 ID和客户端密码。

将外部应用程序分配给文件夹

1. 在 Orchestrator 中，打开包含 MCP 服务器的文件夹。
2. 导航到“管理访问权限”>“分配” 。
3. 添加具有“自动化用户”角色的外部应用程序。

配置 ChatGPT

1. 返回到“ChatGPT”浏览器选项卡。
2. 输入从外部应用程序复制的OAuth 客户端 ID和客户端密码。
3. 在“客户端注册”>“令牌端点身份验证方法”下，选择client_secret_basic 。
4. 在“作用域”>“默认作用域”下，停用任何现有的默认作用域。
5. 在“作用域”>“基本作用域”下，添加OR.Default 。
6. 选择“创建”。

结果

ChatGPT 已连接到 UiPath MCP 服务器。当应用程序访问 MCP 工具时，用户通过手动 OAuth 流程进行身份验证。

OR.Default 的行为

OR.Default会同时在应用程序作用域和用户作用域的流程中引用，但其在各个上下文中的行为有所不同：

Context	行为
应用程序作用域，位于令牌请求的--scope参数中	控制 Orchestrator 如何解析权限。当OR.Default是唯一的作用域时，Orchestrator 使用文件夹角色分配，而不是显式的作用域声明。检查了解作用域组合。
用户作用域，在授权请求的scope参数中	用作授权请求中的作用域参数。在 Orchestrator 级别，它启用包容性授权模式，在该模式下，如果作用域检查或用户的文件夹角色权限通过，则会授予访问权限。MCP 服务器不将OR.Default用于用户作用域的令牌，它始终进行单次跨文件夹调用，无论令牌包含哪个作用域。

在这两种情况下， OR.Default都不是您在外部Apps用户界面中配置的作用域。它仅在请求令牌或授权时显示在作用域参数中。