配置具有OAuth 2.0授权码授予的外部应用程序

外部应用程序为管理员提供了一种从Foundry中构建的工作流管理与外部系统的OAuth 2.0连接的方法。外部应用程序在Control Panel的组织级别进行管理。

外部应用程序表示Foundry作为OAuth 2.0 客户端所需的一组配置。该应用程序向可以作为OAuth 2.0 服务器的另一个系统发出请求。

Foundry中的外部应用程序仅支持OAuth 2.0授权码授予 ↗类型。 要设置OAuth 2.0客户端凭据授予，请遵循这些资源，在webhook中手动建立握手过程。

创建外部应用程序

要创建外部应用程序，首先导航到Control Panel中的外部应用程序，位于组织设置下。如果您有多个组织的访问权限，请确保选择您希望创建外部应用程序的组织。该组织中具有设置数据连接源权限的所有用户都可以选择任何外部应用程序作为他们连接的授权机制。

要查看外部应用程序页面，您需要访问“管理外部应用程序”工作流，该工作流默认授予Control Panel中的组织管理员角色。

了解更多关于配置角色的信息。

选择新应用程序并提供所需的输入以设置您的外部应用程序。详细的配置选项如下所示。

配置选项

以下配置选项适用于基于云和本地的OAuth 2.0服务器。

直接云连接的配置选项

如果OAuth 2.0服务器可以通过互联网访问，我们建议在设置外部连接时使用直接连接。

本地OAuth服务器的配置选项

本地配置应仅在OAuth服务器位于私有网络内部且无法通过直接互联网连接访问时使用。

连接到私有网络内的OAuth 2.0服务器

由于某些OAuth 2.0服务器未暴露于开放互联网，OAuth 2.0握手请求必须通过使用代理工作程序运行时连接到服务器的自定义REST API源进行路由。此方法要求您编写自己的请求，这些请求将用于执行OAuth 2.0握手。

第一步是创建一个可以连接到您的OAuth2服务器的REST API源。例如，您可以配置您的源域和客户端密钥：

接下来，您需要在该REST API源上创建一个可以调用OAuth 2.0服务器的/token端点的webhook。您可以选择性地创建第二个webhook来刷新令牌。

下面的示例显示了使用cURL向假想的OAuth 2.0服务器发出OAuth 2.0握手请求的示例：

Copied!
1
2
3
4
5
curl -XPOST 'https://<oauth-server>/token'  # 发送POST请求到OAuth服务器获取令牌
    -H 'Content-Type: application/json'    # 设置请求头为JSON格式
    -d '{"client_id":"8b3df622e71449519cd9b0160b9e39f7", \  # 客户端ID
         "client_secret":"04011f337b984df0ad8c58a50f9e91f5", \  # 客户端密钥
         "code":"a8ec5e83728e480fa6bfda4eb8e122a3"}'  # 授权码，用于获取访问令牌

注意：实际应用中，请确保在公开场合或生产环境中避免直接暴露client_secret和code等敏感信息。 一个示例响应可能如下所示：

Copied!
1
2
3
4
5
6
7
{
  "access_token": "1846149cf5774c3d8eaeb18b75f7178d",  // 访问令牌，用于访问受保护的资源
  "refresh_token": "1846149cf5774c3d8eaeb18b75f7178d", // 刷新令牌，用于获取新的访问令牌
  "token_type": "bearer",  // 令牌类型，通常为bearer
  "scope": "<comma-delimited-set-of-scopes>", // 访问范围，多个范围用逗号分隔
  "expires_in": "3600" // 令牌的有效期，单位为秒
}

作为另一个例子，一个典型的刷新请求可能如下所示：

Copied!
1
2
3
4
5
curl -XPOST 'https://<oauth-server>/refresh_token'
    -H 'Content-Type: application/json'
    -d '{"client_id":"8b3df622e71449519cd9b0160b9e39f7", \
         "client_secret":"04011f337b984df0ad8c58a50f9e91f5", \
         "refresh_token":"a8ec5e83728e480fa6bfda4eb8e122a3"}'

• 这个命令使用 curl 工具发送一个 HTTP POST 请求到 OAuth 服务器的 /refresh_token 端点。
• 请求头包含 Content-Type: application/json，表明请求体的数据格式为 JSON。
• 请求体包含以下字段：
  • client_id: 客户端标识符，用于标识请求的客户端。
  • client_secret: 客户端密钥，用于验证客户端的身份。
  • refresh_token: 用于获取新的访问令牌的刷新令牌。 以上响应与握手响应相同：

Copied!
1
2
3
4
5
6
7
{
  "access_token": "1846149cf5774c3d8eaeb18b75f7178d",
  "refresh_token": "1846149cf5774c3d8eaeb18b75f7178d",
  "token_type": "bearer", // 令牌类型为bearer
  "scope": "session",     // 令牌的作用域为session
  "expires_in": "3600"    // 令牌的有效期为3600秒（1小时）
}

使用下节中的说明创建您需要的词元和刷新词元 webhook，以在 Foundry 中实现 OAuth 2.0 握手。

词元 webhook

词元 webhook 应实现对 OAuth 2.0 服务器上的 /token 端点的请求，以获取给定 client_id、redirect_uri 和 authorization_code 的有效词元。词元 webhook 必须具有以下列出的输入和输出参数。了解更多关于webhook 参数的信息。

下面是一个标准 OAuth 2.0 服务器词元请求的请求配置示例：

您还必须在 webhook 表单主体中设置 grant_type=authorization_code 作为其中一项。查看您的 OAuth 2.0 服务器文档以了解其他所需的配置。

刷新词元 webhook

在创建词元 webhook 之后，您必须使用下列输入和输出参数创建第二个用于刷新词元流程的 webhook。webhook 应实现对 /token 端点的请求，以获取给定 refresh_token 和 client_id 的新词元。

下面是一个标准 OAuth 2.0 服务器刷新请求的请求配置示例：

您还必须在 webhook 表单主体中设置 grant_type=refresh_token 作为其中一项。查看您的 OAuth 2.0 服务器文档以了解其他所需的配置。

可用的输出参数与词元 webhook的参数相同。

管理外部应用程序

一旦创建了外部应用程序，该应用程序将可供该组织中的所有用户用作REST API 源在数据连接中的授权方法。以下选项可供有权限管理外部应用程序的管理员使用。

删除外部应用程序

删除外部应用程序将永久删除所有已授权该应用程序的用户的存储词元和刷新词元。应用程序配置，包括客户端密钥，也将被永久删除。此操作无法撤销。

重置外部应用程序

重置外部应用程序将永久删除所有已授权该应用程序的用户的存储词元和刷新词元。这会使应用程序返回到初始设置后的状态，此时还没有用户完成交互式授权流程。下次用户尝试执行需要此外部应用程序词元的工作流时，他们将被提示再次完成授权流程。

启用外部应用程序

启用外部应用程序意味着用户可以对该外部系统执行交互式授权流程。禁用应用程序将阻止使用任何先前存储的词元和刷新词元。然而，这些词元不会被删除，并且在应用程序重新启用后可以再次使用。

之前未授权该应用程序的新用户在外部应用程序被禁用时将无法执行交互式授权流程。

新创建的应用程序将默认启用，且只能在创建后被禁用。

在数据连接中使用外部应用程序

一旦创建并启用外部应用程序，它可以用作REST API 源中域的身份验证方法。在配置域时，选择 OAuth 2.0，然后从下拉菜单中选择所需的外部应用程序。

任何使用配置了 OAuth 2.0 域的 webhook 都将在用户首次尝试运行时显示交互提示。Webhook 通常通过操作从工作坊调用；在这种情况下，当在工作坊中运行一个操作时，用户将看到一个弹出窗口，显示 OAuth 2.0 服务器的身份验证页面，提示他们授权 Foundry 代表他们与该系统交互。

如果配置了词元刷新工作流，除非外部系统中的授权被撤销或外部应用程序被重置，用户不太可能再次看到此提示。如果未配置刷新工作流，最终用户将在词元过期时看到身份验证弹出窗口。词元通常在几分钟或几小时内过期，我们鼓励使用刷新流程以获得更好的用户体验。