外部应用程序 (OAuth)

These instructions are intended for developers who maintain the integration between UiPath® products and external applications using the UiPath® functionality based on the OAuth framework.

提示：

在开始之前：

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

概述

可以授予 UiPath 平台外部的应用程序访问 UiPath 资源的权限，而不必共享用户凭据。使用 OAuth 框架，组织管理员可以将授权委派给外部应用程序。注册后，这些应用程序就可以对 UiPath 应用程序或您在注册范围内包含的资源进行 API 调用。

如果管理员要在以下级别定义外部应用程序作用域：

• 组织级别（“管理员”>“外部应用程序”>“OAuth”）：您为其分配权限，例如 OR.Machines.Read 。这将向组织所有租户中的计算机授予读取权限。

• 租户级别（“Orchestrator”>“租户”>“管理访问权限”）或文件夹级别（“Orchestrator”>“文件夹”>“设置”>“管理访问权限”）：将应用程序添加到所需的租户或文件夹，并为其分配角色。此操作用于配置更细化的作用域。

  例如，如果使用 Assets.View 权限将应用程序添加到 EMEA 租户的 Finance 文件夹，则该应用程序将获得 EMEA 租户和 Finance 文件夹中资产的查看权限。

备注：

为了让开发者使用这些外部应用程序，他们必须在请求中声明某些作用域。

精细访问

根据外部应用程序已注册的权限，开发者必须声明某些作用域才能使用这些权限。可能提供以下三个选项：

1. 用于查看组织中所有计算机的特定权限，例如 OR.Machines.View。
2. 特定权限和 OR.Default 的组合，例如 OR.Machines.View + OR.Default：请求查看整个组织中的计算机，以及在特定租户和文件夹中搜索细化权限。
3. 仅限 OR.Default：在特定租户和文件夹中以专有方式请求细化权限。

使用不同的授权类型

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

要使用的授权类型：

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

备注：

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

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

The authorization server for accessing UiPath® resources is the UiPath® Identity Server, which supports the OAuth 2.0 framework.

精细访问

对于通过 Orchestrator 配置的具有精细访问权限的机密应用程序，您需要请求 OR.Default 作用域，以便应用程序在租户和文件夹级别检查在 Orchestrator 中执行的分配。然后，应用程序可以访问这些租户和文件夹中被授予访问权限的资源。

例如，您希望外部应用程序查看组织中所有租户的作业和计算机。通过利用“精细访问”功能，您还可以配置应用程序以查看一个文件夹中的队列。

要在这种情况下获取外部应用程序的访问令牌，您应该请求以下作用域：OR.Jobs.Read, OR.Machines.Read, OR.Default。这将授予您的应用程序对组织中所有租户的作业和计算机的查看权限，以及对文件夹中队列的查看权限，前提是已向其分配外部应用程序并通过角色授予所需权限。

授权代码

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

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

1. The external application sends an authorize request to the UiPath® Identity Server authorize endpoint to get the authorization code.

   https://{yourDomain}/identity_/connect/authorize?
   response_type=code&
   acr_values={value}&
   client_id={app_id}&
   scope={scopes}&
   redirect_uri={redirect_url}

   选项	描述
   https://{yourDomain}/identity_/connect/authorize	Identity Server 授权端点。
   response_type=code	指定应用程序正在请求授权代码。
   acr_values	允许 Identity Server 根据用户所属的组织应用身份验证策略。可以采用不同的值： acr_values=tenant:{target organization GlobalId} - 组织 ID 用作 ACR 值。 acr_values=tenantName:{target organization name} - 组织名称充当 ACR 值。
   client_id	必须包含应用程序 ID（显示在“外部应用程序”页面上）。
   scope	包含应用程序请求的作用域，以空格分隔；例如 OR.Machines OR.Robots。 注意：查看资源的 API 文档中的端点，以获取所需的作用域值。例如：
   redirect_uri	Contains the URL where UiPath® Identity Server redirects the authorize request after the authorization code is granted.

2. 用户必须登录到，以对授权请求进行身份验证。

   如果出现以下情况，请求将失败：

   • 用户不在已注册外部应用程序的组织中
   • 对于某些资源，已登录的用户对请求的范围没有所需要的权限。
3. 外部应用程序接收授权代码。
   示例授权请求重定向：{redirect_url}?code={authorization_code}&scope={scopes} 您只能使用一次授权代码。
4. The external application requests an access token from UiPath® Identity Server using the authorization code and authentication details (client_id and client_secret). These are included in the body of a POST request to the token endpoint https://{yourDomain}/identity_/connect/token.

   {
       "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}"
   }

现在，应用程序可以使用访问令牌来访问用户资源，直到令牌过期（一小时）。

使用 PKCE 的授权代码

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

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

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

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

https://{yourDomain}/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

在发送至 https://{yourDomain}/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 请求 https://{yourDomain}/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 "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"

注意：有关可用 API 的信息，请参阅 https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/swagger/index.html 上的 Orchestrator API Swagger。

获取刷新令牌

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

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

要请求刷新令牌，须在授权请求的 scope 参数中包含 offline_access，以便在令牌请求中使用授权代码来获取刷新令牌。

获取刷新令牌

向令牌端点发送包含授权代码的 POST 请求

https://{yourDomain}/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 授权类型向令牌端点 https://{yourDomain}/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}"
}

注意：如果外部应用程序是非机密应用程序，并且使用具有 PKCE 授权类型的授权代码，请从请求正文中删除 client_secret 参数。

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

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

UiPath® Identity Server Endpoints

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

身份服务器层	Endpoint	描述
发现	https://{yourDomain}/identity_/.well-known/openid-configuration	使用此端点检索有关 Identity Server 实例的元数据。
授权	https://{yourDomain}/identity_/connect/authorize	使用此端点通过浏览器请求令牌或授权代码。 此流程包括对最终用户的身份验证和（可选）同意。
令牌	https://{yourDomain}/identity_/connect/token	使用此端点以编程方式请求令牌。 请注意，对于此端点，内容类型必须为 application/x-www-form-urlencoded。