UiPath CLI - 身份验证

uipath-cli

latest

false

UiPath CLI 用户指南

重要 :

请注意，此内容已使用机器翻译进行了本地化。新发布内容的本地化可能需要 1-2 周的时间才能完成。

身份验证

使用交互式 OAuth2、外部应用程序凭据或环境变量令牌流对 UiPath CLI 进行身份验证。

UiPath CLI 支持五种身份验证流程：使用笔记本电脑的开发者使用、使用外部应用程序调用 Orchestrator 的 CI/CD 管道、可以颁发自己的 OIDC 令牌而不是保存长期密码、容器或临时密码的 CI/CD 平台。已持有访问令牌的运行器，以及与本地 UiPath Robot 一起运行的流程。前三个过程在同一位置结束，即经过身份验证的会话保留到凭据文件夹中，以便每个后续 uip 命令重用，但它们获取令牌的方式不同，以及 CLI 刷新令牌的方式不同。第四个完全绕过磁盘状态。五个不同之处在于机器人自己在本地 IPC 通道上的身份。

选择一个流程

您正在…	使用此选项	如何
使用笔记本电脑或工作站的开发者	交互式 OAuth2	`uip login` 打开浏览器，登录一次，令牌会自动存储和刷新。
CI/CD 管道或服务器	外部应用程序（客户端凭据）	在 UiPath 中创建一个外部应用程序，将其 ID 和密码传递给`uip login --client-id … --client-secret …` 。系统会存储和刷新令牌。
一个可以创建自己的 OIDC 令牌（工作负载身份）的 CI/CD 平台	联合凭据	`uip login --client-id <app-id> --client-assertion env.OIDC_TOKEN` — OIDC JWT 代表客户端密码，因此没有需要存储或轮换的长期密码。需要 `--client-id`；与 `--client-secret` 互斥。
容器、临时运行器或任何已持有令牌的流程	环境变量身份验证	设置`UIPATH_CLI_ENABLE_ENV_AUTH=true`并通过环境变量提供令牌和组织/租户。未写入任何文件；则无需刷新。
在具有本地 UiPath Robot 的计算机上运行的流程	机器人凭据	设置 `UIPATH_CLI_ENFORCE_ROBOT_AUTH=true`。`uip` 通过机器人的本地 IPC 通道（而不是上述任何通道）进行身份验证。

uip logout 会清除前三个流程中的所有磁盘凭据。此 env-var 流程无需清除任何内容 — 请取消设置环境变量。机器人凭据也无需清除——机器人拥有身份标识。

提示：

--profile <name>是一个用于命名会话的全局标志（请参阅全局选项），以便多个登录（跨前三个流程中的任何一个）可以并排共存。为应重用给定命名会话的每个命令传递相同的 --profile；它与 --file 和 -f 上的 uip login/uip logout 互斥。

流程 1 — 交互式 OAuth2

运行不带参数的uip login ：

uip login
uip login

uip将在 UiPath 登录页面上打开默认浏览器。您进行身份验证后，UiPath 会重定向回uip正在侦听的本地回调，并且 CLI 会提示您选择租户。选择租户后，系统将保存会话，至此，您的操作完成。

有用的标志:

uip login --tenant DefaultTenant                 # skip the tenant picker
uip login --organization my-org                  # skip the org picker for users in multiple orgs
uip login --interactive                          # explicitly show the tenant picker even if --tenant was set
uip login --authority https://example.com        # point at a non-default identity authority (Automation Suite, staging)
uip login --scope "OR.Folders OR.Jobs"           # restrict the session to specific scopes
uip login --file /path/to/creds                  # store credentials in a non-default folder
uip login --tenant DefaultTenant                 # skip the tenant picker
uip login --organization my-org                  # skip the org picker for users in multiple orgs
uip login --interactive                          # explicitly show the tenant picker even if --tenant was set
uip login --authority https://example.com        # point at a non-default identity authority (Automation Suite, staging)
uip login --scope "OR.Folders OR.Jobs"           # restrict the session to specific scopes
uip login --file /path/to/creds                  # store credentials in a non-default folder

存储凭据的位置

默认情况下，会话存储在.uipath/文件夹中。uip会按顺序在三个位置中查找此文件夹:

显式文件夹 — 如果传递了--file <folder> ，则 CLI 将使用该文件夹。请传递文件夹，而非文件路径。
从当前工作目录开始查找.uipath/ ，以便项目文件夹可以进行自己的会话，而无需访问用户的主页。
~/.uipath/ — 默认回退。

当未经许可的链上的任何位置都不存在.uipath/时， uip login将在~/.uipath/中创建一个初始链。以不透明方式处理文件夹的内容 — 它们由uip login 、 uip login tenant set和uip logout管理。

在会话中管理租户

会话一次存储一个活动租户。无需重新运行完整登录流程即可切换：

uip login tenant list           # show all tenants available to your account
uip login tenant set MyTenant   # switch the active tenant
uip login tenant list           # show all tenants available to your account
uip login tenant set MyTenant   # switch the active tenant

uip login status显示当前组织、租户和令牌到期日期。

自动刷新

当访问令牌即将过期时， uip会在后台刷新访问令牌。除非刷新令牌本身过期或被撤销，或您更改了租户/组织，否则您不需要重新运行uip login 。

无头交互式登录 (`--no-browser`)

uip login 通常会打开系统浏览器。在无头环境中（需要真实用户身份（带有刷新令牌）而不是外部应用程序，但没有显示的 CI 驱动程序），传递--no-browser （或设置UIPATH_CLI_NO_BROWSER=true ）：

uip login --no-browser --tenant DefaultTenant
uip login --no-browser --tenant DefaultTenant

这将保留整个交互式流（PKCE、状态、本地回调、令牌保存），但不会启动浏览器。相反，它会将授权 URL 作为稳定的标记行打印到标准错误：

UIPATH_AUTH_URL https://cloud.uipath.com/identity_/connect/authorize?...
UIPATH_AUTH_URL https://cloud.uipath.com/identity_/connect/authorize?...

外部自动化（例如 Playwright 脚本）读取该行，在其控制的浏览器中打开 URL，完成登录，身份提供程序像往常一样重定向到 uip 的本地回调 — 以相同的方式完成登录如同人类单击一样。

打印的 URL 可以安全地显示在 CI 日志中：它仅包含公共 OAuth 值（PKCE code_challenge、state、client_id、redirect_uri、scope），没有密码，也没有令牌。--no-browser 对流程 2 或流程 3 没有影响（客户端凭据和联合登录始终不会打开浏览器）— 如果您将其与 --client-secret 或 --client-assertion 一起传递，系统会记录警告。

流程 2 — 外部应用程序（客户端凭据）

在 UiPath 中创建一个外部应用程序（Automation Cloud： “管理员”→“外部应用程序”），其中包含：

应用程序类型：机密
授权类型：客户端凭据
作用域：您的管道所需的作用域（例如OR.Folders 、 OR.Jobs 、 OR.Execution 、 OR.Assets 、 OR.Users ）。

复制生成的应用程序 ID和应用程序密码，并将其存储在管道的密码存储区（GitHub Actions 密码、Azure DevOps 变量组、Jenkins 凭据、保险库等）中。

从管道登录：

uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT"
uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT"

env.VAR_NAME 前缀

--client-id和--client-secret接受文本值或在运行时解析为环境变量的特殊前缀env. 。env.UIPATH_CLIENT_ID表示“从UIPATH_CLIENT_ID环境变量中读取值”。与在命令行中展开的--client-secret "$UIPATH_CLIENT_SECRET"不同，这会将密码值保留在 shell 历史记录和流程列表中。

文本值在以下情况下仍然有效：

uip login --client-id 3c7af0…-… --client-secret s3cr3t…   # works, but the secret is visible in history
uip login --client-id 3c7af0…-… --client-secret s3cr3t…   # works, but the secret is visible in history

警告：

请勿将UIPATH_CLIENT_ID / UIPATH_CLIENT_SECRET设置为环境变量，并期望uip login会自动选择它们。在 UiPath CLI 1.0 之前，支持uip login --env和隐式环境变量读取；系统已将其删除。您必须使用文本值或env.前缀显式传递标志。

作用域覆盖

如果外部应用程序具有多个作用域，并且您希望特定脚本的会话范围更小，请传递--scope ：

uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT" \
  --scope "OR.Folders OR.Jobs"
uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT" \
  --scope "OR.Folders OR.Jobs"

流程 3 — 联合凭据（工作负载身份）

对于可以创建自己的 OIDC 令牌的 CI/CD 平台，无需创建、存储或轮换外部应用程序客户端密码：

uip login \
  --client-id "$UIPATH_CLIENT_ID" \
  --client-assertion env.OIDC_TOKEN \
  --tenant "$UIPATH_TENANT"
uip login \
  --client-id "$UIPATH_CLIENT_ID" \
  --client-assertion env.OIDC_TOKEN \
  --tenant "$UIPATH_TENANT"

--client-assertion接受 OIDC JWT--client-secret --client-id--client-secret代替 / — 接受env. 前缀，以在运行时从环境变量中读取令牌（推荐操作：将原始 JWT 作为字符串传递文本值会打印警告，否则它将在 shell 历史记录和流程列表中可见）。

规则由 uip login 强制执行：

需要--client-id 。联合登录仍可通过客户端 ID 来识别外部应用程序；系统仅会替换密码。
与--client-secret互斥。同时失败且显示 --client-secret cannot be combined with --client-assertion.
--organization被忽略— 组织由客户端 ID 固定，与客户端凭据登录相同。
--no-browser无效— 与客户端凭据登录一样，任何情况下都不会为此流程打开浏览器。

通过身份验证后，会话的行为类似于外部应用程序会话：它会保留，自动刷新并通过 uip logout 清除。

流 4 — 环境变量身份验证（访问令牌已在手）

某些环境（由另一个管道构建的容器、计划的作业、测试设备）已经持有有效的 UiPath 访问令牌，不需要交互式登录或客户端凭据交换。通过设置以下内容来启用 env-var 身份验证流程：

export UIPATH_CLI_ENABLE_ENV_AUTH=true

export UIPATH_CLI_AUTH_TOKEN="$UIPATH_TOKEN"            # JWT access token
export UIPATH_CLI_ORGANIZATION_NAME=my-org
export UIPATH_CLI_ORGANIZATION_ID="$UIPATH_ORG_ID"
export UIPATH_CLI_TENANT_NAME=DefaultTenant
export UIPATH_CLI_TENANT_ID="$UIPATH_TENANT_ID"
export UIPATH_CLI_ENABLE_ENV_AUTH=true

export UIPATH_CLI_AUTH_TOKEN="$UIPATH_TOKEN"            # JWT access token
export UIPATH_CLI_ORGANIZATION_NAME=my-org
export UIPATH_CLI_ORGANIZATION_ID="$UIPATH_ORG_ID"
export UIPATH_CLI_TENANT_NAME=DefaultTenant
export UIPATH_CLI_TENANT_ID="$UIPATH_TENANT_ID"

使用UIPATH_CLI_ENABLE_ENV_AUTH=true ，每次uip调用都会根据这些变量进行身份验证，并完全绕过.uipath/文件夹。不存在uip login步骤，也不会将任何内容写入磁盘。

注意和限制

不透明令牌。调用者负责令牌的新鲜度。没有刷新流程。当令牌过期时， uip login status会报告Expired ，并且在变量轮换之前，命令将失败。
服务器 URL 派生自 JWT。当 UIPATH_CLI_AUTH_TOKEN 持有 JWT 访问令牌时，其 iss 声明具有授权 — 您无需设置 UIPATH_URL。这可以防止管道设置的 UIPATH_URL 与令牌不一致时出现错误路由。这不适用于个人访问令牌 — 见下文。
控制边界很重要。如果UIPATH_CLI_ENABLE_ENV_AUTH未设置或设置为文字字符串true以外的任何内容，则使用基于文件的流程。拼写错误的门会导致静默回退 — 请检查uip login status 。
缺失值明确失败。如果任何必填变量为空，则uip返回一个明确的错误变量命名错误，而不是通用的“未通过身份验证”。

使用 env-var auth 的示例 GitHub Actions 步骤：

- name: Run uip against Orchestrator
  env:
    UIPATH_CLI_ENABLE_ENV_AUTH: "true"
    UIPATH_CLI_AUTH_TOKEN: ${{ secrets.UIPATH_TOKEN }}
    UIPATH_CLI_ORGANIZATION_NAME: contoso
    UIPATH_CLI_ORGANIZATION_ID: ${{ secrets.UIPATH_ORG_ID }}
    UIPATH_CLI_TENANT_NAME: Default
    UIPATH_CLI_TENANT_ID: ${{ secrets.UIPATH_TENANT_ID }}
  run: uip or folders list --output json
- name: Run uip against Orchestrator
  env:
    UIPATH_CLI_ENABLE_ENV_AUTH: "true"
    UIPATH_CLI_AUTH_TOKEN: ${{ secrets.UIPATH_TOKEN }}
    UIPATH_CLI_ORGANIZATION_NAME: contoso
    UIPATH_CLI_ORGANIZATION_ID: ${{ secrets.UIPATH_ORG_ID }}
    UIPATH_CLI_TENANT_NAME: Default
    UIPATH_CLI_TENANT_ID: ${{ secrets.UIPATH_TENANT_ID }}
  run: uip or folders list --output json

使用个人访问令牌代替 JWT

UIPATH_CLI_AUTH_TOKEN 还接受使用 uip admin pat create 创建并使用 uip admin pat list/revoke/regenerate 管理的 UiPath 个人访问令牌（PAT - 一种不透明的“引用令牌”）。PAT 不是 JWT，因此它不包含 iss 声明 — 这改变了上述规则中的一个：

UIPATH_URL变为必需。由于 CLI 无法从不透明令牌中派生服务器 URL，因此请将 UIPATH_URL（例如https://cloud.uipath.com）。当令牌是 JWT 时，可忽略该字段，但当令牌是 PAT 时，则为必需。
不会报告过期情况。uip login status 显示的 Logged in 没有到期日期，也没有身份字段——令牌不透明，因此 CLI 也无法知晓。PAT 被撤销或过期后，命令将失败，并返回 401，在事先没有本地警告的情况下 — 请自行跟踪到期日期。
此流程中的所有其他变量（网关、租户/组织名称和 ID）的工作方式与 JWT 相同。

流程 5 — 机器人凭据（本地 UiPath Robot）

对于与本地 UiPath 机器人一起运行的流程（Studio 桌面版和其他机器人托管的上下文），身份验证可以完全遵循本地 IPC 通道上机器人自己的身份，而不是 CLI 自行管理的任何令牌：

export UIPATH_CLI_ENFORCE_ROBOT_AUTH=true
uip or folders list
export UIPATH_CLI_ENFORCE_ROBOT_AUTH=true
uip or folders list

设置网关后，uip 将与机器人的 IPC 端点通信，以获取访问令牌和资源基本 URL，完全绕过 .uipath/ 凭据文件夹和 env-var 流程。UIPATH_CLI_ENFORCE_ROBOT_AUTH 与 UIPATH_CLI_ENABLE_ENV_AUTH 互斥 — 两者同时设置将导致错误，而非静默覆盖。没有 uip login 步骤，没有要管理的刷新，也没有uip logout要清除的内容。

注销

uip logout                         # clear the default credentials folder
uip logout --file /path/to/creds   # clear a non-default credentials folder
uip logout                         # clear the default credentials folder
uip logout --file /path/to/creds   # clear a non-default credentials folder

logout清除.uipath/中存储的会话。在 env-var 流程中，没有要删除的内容 — 请取消设置变量。

故障排除

未登录

在临时链中未找到.uipath/文件夹，或存储的会话不可读。运行uip login （或设置 env-var 流程）并重试。

令牌已过期

交互式和外部应用程序会话即将过期时会自动刷新。如果看到Expired ，则表示刷新令牌本身已过期或已撤销 — 请重新运行uip login 。对于 env-var 身份验证，请轮换UIPATH_CLI_AUTH_TOKEN 。

存在多个组织成员，但选择了错误的组织

向--organization <logical-name>传递uip login ，以绕过组织选取器，或在uip login tenant list后传递，以查看会话实际绑定的对象。

公司代理会阻止浏览器回调

交互式流将在 127.0.0.1 上打开本地回调端口。大多数代理都会保留环回，但一些攻击性的设置会阻止环回。解决方法是使用流程 2（外部应用程序）、流程 3（联合凭据）或流程 4 (env-var auth) — 这三种流程都完全避免了浏览器回调。

另请参阅

安装 UiPath CLI — 身份验证前的一次性安装。
配置— 环境变量和标志优先级。
会话和凭据— 凭据文件夹的磁盘布局。
uip 登录参考、 uip 注销参考。

此页面有帮助吗？

前一个概述

下一个配置 (uipath.config.json)

选择一个流程​

流程 1 — 交互式 OAuth2​

存储凭据的位置​

在会话中管理租户​

自动刷新​

无头交互式登录 (--no-browser)​

流程 2 — 外部应用程序（客户端凭据）​

env.VAR_NAME 前缀​

作用域覆盖​

流程 3 — 联合凭据（工作负载身份）​

流 4 — 环境变量身份验证（访问令牌已在手）​

注意和限制​

使用个人访问令牌代替 JWT​

流程 5 — 机器人凭据（本地 UiPath Robot）​

注销​

故障排除​

未登录​

令牌已过期​

存在多个组织成员，但选择了错误的组织​

公司代理会阻止浏览器回调​

另请参阅​