外部客户端 — 联合凭据

联合凭据使 OAuth 外部应用程序使用外部身份提供程序颁发的 JSON 网页令牌 (JWT) 对 UiPath 进行身份验证，而无需客户端密码。每个应用程序最多支持 20 个联合凭据。

使用此页面上的端点列出、创建、检索、更新和删除已注册的 OAuth 外部应用程序的联合凭据。要管理外部应用程序本身，请参阅管理外部 OAuth 应用程序。

将所有端点路径中的{accessURL}替换为您的云平台的基本 URL：

Cloud Platform	访问 URL
Test Cloud	https://cloud.uipath.com/
Test Cloud 公共部门版	https://govcloud.uipath.us/
Test Cloud 专用版	https://{customURL}.dedicated.uipath.com/

---

列出联合凭据

检索为特定 OAuth 外部应用程序注册的所有联合凭据。

API 端点

GET {accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials

路径参数

参数	描述
partitionGlobalId	组织全局 ID。
clientId	OAuth 外部应用程序的 ID。

作用域

需要以下任一作用域：

• PM.OAuthApp
• PM.OAuthApp.Read（用于 GET 请求）

请求标头

--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'

备注：

要获取{access_token} ，请使用组织管理员令牌或通过身份验证方法中描述的其中一种方法进行身份验证。

响应

200 OK

返回FedassistedCredentialDto对象的数组。如果未注册任何凭据，则返回空数组。

请求示例

curl --request GET \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials' \
  --header 'Authorization: Bearer {access_token}'

响应示例

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
    "name": "GitHub Actions",
    "description": "Used for GitHub Actions CI/CD pipeline",
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "https://cloud.uipath.com/myorg",
    "subject": "repo:myorg/myrepo:ref:refs/heads/main",
    "createdAt": "2026-03-01T10:00:00Z",
    "updatedAt": "2026-03-01T10:00:00Z"
  }
]

---

创建联合凭据

为特定的 OAuth 外部应用程序创建联合身份凭据。

备注：

每个应用程序最多支持 20 个联合凭据。

API 端点

POST {accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials

路径参数

参数	描述
partitionGlobalId	组织全局 ID。
clientId	OAuth 外部应用程序的 ID。

作用域

需要以下任一作用域：

• PM.OAuthApp
• PM.OAuthApp.Write（用于 PUT 请求）

请求标头

--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'

请求正文

{
  "name": "azure-production-workload",
  "description": "Federated credential for production Azure workload",
  "issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0",
  "audience": "api://uipath-production",
  "subject": "00000000-0000-0000-0000-000000000000"
}

字段	必填	描述
name	是	凭据的描述性名称。在应用程序中必须是唯一的。最多 128 个字符。
description	否	凭据的可选上下文。最多 512 个字符。
issuer	是	外部身份提供程序的 HTTPS URI。在创建时必须可访问。
audience	是	必须出现在 JWT aud声明中的单个字符串。
subject	是	一个必须与 JWT sub声明完全匹配的值。

响应

201 已创建

返回创建的“FederationCredentialDto”对象。

400 Bad Request

请求无效。可能的原因： name在客户端中不是唯一的， issuer不是有效的 HTTPS URI，颁发者的 JWKS 端点无法访问或已达到每个应用程序 20 个凭据的上限。

404 未找到

指定的clientId不存在或不属于调用者所在的组织。

请求示例

curl --request POST \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "GitHub Actions",
    "description": "Used for GitHub Actions CI/CD pipeline",
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "https://cloud.uipath.com/myorg",
    "subject": "repo:myorg/myrepo:ref:refs/heads/main"
  }'

响应示例

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
  "name": "GitHub Actions",
  "description": "Used for GitHub Actions CI/CD pipeline",
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://cloud.uipath.com/myorg",
  "subject": "repo:myorg/myrepo:ref:refs/heads/main",
  "createdAt": "2026-03-01T10:00:00Z",
  "updatedAt": "2026-03-01T10:00:00Z"
}

---

获取联合凭据

按 ID 检索特定的联合凭据。

API 端点

GET {accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}

路径参数

参数	描述
partitionGlobalId	组织全局 ID。
clientId	OAuth 外部应用程序的 ID。
credentialId	联合凭据的 ID。

作用域

需要以下任一作用域：

• PM.OAuthApp
• PM.OAuthApp.Read（用于 GET 请求）

请求标头

--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'

响应

200 OK

返回所请求凭据的Fed托管凭据 Dto 对象。

404 未找到

调用者的组织中不存在指定的凭据或应用程序。

请求示例

curl --request GET \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}' \
  --header 'Authorization: Bearer {access_token}'

响应示例

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
  "name": "GitHub Actions",
  "description": "Used for GitHub Actions CI/CD pipeline",
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://cloud.uipath.com/myorg",
  "subject": "repo:myorg/myrepo:ref:refs/heads/main",
  "createdAt": "2026-03-01T10:00:00Z",
  "updatedAt": "2026-03-15T08:30:00Z"
}

---

更新联合凭据

更新现有联合联合凭据。请求正文中必须包含所有必填字段。

API 端点

PUT {accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}

路径参数

参数	描述
partitionGlobalId	组织全局 ID。
clientId	OAuth 外部应用程序的 ID。
credentialId	要更新的联合凭据的 ID。

作用域

需要以下任一作用域：

• PM.OAuthApp
• PM.OAuthApp.Write（用于 PUT 请求）

请求标头

--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'

请求正文

{
  "name": "azure-production-workload-updated",
  "description": "Updated description",
  "issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0",
  "audience": "api://uipath-production",
  "subject": "00000000-0000-0000-0000-000000000000"
}

字段	必填	描述
name	是	凭据的描述性名称。在应用程序中必须是唯一的。最多 128 个字符。
description	否	凭据的可选上下文。最多 512 个字符。
issuer	是	外部身份提供程序的 HTTPS URI。在创建时必须可访问。
audience	是	必须出现在 JWT aud声明中的单个字符串。
subject	是	一个必须与 JWT sub声明完全匹配的值。

响应

200 OK

返回更新的FedExedential Credential Dto对象。

400 Bad Request

验证失败。可能的原因：重复的name 、颁发者 URI 无效或无法访问的 JWKS 端点。

请求示例

curl --request PUT \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "GitHub Actions — Production",
    "description": "Production branch deployments only",
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "https://cloud.uipath.com/myorg",
    "subject": "repo:myorg/myrepo:ref:refs/heads/main"
  }'

响应示例

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
  "name": "GitHub Actions — Production",
  "description": "Production branch deployments only",
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://cloud.uipath.com/myorg",
  "subject": "repo:myorg/myrepo:ref:refs/heads/main",
  "createdAt": "2026-03-01T10:00:00Z",
  "updatedAt": "2026-03-20T14:00:00Z"
}

---

删除联合凭据

删除联合凭据。此操作是永久性的，并且会立即使使用此凭据获取的任何令牌失效。

警告：

此操作是永久删除。删除后，凭据不能再用于获取新的访问令牌。删除前已颁发的访问令牌在过期前一直有效。

API 端点

DELETE {accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}

路径参数

参数	描述
partitionGlobalId	组织全局 ID。
clientId	OAuth 外部应用程序的 ID。
credentialId	要删除的联合凭据的 ID。

作用域

需要以下任一作用域：

• PM.OAuthApp
• PM.OAuthApp.Write（用于 PUT 请求）

请求标头

--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'

响应

204 无内容

已成功删除联合凭据。响应正文为空。

404 未找到

调用者的组织中不存在指定的凭据或应用程序。

请求示例

curl --request DELETE \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}' \
  --header 'Authorization: Bearer {access_token}'

---

使用联合凭据获取令牌

将外部身份提供程序提供的 JWT 交换为 UiPath 访问令牌。

API 端点

POST {accessURL}/identity_/connect/token

请求标头

--header 'Content-Type: application/x-www-form-urlencoded'

请求正文

grant_type=client_credentials
&client_id={client_id}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={jwt_token}
&scope={requested_scopes}

参数	描述
grant_type	必须是client_credentials 。
client_id	已注册的 OAuth 外部应用程序的客户端 ID。
client_assertion_type	必须是urn:ietf:params:oauth:client-assertion-type:jwt-bearer 。
client_assertion	由外部身份提供程序颁发的 JWT。
scope	为访问令牌请求的 OAuth 作用域。

响应

200 OK

返回访问令牌对象。在后续 API 调用的Authorization: Bearer标头中使用access_token值。

400 Bad Request

令牌获取失败。可能的原因：JWT 签名无效、颁发者或受众不匹配、主题不匹配、JWT 过期或 JWT 超过 8 KB。

---

架构

联合凭据 DTO

GET、POST 和 PUT 操作返回的对象。

属性	类型	可空	描述
id	字符串 (uuid)	否	联合凭据的唯一标识符。
clientId	字符串	是	此凭据所属的 OAuth 外部应用程序的应用程序 ID。
name	字符串	是	联合凭据的显示名称。
description	字符串	是	联合凭据的描述。
issuer	字符串	是	外部身份提供程序的 URL。
audience	字符串	是	JWT 中预期的aud声明值。
subject	字符串	是	JWT 中预期的sub声明值。
createdAt	字符串（日期时间）	否	创建凭据时的 UTC 时间戳。
updatedAt	字符串（日期时间）	否	上次更新凭据时的 UTC 时间戳。