- 入门指南
- 身份验证
- 作用域和权限
- 平台管理 API
Automation Suite API 指南
外部应用程序 (OAuth)
作为致力于将 UiPath 产品与外部应用程序集成的开发者,您负责执行诸如管理作用域更改、管理访问令牌和刷新令牌以及维护外部应用程序和 UiPath 资源之间的集成等的任务。以下指南将引导您完成这些操作。
OAuth 提供了一系列库,您可以利用这些库来简化身份验证、授权、委派和保护 API 调用。您可以直接从官方 OAuth 网站访问这些资源。
在注册外部应用程序后,您必须为外部应用程序实施适当的授权机制,并提供适当的授权类型,以便外部应用程序可以检索访问令牌。
在此流程中,通过向 Identity Server 提供外部应用程序的作用域和已注册应用程序的凭据(应用程序 ID,以及机密应用程序的应用程序密码)来请求访问令牌。如果凭据有效,Identity Server 将通过发出授权代码进行响应,该代码将用于生成访问令牌。
应用程序类型 |
范围 |
要求的授权类型 |
---|---|---|
机密 |
应用程序 |
客户端凭据 |
机密 |
用户 |
授权代码 |
机密 |
应用程序和用户 |
客户端凭据和授权代码 |
非机密 |
用户 |
使用 PKCE 的授权代码 |
当用户和应用程序作用域内的作用域名称相同时(如在 Orchestrator 中),您使用的授予类型将决定是在用户作用域还是应用程序作用域下调用资源。
管理员为应用程序定义的作用域决定了应用程序可以获得的最高访问级别。作为开发者,如果您请求的访问权限超出此预定义的作用域,您的请求将失败。因此,请务必确保您的请求在管理员定义的作用域内。
在管理员级别,应用程序的权限可以是:
-
组织范围内的权限:默认情况下,注册外部应用程序后,根据设置的作用域,该应用程序具有组织范围内对资源的访问权限。
-
精细权限:对于更精细的权限设置,组织管理员可以在 Orchestrator 中,在租户或文件夹级别将角色分配给外部应用程序,但这仅适用于机密应用程序。
在开发者级别,作用域的声明方式如下:
-
组织范围内的权限:当您在令牌请求中声明显式指定的作用域(例如
OR.Machines.View
)时,这意味着应用程序正在请求组织范围内的访问权限。 -
精细权限:要为应用程序提供精细访问权限,您必须在令牌请求中声明
OR.Default
。OR.Default
的作用类似于通配符作用域,为您的应用程序提供精细的访问权限,具体取决于应用程序在特定租户或文件夹中获分配的角色。
OR.Machines.View
和 OR.Default
。此合并声明允许您的外部应用程序既在组织范围内运行,又在特定的 Orchestrator 租户或文件夹中运行。
查看资源的 API 文档中的端点,以获取所需的作用域值。例如:
使用此授予类型的流程如下所示:
-
外部应用程序通过向 Identity Server 令牌端点发送包含
client_id
和client_secret
的 POST 请求来请求访问令牌:
:https://{yourDomain}/identity_
/connect/tokengrant_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}字段
描述
client_id
指定在注册期间分配给应用程序的唯一标识符。
必须包含应用程序 ID(由管理员提供)。
client_secret
指定机密应用程序在注册时提供给您的机密信息(如密码)。当向 Identity Server 发出请求时,此字段与client_id
一起用于对应用程序进行身份验证。必须包含应用程序密码(由管理员提供)。
scope
指定应用程序请求的作用域,以空格分隔;例如OR.Machines.View OR.Default
。-
使用
OR.Default
在特定租户或文件夹中授予受控的自定义访问权限。应用程序获得的实际权限取决于管理员将应用程序分配在哪些租户或文件夹中。 -
使用
OR.Machines.View
等显式作用域在组织范围内授予对某些资源的广泛访问权限。
-
-
外部应用程序收到包含访问令牌的响应:应用程序现在可以使用访问令牌来访问用户资源,直到令牌过期(一小时)。
{ "access_token":"{access_token}", "expires_in":3600, "token_type":"Bearer", "scope":"{scopes}" }
{ "access_token":"{access_token}", "expires_in":3600, "token_type":"Bearer", "scope":"{scopes}" }
有关使用授权代码的 OAuth 流程的详细信息,请参阅 RFC 6749 文档。
application/x-www-form-urlencoded
应用程序现在可以使用访问令牌来访问用户资源,直到令牌过期(一小时)。
对于具有用户作用域的非机密应用程序,您可以使用 PKCE 流程执行授权代码。有关使用包含 PKCE 的授权代码的 OAuth 流程的详细信息,请参阅 RFC 7636 文档。
使用此授予类型的流程如下所示:
-
外部应用程序向
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
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 标准。
-
在发送至
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}
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}/{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"
访问令牌将在一小时后过期。外部应用程序可以通过交换刷新令牌来获取新的访问令牌,而无需用户交互。机密和非机密外部应用程序都可以请求刷新令牌。但是,客户端凭据流程不支持刷新令牌。在客户端凭据流程中,直接授予访问令牌,而无需刷新令牌。当客户端需要新令牌时,必须使用其凭据重新进行身份验证。
刷新令牌也仅能使用一次,并且会在 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 。
|