订阅

UiPath Automation Cloud™

UiPath Automation Cloud™ 指南

有关 Automation Cloud 和我们的云服务当前状态的信息,请参阅“状态”页面。

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

这些说明适用于维护 UiPath 产品与外部应用程序之间集成的开发者。

👍

要求

Before you begin:

  • 必须先由组织管理员在 Automation Cloud 中注册外部应用程序。
  • 向组织管理员获取注册详细信息

 

使用不同的授权类型


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

Which authorization grant type to use:

Application TypeScopeRequired Grant Type
confidentialuserAuthorization code (instructions)
confidentialapplicationClient credentials (instructions)
non-confidentialuserAuthorization code with PKCE (instructions)

📘

备注:

如果同时向用户和应用程序作用域授予了一个机密应用程序,则您必须同时实现这两种授予类型。
当用户和应用程序作用域内的作用域名称相同时(如在 Orchestrator 中),您使用的授予类型将决定是在用户作用域还是应用程序作用域下调用资源。

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

精细访问

For confidential applications with fine-grained access configured via Orchestrator, you need to request the OR.Default scope, which allows the application to check for assignments made in Orchestrator, at the tenant and folder levels. The application can then access the resources it's been granted access to in those tenants and folders.

For example, you want an external application to view jobs and machines across all tenants in the organization. By leveraging the fine-grained access functionality, you can also configure the application to view queues in one folder.

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

授权代码

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

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

  1. 外部应用程序向 UiPath Identity Server 授权端点发送授权请求,以获取授权代码。
https://cloud.uipath.com/identity_/connect/authorize?
response_type=code&
client_id={app_id}&
scope={scopes}&
redirect_uri={redirect_url}
  • https://cloud.uipath.com/connect/authorize 是 Identity Server 授权端点。
  • response_type=code 指定应用程序正在请求授权代码。
  • client_id 必须包含应用程序 ID(显示在“外部应用程序”页面上)。
  • scope:包含应用程序请求的作用域,以空格分隔;例如 OR.Machines OR.Robots
    Check the endpoint in the API documentation of the resource to get the scope values you need. For example:
14331433
  • redirect_uri 包含 UiPath Identity Server 在授予授权代码后重定向授权请求时使用的 URL。
  1. 用户必须登录到 Automation Cloud,以对授权请求进行身份验证。
    如果出现以下情况,请求将失败:

    • 用户不在已注册外部应用程序的组织中
    • 对于某些资源,已登录的用户对请求的范围没有所需要的权限。
  2. 外部应用程序接收授权代码。
    示例授权请求重定向:{redirect_url}?code={authorization_code}&scope={scopes}
    您只能使用一次授权代码。

  3. 外部应用程序使用授权代码和身份验证详细信息(client_idclient_secret)从 UiPath Identity Server 请求访问令牌。这些请求包含在对令牌端点 https://cloud.uipath.com/identity_/connect/token 的 POST 请求的正文中。
    如果您使用的是 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}"
}

📘

备注:

在 Automation Cloud 中注册机密应用程序后,系统将返回 client_secret
对于非机密应用程序,请使用 code_challengecode_challenge_method,而不是client_secret

  1. 外部应用程序收到包含访问令牌的响应,例如:
{
    "access_token":"{access_token}",
    "expires_in":3600,
    "token_type":"Bearer",
    "scope":"{scopes}"
}

Now the application can use the access token to access user resources until the token expires (one hour). See Using the Access Token and Obtaining a Refresh Token for more information.

使用 PCKE 的授权代码

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

The flow is the same as when using authorization code, except in the authorize request you need to include the following request query parameters:

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

You must use a code verifier algorithm to generate the code challenge. You can also create your own, as long as it complies with the rfc7636 standard.

https://cloud.uipath.com/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://cloud.uipath.com/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}" 
}

The response includes an access token which the application can use to access user resources until the token expires (one hour). See Using the Access Token and Obtaining a Refresh Token for more information.

客户端凭据

为了让机密应用程序访问应用程序作用域,外部应用程序会向 Identity Server 令牌端点发送包含 client_idclient_secret 的 POST 请求 https://cloud.uipath.com/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://cloud.uipath.com/{org_name}/{tenant_name}/orchestrator_/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"l

See the Orchestrator API Swagger at https://cloud.uipath.com/{org_name}/{tenant_name}/orchestrator_/swagger/index.htm for information about the available APIs.

 

获取刷新令牌


访问令牌将在一小时后过期。外部应用程序可以通过交换刷新令牌来获取新的访问令牌,而无需用户交互。 机密和非机密外部应用程序都可以请求刷新令牌。
刷新令牌也仅能使用一次,并且会在 60 天后过期。

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

获取刷新令牌

向令牌端点发送包含授权代码的 POST 请求
https://cloud.uipath.com/identity_/connect/token
If you are using Postman or a similar tool, use the content type 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://cloud.uipath.com/identity_/connect/token 发送 POST 请求。
If you are using Postman or a similar tool, use the content type 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。如果您以编程方式发出请求,则不需要这样做。

发现:
https://cloud.uipath.com/identity_/.well-known/openid-configuration

Authorization
https://cloud.uipath.com/identity_/connect/authorize

令牌:
https://cloud.uipath.com/identity_/connect/token

14 天前更新


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


建议的编辑仅限用于 API 参考页面

您只能建议对 Markdown 正文内容进行编辑,而不能建议对 API 规范进行编辑。