外部应用程序 (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 文件夹中资产的查看权限。
为了让开发者使用这些外部应用程序,他们必须在请求中声明某些作用域。
根据外部应用程序已注册的权限,开发者必须声明某些作用域才能使用这些权限。可能提供以下三个选项:
-
用于查看组织中所有计算机的特定权限,例如
OR.Machines.View
。 -
特定权限和
OR.Default
的组合,例如OR.Machines.View
+OR.Default
:请求查看整个组织中的计算机,以及在特定租户和文件夹中搜索细化权限。 -
仅限
OR.Default
:在特定租户和文件夹中以专有方式请求细化权限。
在注册外部应用程序后,您必须为外部应用程序实施适当的授权机制,并为允许的作用域提供适当的授权类型,以便外部应用程序可以检索访问令牌。
要使用的授权类型:
应用程序类型 |
范围 |
要求的授权类型 |
---|---|---|
机密 |
用户 |
授权代码 |
机密 |
应用程序 |
客户端凭据 |
非机密 |
用户 |
使用 PKCE 的授权代码 |
如果同时向用户和应用程序作用域授予了一个机密应用程序,则您必须同时实现这两种授予类型。
当用户和应用程序作用域内的作用域名称相同时(如在 Orchestrator 中),您使用的授予类型将决定是在用户作用域还是应用程序作用域下调用资源。
The authorization server for accessing UiPath® resources is the UiPath® Identity Server, which supports the OAuth 2.0 framework.
OR.Default
作用域,以便应用程序在租户和文件夹级别检查在 Orchestrator 中执行的分配。然后,应用程序可以访问这些租户和文件夹中被授予访问权限的资源。
例如,您希望外部应用程序查看组织中所有租户的作业和计算机。通过利用“精细访问”功能,您还可以配置应用程序以查看一个文件夹中的队列。
OR.Jobs.Read, OR.Machines.Read, OR.Default
。这将授予您的应用程序对组织中所有租户的作业和计算机的查看权限,以及对文件夹中队列的查看权限,前提是已向其分配外部应用程序并通过角色授予所需权限。
如果注册的应用程序是非机密类型且请求是针对用户作用域,则请使用此授权类型。
流程与使用授权代码时相同,不同之处为在授权请求中,您需要加入以下请求查询参数:
-
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/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
的原始字符串)。
application/x-www-form-urlencoded
。
{
"grant_type": "authorization_code",
"code": "{authorization_code}",
"redirect_uri": "{redirect_url}",
"client_id": "{app_id}",
"code_verifier": "{code_verifier}"
}
{
"grant_type": "authorization_code",
"code": "{authorization_code}",
"redirect_uri": "{redirect_url}",
"client_id": "{app_id}",
"code_verifier": "{code_verifier}"
}
响应包括访问令牌,应用程序可使用该访问令牌来访问用户资源,直到令牌过期(一小时)。有关更多信息,请参见使用访问令牌和获取刷新令牌。
client_id
和 client_secret
的 POST 请求
https://{yourDomain}/identity_/connect/token
,以请求访问令牌。
application/x-www-form-urlencoded
。
{
"grant_type": "client_credentials",
"client_id": "{app_id}",
"client_secret": "{app_secret}",
"scope": "{scopes}"
}
{
"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"
curl -X GET "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"
https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/swagger/index.html
上的 Orchestrator API Swagger。
访问令牌将在一小时后过期。外部应用程序可以通过交换刷新令牌来获取新的访问令牌,而无需用户交互。 机密和非机密外部应用程序都可以请求刷新令牌。
刷新令牌也仅能使用一次,并且会在 60 天后过期。
scope
参数中包含 offline_access
,以便在令牌请求中使用授权代码来获取刷新令牌。
向令牌端点发送包含授权代码的 POST 请求
https://{yourDomain}/identity_/connect/token
。
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"
}
{
"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 请求。
application/x-www-form-urlencoded
。
{
"grant_type": "refresh_token",
"client_id": "{app_id}",
"client_secret": "{app_secret}",
"refresh_token": "{existing_refresh_token}"
}
{
"grant_type": "refresh_token",
"client_id": "{app_id}",
"client_secret": "{app_secret}",
"refresh_token": "{existing_refresh_token}"
}
client_secret
参数。
该响应将返回一个新的访问令牌和一个新的刷新令牌。
现有刷新令牌在使用后不再有效,因此请确保使用收到的新刷新令牌。
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 。
|