使用外部应用程序访问 UiPath 资源

这些说明适用于在具有内部部署 Orchestrator 安装或自托管 Orchestrator 安装的环境中维护 UiPath 产品与外部应用程序之间集成的开发者。

提示：

在开始之前：

• 外部应用程序必须已由组织管理员在“ 外部应用程序 ”中注册。
• 从组织管理员处获取注册详细信息。

使用不同的授权类型

在注册外部应用程序后，您必须为外部应用程序实施适当的授权机制，并为允许的作用域提供适当的授权类型，以便外部应用程序可以检索访问令牌。

要使用的授权类型：

应用程序类型	范围	要求的授权类型
机密	用户	授权代码 （说明）
机密	应用程序	客户端凭据 （说明）
非机密	用户	带 PKCE 的授权代码（说明）

备注：

如果同时向用户和应用程序作用域授予了一个机密应用程序，则您必须同时实现这两种授予类型。

当用户和应用程序作用域内的作用域名称相同时（如在 Orchestrator 中），您使用的授予类型将决定是在用户作用域还是应用程序作用域下调用资源。

用于访问 UiPath 资源的授权服务器是 UiPath Identity Server，它支持 OAuth 2.0 框架。

授权代码

当注册的应用程序为机密类型且请求针对用户作用域时，请使用此授权类型。

使用此授予类型的流程如下所示：

1. 外部应用程序向 UiPath Identity Server 授权端点发送授权请求，以获取授权代码。

   {BaseURL}/identity/connect/authorize?
   response_type=code&
   client_id={app_id}&
   scope={scopes}&
   redirect_uri={redirect_url}

   • {BaseURL}/identity/connect/authorize 是 Identity Server 授权端点。
   • response_type=code 指定应用程序正在请求授权代码。
   • client_id 必须包含应用程序 ID（显示在“外部应用程序”页面上）。
   • scope：包含应用程序请求的作用域，以空格分隔；例如 OR.Machines OR.Robots。
     注意：查看 Swagger 中的端点，以获取所需的作用域值。例如：

     

   • redirect_uri 包含 UiPath Identity Server 在授予授权代码后重定向授权请求时使用的 URL。
2. 用户必须登录到 Orchestrator，以对授权请求进行身份验证。如果出现以下情况，请求将失败：
   • 用户不在已注册外部应用程序的租户中

   • 对于某些资源，已登录的用户对请求的范围没有所需要的权限

3. 外部应用程序接收授权代码。授权请求重定向示例: {redirect_url}?code={authorization_code}&scope={scopes}。
   您只能使用一次授权代码。
4. 外部应用程序使用授权代码和身份验证详细信息（client_id 和 client_secret）从 UiPath Identity Server 请求访问令牌。这些请求包含在对令牌端点 {BaseURL}/identity/connect/token 的 POST 请求的正文中。

   {
       "grant_type": "authorization_code",
       "code": "{authorization_code}",
       "redirect_uri": "{redirect_url}",
       "client_id": "{app_id}",
       "client_secret": "{app_secret}"
   }

   如果您使用的是 Postman 或类似工具，请使用内容类型 application/x-www-form-urlencoded。

   grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_secret}

   备注：

   在“ 外部应用程序”中注册机密应用程序后，将返回 client_secret 。

   对于非机密应用程序，请使用 code_challenge 和 code_challenge_method，而不要使用client_secret。
5. 外部应用程序收到包含访问令牌的响应，例如：

   {
       "access_token":"{access_token}",
       "expires_in":3600,
       "token_type":"Bearer",
       "scope":"{scopes}"
   }

现在，应用程序可以使用访问令牌来访问用户资源，直到令牌过期（一小时）。有关更多信息，请参见使用访问令牌和获取刷新令牌。

使用 PCKE 的授权代码

如果注册的应用程序是非机密类型且请求是针对用户作用域，则请使用此授权类型。

流程与使用授权代码时相同，不同之处为在授权请求中，您需要包括以下请求查询参数：

• code_challenge_method，必须为 S256
• code_challenge，这是从 code_verifier 派生的加密随机字符串，用于将授权请求连接到令牌请求。

您必须使用代码验证程序算法来生成代码质询。您也可以创建自己的算法，但前提是它必须符合 rfc7636 标准。

{BaseURL}/identity/connect/authorize? 
  response_type=code
  &client_id={app_id}
  &scope={scopes}
  &redirect_uri={redirect_url}
  &code_challenge={cryptographically-random string from code_verifier}
  &code_challenge_method=S256

在发送至 {BaseURL}/identity/connect/token 的 POST 令牌请求中，您需要在请求正文中包含 code_verifier（用于生成 code_challenge 的原始字符串）。

如果您使用的是 Postman 或类似工具，请使用内容类型 application/x-www-form-urlencoded。

{ 
    grant_type: "authorization_code" 
    code: "{authorization_code}" 
    redirect_uri: "{redirect_url}" 
    client_id: "{app_id}" 
    code_verifier: "{code_verifier}" 
}

响应包括访问令牌，应用程序可使用该访问令牌来访问用户资源，直到令牌过期（一小时）。有关更多信息，请参见使用访问令牌和获取刷新令牌。

客户端凭据

为了让机密应用程序访问应用程序作用域，外部应用程序会向 Identity Server 令牌端点发送包含 client_id 和 client_secret 的 POST 请求 {BaseURL}/identity/connect/token，以请求访问令牌。

如果您使用的是 Postman 或类似工具，请使用内容类型 application/x-www-form-urlencoded。

{
    grant_type: "client_credentials"
    client_id: "{app_id}"
    client_secret: "{app_secret}"
    scope: "{scopes}"
}

使用访问令牌

应用程序获得访问令牌后，它可以使用令牌来访问允许的资源（仅限于选定的作用域），直到令牌过期（一小时）。

这是向 odata/Machines API 发出的一个示例请求，该请求在“授权”标头中使用访问令牌，其中访问令牌的作用域中包含“OR.Machines 作用域”。

curl -X GET "{OrchestratorURL}/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"l

注意：有关可用 API 的信息，请参阅 {OrchestratorURL}/swagger/index.html 上的 Orchestrator API Swagger。

获取刷新令牌

访问令牌将在一小时后过期。外部应用程序可以通过交换刷新令牌来获取新的访问令牌，而无需用户交互。

刷新令牌也仅能使用一次，并且会在 60 天后过期。

机密和非机密外部应用程序都可以请求刷新令牌。为此，它们必须在授权请求的 scope 参数中包含 offline_access，以便可以在令牌请求中使用授权代码来获取刷新令牌。

要获取刷新令牌，请将包含授权代码的 POST 请求发送到令牌端点

{BaseURL}/identity/connect/token。

如果您使用的是 Postman 或类似工具，请使用内容类型 application/x-www-form-urlencoded。

该请求将返回一个新的访问令牌和一个刷新令牌：

{ 
    "access_token": "{access_token}", 
    "expires_in": 3600, 
    "token_type": "Bearer", 
    "refresh_token": "{refresh_token}", 
    "scope": "OR.Machines OR.Robots offline_access" 
}

要获取新的刷新令牌和新的访问令牌，请使用 refresh_token 授予类型向令牌端点 {BaseURL}/identity/connect/token 发送 POST 请求。

如果您使用的是 Postman 或类似工具，请使用内容类型 application/x-www-form-urlencoded。

{
    grant_type: "refresh_token"
    client_id: "{app_id}"
    client_secret: "{app_secret}"
    refresh_token: "{existing_refresh_token}"
}

该响应将返回一个新的访问令牌和一个新的刷新令牌。

现有刷新令牌在使用后不再有效，因此请确保使用收到的新刷新令牌。

UiPath Identity Server 端点

如果您使用的是 Postman 或类似工具，请为发送至 Identity Server 端点的请求使用内容类型 application/x-www-form-urlencoded。如果您以编程方式发出请求，则不需要这样做。

发现： {BaseURL}/identity/.well-known/openid-configuration

授权： {BaseURL}/identity/connect/authorize

令牌： {BaseURL}/identity/connect/token