深入解析 Salesforce 命名凭证：集成工程师指南

十月 11, 2025

背景与应用场景

作为一名 Salesforce 集成工程师，我的日常工作核心就是将 Salesforce 平台与外部世界连接起来。无论是企业内部的 ERP 系统、财务软件，还是第三方的SaaS服务（如 Google, Slack, Stripe），构建无缝、安全且可维护的集成通道至关重要。在集成的早期阶段，我们面临一个棘手的问题：如何管理外部服务的认证凭证（如 API 密钥、用户名密码、Token 等）？

最初的解决方案通常比较粗糙，例如直接将凭证硬编码在 Apex 代码中，或者存储在自定义设置 (Custom Settings) / 自定义元数据 (Custom Metadata) 中。这些方法存在显而易见的弊端：

安全风险：凭证以明文或易于解码的形式存储，一旦代码或元数据泄露，将导致严重的安全漏洞。
维护噩梦：当外部服务的凭证过期或变更时（例如密码轮换策略），我们需要修改代码或元数据，然后重新部署。在拥有多个沙箱和生产环境的复杂组织中，这会变得极其繁琐且容易出错。
缺乏灵活性：难以针对不同用户或不同环境（开发、测试、生产）使用不同的凭证。

为了解决这些痛点，Salesforce 推出了 Named Credential (命名凭证)。它是一种标准、安全且可配置的功能，用于存储和管理对外部 Web 服务的调用端点 (Endpoint) 及其认证信息。它将认证过程从代码中完全分离出来，让集成工作变得前所未有的简单和安全。

典型的应用场景包括：

从 Apex 调用外部的 REST API 或 SOAP API，以获取或更新数据。
配置外部服务 (External Services)，以声明方式将 OpenAPI 规范转换为可直接在 Flow 中调用的操作。
在 Salesforce Connect 中配置 OData 外部数据源，实现对外部数据的实时访问。

原理说明

从本质上讲，一个 Named Credential 是一个配置记录，它将一个 URL 端点与一组认证参数安全地绑定在一起。当我们通过 Apex 代码或其他 Salesforce 功能调用一个 `Named Credential` 时，平台会在后台自动处理认证握手，并将认证信息（如 `Authorization` 头）附加到发出的 HTTP 请求中。

一个 `Named Credential` 主要由以下几个核心部分构成：

1. URL

这是外部服务的根 URL 或基础端点。例如 `https://api.example.com`。在代码中，我们只需要引用 `Named Credential` 并附加具体的资源路径（如 `/v1/invoices`），而无需关心完整的 URL。

2. 身份类型 (Identity Type)

这决定了 Salesforce 连接到外部系统时所使用的身份。主要有两种类型：

Named Principal (指定主体): 所有通过此 `Named Credential` 发出请求的 Salesforce 用户，都共享同一套凭证来认证外部系统。这适用于系统对系统的集成场景，例如 Salesforce 使用一个通用的 API 账户访问外部服务。
Per User (每用户): 每个 Salesforce 用户都使用自己独立的凭证来认证外部系统。当外部系统需要根据操作用户的身份来控制权限和审计时，这种模式非常有用。每个用户都需要在个人设置中对该外部系统进行一次性的认证授权。

3. 认证协议 (Authentication Protocol)

这是 `Named Credential` 的核心，它定义了 Salesforce 如何向外部服务证明自己的身份。Salesforce 支持多种主流协议：

Password Authentication: 基本的用户名密码认证。
OAuth 2.0: 业界标准授权协议，支持多种授权流程（如 Authorization Code, JWT Bearer Flow 等），是连接到 Google, Microsoft, 其他 Salesforce Org 等现代 API 的首选。
JWT (JSON Web Token): 支持使用数字签名的 JWT 来进行服务器到服务器的认证。
AWS Signature Version 4: 专用于安全地调用 Amazon Web Services (AWS) API。

当配置好认证协议后，Salesforce 会负责处理所有复杂的细节，例如获取、缓存和刷新 `OAuth` 的 `Access Token`，开发者无需编写任何相关的样板代码。

4. 调用语法 (Callout Syntax)

在 Apex 中使用 `Named Credential` 的最大便利之处在于其独特的端点语法：`callout:My_Named_Credential_Name/path`。这里的 `My_Named_Credential_Name` 是你创建的 `Named Credential` 的 API 名称。Salesforce 识别到 `callout:` 前缀后，就会自动执行以下操作：

查找名为 `My_Named_Credential_Name` 的配置。
根据其定义的认证协议完成认证。
构建完整的 URL（将 `Named Credential` 中定义的 URL 与代码中提供的 `/path` 结合）。
将认证信息（如 `Authorization: Bearer ...` 或其他）注入到 HTTP 请求头中。
发送请求。

5. 外部凭证 (External Credential) 的演进

值得注意的是，Salesforce 正在逐步推广一个更现代化、更模块化的框架，即 External Credential (外部凭证) 和 Principal (主体)。`External Credential` 定义了认证协议和权限集，而 `Principal` 则关联了具体的用户和凭证。在当前版本中，当你创建一个传统的 `Named Credential` 时，Salesforce 会在后台自动为你创建相应的 `External Credential` 和 `Principal`。作为集成工程师，了解这一演进方向对于设计未来的集成架构非常重要。

示例代码

以下是一个使用 `Named Credential` 在 Apex 中调用外部 REST API 的典型示例。假设我们已经创建了一个名为 `My_External_Service` 的 `Named Credential`，它指向 `https://api.example.com` 并配置了适当的认证。

此代码示例严格遵循 Salesforce 官方文档中的标准实践。

// Apex Class to make a callout to an external service using a Named Credential.
public class ApiCalloutExample {
    
    // Method to get invoice data from the external service.
    public static HttpResponse getInvoices() {
        // 1. 创建一个新的 HttpRequest 对象。
        // 这是发起 HTTP 请求的标准起点。
        HttpRequest req = new HttpRequest();
        
        // 2. 设置请求端点。这是 Named Credential 的核心优势所在。
        // 'callout:My_External_Service' 指向我们配置的 Named Credential。
        // Salesforce 会自动将 'https://api.example.com' 替换进来，并处理认证。
        // '/v1/invoices' 是我们希望访问的具体资源路径。
        req.setEndpoint('callout:My_External_Service/v1/invoices');
        
        // 3. 设置 HTTP 方法。这里我们使用 GET 来获取数据。
        // 其他常见方法还包括 POST, PUT, DELETE 等。
        req.setMethod('GET');

        // 4. (可选) 如果需要，可以设置自定义请求头。
        // 注意：认证相关的头 (如 Authorization) 会由 Named Credential 自动添加，无需手动设置。
        req.setHeader('Content-Type', 'application/json;charset=UTF-8');
        
        // 5. 创建 Http 对象实例，用于发送请求。
        Http http = new Http();
        
        // 6. 发送请求并获取 HttpResponse 对象。
        // 这是一个同步调用，代码会在此处等待，直到收到服务器的响应或超时。
        HttpResponse res = http.send(req);
        
        // 7. (可选) 可以在此处理响应。例如，检查状态码。
        if (res.getStatusCode() == 200) {
            // 请求成功，可以解析 res.getBody() 中的 JSON 数据。
            System.debug('Success: ' + res.getBody());
        } else {
            // 请求失败，记录错误信息。
            System.debug('Error: ' + res.getStatusCode() + ' ' + res.getStatus());
            System.debug('Error Body: ' + res.getBody());
        }
        
        // 8. 返回完整的响应对象，以便调用者可以进一步处理。
        return res;
    }
}

注意事项

权限 (Permissions)

- 管理员权限: 创建和修改 `Named Credential` 需要 "Customize Application" 权限。

- 用户访问权限: 这一点至关重要但常常被忽略。仅仅在代码中调用 `Named Credential` 是不够的，执行该代码的用户必须被授权访问此 `Named Credential`。通常这是通过用户的简档 (Profile) 或更推荐的权限集 (Permission Set) 来授予的。在权限集中，可以找到 "Named Credential Access" 的相关设置。这提供了一个强大的安全控制层，确保只有授权用户才能发起对特定外部系统的调用。

API 限制 (API Limits)

使用 `Named Credential` 并不会绕过 Salesforce 的 Governor Limits。每次 `http.send(req)` 调用仍然计入 Apex 事务中的总调用次数限制（同步 Apex 为 100 次）和总超时限制（最长 120 秒）。在设计批量处理或复杂的触发器逻辑时，必须充分考虑这些限制。

错误处理 (Error Handling)

健壮的集成必须有完善的错误处理机制。在使用 `Named Credential` 时，应该始终将 `http.send()` 调用包裹在 `try-catch` 块中，以捕获 `System.CalloutException` 等潜在的异常（例如，DNS 解析失败、连接超时）。

此外，即使请求成功发送，也并不意味着业务操作成功。必须检查 `HttpResponse` 的状态码 (`res.getStatusCode()`)。通常 `2xx` 范围的状态码表示成功，`4xx`（如 401 Unauthorized, 404 Not Found）表示客户端错误，`5xx` 表示服务器端错误。代码逻辑需要能够优雅地处理这些非成功的响应。

安全考量 (Security Considerations)

- 凭证的安全性: `Named Credential` 将所有敏感信息（如密码、密钥）加密存储在 Salesforce 数据库中，不会暴露在代码或元数据中，这是其核心安全价值。

- 合并字段 (Merge Fields): `Named Credential` 的配置中有一个选项 "Allow Merge Fields in HTTP Header/Body"。启用此选项允许在请求头和请求体中使用 Salesforce 的合并字段（如 `{!$User.FirstName}`）。这是一个强大的功能，但也带来了潜在风险。如果使用不当，可能会意外泄露记录中的敏感数据。请务必谨慎使用，并确保其符合数据安全策略。

总结与最佳实践

对于任何 Salesforce 集成工程师来说，Named Credential 都是工具箱中不可或缺的核心工具。它通过将认证逻辑与业务逻辑分离，极大地提升了集成的安全性、可维护性和开发效率。

以下是一些在实践中总结出的最佳实践：

杜绝硬编码: 始终使用 `Named Credential` 来管理所有对外部服务的 API 调用，彻底告别在代码或配置中存储凭证的坏习惯。
遵循最小权限原则: 通过权限集 (Permission Set) 精确地将 `Named Credential` 的访问权限授予需要它的用户或集成用户，而不是宽泛地添加到整个简档 (Profile) 中。
选择正确的身份类型: 根据业务需求仔细选择 `Named Principal` 或 `Per User`。前者适用于系统级集成，后者适用于需要用户级授权和审计的场景。
为不同环境制定策略: 生产环境和沙箱环境的外部端点通常是不同的。最佳实践是为每个环境创建独立的 `Named Credential`（例如，`MyAPI_Prod` 和 `MyAPI_UAT`），并通过自定义元数据或环境变量在代码中动态选择使用哪一个，以实现无缝部署。
拥抱未来: 开始学习和理解 External Credential 框架。虽然目前 `Named Credential` 仍然是主流，但 `External Credential` 提供了更强的灵活性和粒度，将成为未来复杂集成场景的首选方案。

总之，熟练掌握和正确使用 `Named Credential`，是构建一个安全、可靠且易于管理的 Salesforce 集成解决方案的基石。

Salesforce中文网