身份验证

UiPath CLI 支持映射到三个常见用例的三种身份验证流程：使用笔记本电脑的开发者、使用外部应用程序调用 Orchestrator 的 CI/CD 管道，以及已持有访问令牌的容器或临时运行程序。这三者均在同一位置结束，即经过身份验证的会话，每个后续uip命令都会重用该会话，但它们获取令牌的方式以及 CLI 刷新令牌的方式有所不同。

选择一个流程

您正在…	使用此选项	如何
使用笔记本电脑或工作站的开发者	交互式 OAuth2	uip login 打开浏览器，登录一次，令牌会自动存储和刷新。
CI/CD 管道或服务器	外部应用程序（客户端凭据）	在 UiPath 中创建一个外部应用程序，将其 ID 和密码传递给uip login --client-id … --client-secret … 。系统会存储和刷新令牌。
容器、临时运行器或任何已持有令牌的流程	环境变量身份验证	设置UIPATH_CLI_ENABLE_ENV_AUTH=true并通过环境变量提供令牌和组织/租户。未写入任何文件；则无需刷新。

uip logout会清除前两个流程中的所有磁盘凭据。此 env-var 流程无需清除任何内容 — 请取消设置环境变量。

流程 1 — 交互式 OAuth2

运行不带参数的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

存储凭据的位置

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

1. 显式文件夹 — 如果传递了--file <folder> ，则 CLI 将使用该文件夹。请传递文件夹，而非文件路径。
2. 从当前工作目录开始查找.uipath/ ，以便项目文件夹可以进行自己的会话，而无需访问用户的主页。
3. ~/.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 status显示当前组织、租户和令牌到期日期。

提示：

每个uip or …命令还会接受--tenant <name> ，以覆盖单次调用的会话租户 — 当您需要在同一脚本中对两个租户运行而不重新登录时，这非常有用。

自动刷新

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

流程 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"

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

警告：

请勿将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"

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

某些环境（由另一个管道构建的容器、计划的作业、测试设备）已经持有有效的 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"

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

注意和限制

• 不透明令牌。调用者负责令牌的新鲜度。没有刷新流程。当令牌过期时， uip login status会报告Expired ，并且在变量轮换之前，命令将失败。
• 服务器 URL 来自令牌。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

注销

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 (env-var auth) 来解决此问题 — 两者都完全避免浏览器回调。

另请参阅

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