外部应用程序 (OAuth)

As a developer working on the integration of UiPath products with external applications, you are responsible for tasks such as managing scope changes, managing access tokens and refresh tokens and maintaining the integration between the external app and UiPath resources. The following guide walks you through these operations.

OAuth 提供了一系列库，您可以利用这些库来简化身份验证、授权、委派和保护 API 调用。您可以直接从官方 OAuth 网站访问这些资源。

先决条件

组织管理员在 UiPath 中注册了您的外部应用程序后，作为开发者，您将需要获取注册详细信息，以便使用 UiPath 资源对外部应用程序进行身份验证。

• “应用程序类型”和“应用程序 ID”。如果您使用的是机密应用程序，则还需要应用程序密码。它们用于通过 UiPath 的 Identity Server（用于访问 UiPath 资源的授权服务器，支持 OAuth 2.0 框架）对您的应用程序进行身份验证。

• 此外，您需要了解外部应用程序作用域，该作用域定义了外部应用程序可以在 UiPath 中访问哪些资源。这包括资源规范（如资产、流程等）和权限级别（读取、写入、编辑等）。

对外部应用程序进行身份验证和授权

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

在此流程中，通过向 Identity Server 提供外部应用程序的作用域和已注册应用程序的凭据（应用程序 ID，以及机密应用程序的应用程序密码）来请求访问令牌。如果凭据有效，Identity Server 将通过发出授权代码进行响应，该代码将用于生成访问令牌。

要使用的授权类型

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

备注：

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

声明作用域

管理员为应用程序定义的作用域决定了应用程序可以获得的最高访问级别。作为开发者，如果您请求的访问权限超出此预定义的作用域，您的请求将失败。因此，请务必确保您的请求在管理员定义的作用域内。

在管理员级别，应用程序的权限可以是：

• 组织范围内的权限：默认情况下，注册外部应用程序后，根据设置的作用域，该应用程序具有组织范围内对资源的访问权限。

• 精细权限：对于更精细的权限设置，组织管理员可以在 Orchestrator 中，在租户或文件夹级别将角色分配给外部应用程序，但这仅适用于机密应用程序。

在开发者级别，作用域的声明方式如下：

• 组织范围内的权限：当您在令牌请求中声明显式指定的作用域（例如 OR.Machines.View）时，这意味着应用程序正在请求组织范围内的访问权限。
• 精细权限：要为应用程序提供精细访问权限，您必须在令牌请求中声明 OR.Default。OR.Default 的作用类似于通配符作用域，为您的应用程序提供精细的访问权限，具体取决于应用程序在特定租户或文件夹中获分配的角色。

例如，假设您希望应用程序在组织范围内具有查看所有计算机的访问权限，并在定义的租户和文件夹中具有更细化的专属权限。在这种情况下，您可以将作用域声明为 OR.Machines.View 和 OR.Default。此合并声明允许您的外部应用程序既在组织范围内运行，又在特定的 Orchestrator 租户或文件夹中运行。

查看资源的 API 文档中的端点，以获取所需的作用域值。例如：

具有应用程序作用域的机密应用程序（客户端凭据流程）

具有应用程序作用域的机密应用程序根据 UiPath Identity Server 执行客户端凭据流程。

该图显示了 OAuth 客户端凭据流程。客户端将凭据发送到 Identity Server 并接收访问令牌。使用经过验证的令牌，可以访问 API 资源。

有关使用客户端凭据的 OAuth 流程的详细信息，请参阅 RFC 6749 文档。

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

1. 外部应用程序通过向 Identity Server 令牌端点发送包含 client_id 和 client_secret 的 POST 请求来请求访问令牌：https://{yourDomain}/{organizationName}/identity/connect/token：

   grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&scope={scopes}

   字段	描述
   client_id	指定在注册期间分配给应用程序的唯一标识符。 必须包含应用程序 ID（由管理员提供）。
   client_secret	指定机密应用程序在注册时提供给您的机密信息（如密码）。当向 Identity Server 发出请求时，此字段与 client_id 一起用于对应用程序进行身份验证。 必须包含应用程序密码（由管理员提供）。
   scope	指定应用程序请求的作用域，以空格分隔；例如 OR.Machines.View OR.Default。 使用 OR.Default 在特定租户或文件夹中授予受控的自定义访问权限。应用程序获得的实际权限取决于管理员将应用程序分配在哪些租户或文件夹中。 使用 OR.Machines.View 等显式作用域在组织范围内授予对某些资源的广泛访问权限。

2. 外部应用程序收到包含访问令牌的响应：

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

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

具有用户作用域的机密应用程序（授权代码流程）

对于具有用户作用域的机密外部应用程序，您可以针对 Identity Server 执行授权代码流程。

该图显示了 OAuth 授权代码流程。客户端从 Identity Server 请求授权。然后，系统会提示用户登录。成功后，Identity Server 会提供授权代码。客户端使用此代码和客户端密码来检索访问令牌。使用经过验证的令牌，即可访问 API 资源。

有关使用授权代码的 OAuth 流程的详细信息，请参阅 RFC 6749 文档。

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

1. 外部应用程序向 Identity Server 授权端点 https://{yourDomain}/{organizationName}/identity/connect/authorize? 发送一个授权请求，以获取授权代码：

   response_type=code&acr_values={value}&client_id={app_id}&scope={scopes}&redirect_uri={redirect_url}

   选项	描述
   acr_values	允许 Identity Server 根据用户所属的组织应用身份验证策略。可以采用不同的值： acr_values=tenant:{target Organization GlobalId} - 组织 ID 用作 ACR 值。 acr_values=tenantName:{target organization name} - 组织名称充当 ACR 值。
   client_id	指定在注册期间分配给应用程序的唯一标识符。 必须包含应用程序 ID（由管理员提供）。
   client_secret	指定机密应用程序在注册时提供给您的机密信息（如密码）。当向 Identity Server 发出请求时，此字段与 client_id 一起用于对应用程序进行身份验证。 必须包含应用程序密码（由管理员提供）。
   scope	指定应用程序请求的作用域，以空格分隔；例如：OR.Machines.View OR.Default。 使用“OR.Default”可在特定租户或文件夹中授予受控的自定义访问权限。应用程序获得的权限取决于管理员将应用程序分配在哪些租户或文件夹。 使用 OR.Machines.View 等显式作用域在组织范围内授予对某些资源的广泛访问权限。
   redirect_uri	指定 Identity Server 在授予授权代码后重定向授权请求时使用的 URL。

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

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

   • 用户不在已注册外部应用程序的组织中
   • 对于某些资源，已登录的用户对请求的范围没有所需要的权限。
3. 外部应用程序接收授权代码。 您只能使用一次授权代码。
   示例授权请求重定向：{redirect_url}?code={authorization_code}&scope={scopes}
4. 外部应用程序使用授权代码和身份验证详细信息（client_id 和 client_secret）从 UiPath™ Identity Server 请求访问令牌。这些请求包含在对令牌端点 https://{yourDomain}/{organizationName}/identity/connect/token 的 POST 请求的正文中。

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

5. 外部应用程序收到包含访问令牌的响应，例如：

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

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

具有用户作用域的非机密应用程序（具有 PKCE 流程的授权代码）

对于具有用户作用域的非机密应用程序，您可以使用 PKCE 流程执行授权代码。有关使用包含 PKCE 的授权代码的 OAuth 流程的详细信息，请参阅 RFC 7636 文档。

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

1. 外部应用程序向 https://{yourDomain}/{organizationName}/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

   选项	描述
   client_id	指定在注册期间分配给应用程序的唯一标识符。 必须包含应用程序 ID（由管理员提供）。
   scope	指定应用程序请求的作用域，以空格分隔；例如 OR.Machines.View。
   redirect_uri	指定 UiPath Identity Server 在授予授权代码后重定向授权请求时使用的 URL。
   code_challenge_method	指定用于对 code_challenge 的 code_verifier 进行编码的方法。此字段的值必须为 S256，这意味着应使用 SHA256 散列code_verifier 和 base64url 编码，以创建 code_challenge。
   code_challenge	从 code_verifier 派生的加密随机字符串，用于将授权请求连接到令牌请求。 您必须使用代码验证程序算法来生成代码质询。您也可以创建自己的算法，但前提是它必须符合 rfc7636 标准。

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

   grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&code_verifier={code_verifier}

   响应包括访问令牌，应用程序可使用该访问令牌来访问用户资源，直到令牌过期（一小时）。

使用访问令牌

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

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

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

获取刷新令牌

访问令牌将在一小时后过期。外部应用程序可以通过交换刷新令牌来获取新的访问令牌，而无需用户交互。机密和非机密外部应用程序都可以请求刷新令牌。但是，客户端凭据流程不支持刷新令牌。在客户端凭据流程中，直接授予访问令牌，而无需刷新令牌。当客户端需要新令牌时，必须使用其凭据重新进行身份验证。

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

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

获取刷新令牌

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

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

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

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