如何配置 Salesforce 集成

[lindsey (Lindsey Fogle)]

本指南介绍了使用 Discourse Salesforce 插件将 Discourse 连接到 Salesforce 所需的配置步骤。

Discourse Salesforce 仅在 Enterprise（企业）套餐中提供。

所需用户级别：管理员

步骤 0：确定组织中合适的人员

在 Discourse 中执行任何操作之前，首先确保您知道组织中应涉及哪些合适的人员，以便处理 Salesforce 端所需的操作。

Salesforce 管理员

他们是谁： 在大多数组织中，这通常是您的团队称为“Salesforce 管理员”的人——负责管理您 Salesforce 组织配置的人，不一定是您的 IT 系统管理员。

他们做什么： 负责在 Salesforce 端进行初始设置，包括在 Salesforce Setup（设置）中创建外部客户端应用（External Client App）或连接的应用（Connected App），配置 OAuth 设置，并获取 Consumer Key（客户端密钥）和 Consumer Secret（客户端密码）。

他们需要什么： 需要访问 Salesforce Setup（设置），特别是 External Client App Manager（外部客户端应用管理器）。在 Salesforce 中，这需要 Customize Application（自定义应用） 系统权限。此权限包含在标准的 System Administrator（系统管理员） 配置文件中。如果执行设置的人员没有系统管理员配置文件，Salesforce 管理员需要授予他们一个包含“Customize Application（自定义应用）”的权限集。

Salesforce 集成用户

他们是谁： 其账户凭据被 Discourse 插件用于向 Salesforce 发起 API 调用的一名 Salesforce 用户。

他们做什么： 提供用户名，该用户名填入 Discourse Salesforce 设置中的 salesforce username（Salesforce 用户名） 设置中，以便促进从 Discourse 到 Salesforce 的所有 API 调用。

他们需要什么： 此用户必须拥有：

权限	需要原因
API Enabled（启用 API）	任何 Salesforce API 访问所需的权限
Lead（潜在客户）的创建、读取、编辑权限	从 Discourse 用户创建并关联潜在客户
Contact（联系人）的创建、读取、编辑权限	从 Discourse 用户创建并关联联系人
Case（案例）的创建、读取、编辑权限	从 Discourse 主题创建案例
Case Comment（案例评论）的创建权限	将主题回复同步为案例评论
FeedItem（动态）（Chatter）的创建权限	将主题活动发布到 Chatter

注意：Salesforce 集成用户可以是与 Salesforce 管理员相同的同一人。但是，出于安全最佳实践，我们建议使用单独的、权限范围更窄的账户作为集成用户。

步骤 1：生成证书和私钥

角色： Discourse 管理员

Discourse Salesforce 使用 JWT Bearer 流程与 Salesforce 进行身份验证。这需要一对 RSA 密钥：一个公共证书，Salesforce 用它来验证插件的身份；以及一个私钥，Discourse 用它来签署其请求。

1. 按照这些说明生成密钥对：
   • server.crt - 一个公共证书，证明 Discourse 是授权的应用
   • server.key - 一个私钥，用于签署 Discourse 向 Salesforce 发出的 API 请求
2. 将 server.crt 文件发送给您的 Salesforce 管理员，以便他们在步骤 3 中上传该文件。
3. 保留 server.key，以便在步骤 5 中粘贴到 Discourse Salesforce 设置中。

步骤 2：在 Salesforce 中创建外部客户端应用

角色： Salesforce 管理员

1. 登录 Salesforce。

2. 点击右上角的 齿轮图标 ()，然后选择 Setup（设置）。

   

3. 在快速查找框中，搜索 External Client App Manager（外部客户端应用管理器） 并选择它。

   

4. 点击 New External Client App（新建外部客户端应用）。

   

注意： 这些步骤使用 Salesforce Spring '25 中引入的 External Client App Manager（外部客户端应用管理器）。如果您的组织使用的是较旧的版本，界面可能显示为 App Manager（应用管理器） 或 Connected Apps（连接的应用）——底层设置是相同的。

步骤 3：填写基本信息和 OAuth 设置

角色：Salesforce 管理员

1. 填写 Basic Information（基本信息） 部分（必填项包括 App Name（应用名称）和 Contact Email（联系电子邮件））。

   

2. 展开 API (Enable OAuth Settings)（API（启用 OAuth 设置）） 部分，并勾选 Enable OAuth（启用 OAuth） 设置。

3. 在此部分中配置以下设置：

   • Callback URL（回调 URL）：添加以下两个链接，并将 <your-discourse-site> 替换为您 Discourse 站点的完整 URL（例如 meta.discourse.org）：
     https://<your-discourse-site>
https://<your-discourse-site>/auth/salesforce/callback
     确保任一 URL 末尾没有斜杠 /！
   • Available OAuth Scopes（可用的 OAuth 范围）：添加全部三项：
     • Access the identify URL service (id, profile, email, address, phone)（访问身份识别 URL 服务（id、个人资料、电子邮件、地址、电话））
     • Manage user data via APIs (api)（通过 API 管理用户数据（api））
     • Perform requests at any time (refresh_token, offline_access)（随时执行请求（refresh_token，offline_access））
   • Flow Enablement（流程启用）：启用以下两项：
     • Enable Client Credentials Flow（启用客户端凭据流程）
     • Enable JWT Bearer Flow（启用 JWT Bearer 流程）——插件需要此流程来创建潜在客户、联系人和案例

4. 在 Certificate Upload（证书上传） 下，点击 Upload files（上传文件），并上传步骤 1 中的 server.crt 文件。

   

5. 点击 Create（创建）。

步骤 4：获取 Consumer Key 和 Consumer Secret

角色： Salesforce 管理员

1. 在新创建的外部客户端应用上，点击 Settings（设置） 选项卡。

2. 向下滚动并展开 OAuth Settings（OAuth 设置）。

3. 点击 Consumer Key and Secret（客户端密钥和客户端密码）。

   

4. 提示时重新输入您的 Salesforce 登录凭据。

5. 复制 Consumer Key（客户端密钥） 和 Consumer Secret（客户端密码），并将它们发送给您的 Discourse 管理员，用于步骤 5。

步骤 5：配置 Discourse 插件设置

角色： Discourse 管理员

1. 在 Discourse 中，前往 Admin（管理员） → Plugins（插件） → Salesforce → Settings（设置）。

2. 填写以下设置：

   设置	值
   salesforce enabled	勾选框以启用集成
   salesforce client id	步骤 4 中的 Consumer Key（客户端密钥）
   salesforce client secret	步骤 4 中的 Consumer Secret（客户端密码）
   salesforce rsa private key	粘贴步骤 1 中 server.key 文件的完整内容
   salesforce username	Salesforce 集成用户的用户名
   salesforce authorization server url	仅当您使用自定义 Salesforce 域名时需要的（例如 https://mycompany.my.salesforce.com）

   

3. 点击 Save changes（保存更改）。

步骤 6：在 Salesforce 中授权 Discourse 应用

角色： Salesforce 集成用户

1. 前往 https://<your-discourse-site>/salesforce/admin/authorize，将 <your-discourse-site> 替换为您 Discourse 站点的完整 URL（例如 meta.discourse.org）。
2. 您将被重定向到 Salesforce，并提示您授权该应用。
3. 登录 Salesforce 并授予该应用访问权限。

完成此步骤后，一切应已就绪。您可以通过前往 Discourse 中的任何用户资料来确认其正常工作——管理员菜单中应出现 Sync with Salesforce（与 Salesforce 同步） 选项。

故障排除

如果设置后插件无法工作，请首先检查以下内容：

• 管理员仪表板健康检查：如果配置错误，插件会在 /admin 中显示两个警报：

  • SalesforceInvalidCredentials：Consumer Key（客户端密钥）、Consumer Secret（客户端密码）、RSA 私钥或用户名不正确
  • SalesforceAppNotApproved：授权步骤（步骤 6）未完成，或连接的应用被拒绝

• 启用详细日志记录：打开 salesforce_auth_verbose_logging 站点设置，以将详细的身份验证输出写入 Discourse 的 /logs。常见错误和原因：

症状	可能的原因
创建潜在客户或联系人时出现“Insufficient privileges（权限不足）”	集成用户没有潜在客户或联系人对象的创建/编辑权限
创建案例时出现“Insufficient privileges（权限不足）”	集成用户缺少案例或案例评论权限
授权步骤中出现“Invalid grant（无效授予）”	RSA 密钥与步骤 3 中上传的证书不匹配，或未启用 JWT Bearer 流程
创建潜在客户或联系人时出现“DUPLICATE_VALUE（重复值）”错误	如果用户已存在于 Salesforce 中，这是预期行为——插件会处理此情况，但有关详细信息，请参阅插件主要文档
Chatter 帖子未出现	集成用户可能没有 FeedItem（动态）创建权限