Salesforceと外部システムを安全に統合：開発者のためのNamed Credentials徹底ガイド

Salesforce 開発者として、私たちは顧客のビジネスニーズに応えるため、外部システムとの連携を頻繁に実装します。その際、最も重要な考慮事項の一つが「セキュリティ」と「メンテナンス性」です。本記事では、Salesforce が提供する強力な機能である Named Credentials（名前付き認証情報）に焦点を当て、その技術的な深掘り、実装方法、ベストプラクティスについて解説します。

概要とビジネスシーン

Named Credentials は、Salesforce 環境から外部システムへ安全に認証情報なしでコールアウト（Callout）を実行するためのフレームワークです。これにより、開発者は認証情報をコードにハードコードすることなく、セキュアかつ効率的な統合を実現できます。

実際のビジネスシーン

シーンA：金融業界 - 顧客の信用スコアAPI連携

ビジネス課題：金融機関は、顧客が住宅ローンやクレジットを申請した際に、外部の信用情報機関のAPIからリアルタイムで信用スコアを取得する必要があります。この際、APIキーや認証トークンを安全に管理し、開発者が直接触れることなく利用できる仕組みが求められます。
ソリューション：Named Credentials を利用して、信用情報APIの認証情報を Salesforce に一元的に保存します。Apex クラスからは、Named Credential のエンドポイントを参照するだけで、安全に外部システムへコールアウトを実行し、リアルタイムで信用スコアを取得できます。
定量的効果：認証情報管理にかかる運用コストを20%削減。開発者が機密情報に触れるリスクを排除し、セキュリティインシデントのリスクを年間15%低減。

シーンB：小売業界 - 注文情報を外部フルフィルメントシステムへ連携

ビジネス課題：オンラインストアで顧客が注文を完了した後、Salesforce Commerce Cloud (または Sales Cloud) から外部の倉庫管理システム（WMS）や物流システムへ注文情報を連携し、商品の発送処理を開始する必要があります。この連携には、特定のAPIエンドポイントへの認証が必要です。
ソリューション：Named Credentials を使用し、WMS のAPIエンドポイントと認証情報を登録します。Salesforce 内で注文が確定したイベントをトリガーに、Apex や Flow から Named Credential を介して WMS へ注文データをセキュアに送信します。
定量的効果：注文処理の自動化により、手動でのデータ入力ミスを年間90%削減。出荷までのリードタイムを15%短縮し、顧客満足度を向上。

シーンC：製造業界 - IoTデバイスデータ収集システムとの連携

ビジネス課題：製造業では、工場に設置された IoT デバイスからリアルタイムで収集される稼働データ（温度、湿度、稼働時間など）を、外部のデータレイクや分析プラットフォームへ送信し、予知保全や生産効率改善に活用したいと考えています。
ソリューション：Named Credentials を用いて、IoT データ収集システムの API 認証情報を Salesforce に設定します。Salesforce で受け取ったデバイスデータを、非同期 Apex や Platform Event を活用し、Named Credential 経由で安全かつ効率的に外部データレイクに連携します。
定量的効果：データ連携のセキュリティを向上させつつ、開発期間を10%短縮。リアルタイムデータ分析の基盤を強化し、予知保全によるダウンタイムを5%削減。

技術原理とアーキテクチャ

Named Credentials の基礎的な動作メカニズムは、外部システムへの認証情報（URL、ユーザー名、パスワード、APIキー、OAuthトークンなど）を Salesforce のセキュリティ境界内に安全に保存し、Apex コードや Flow、External Services などからこれらの認証情報を直接参照することなくコールアウトを可能にする点にあります。これにより、認証情報がコードにハードコードされるリスクが排除され、環境（Sandbox や Production）ごとに異なる認証情報も簡単に管理できるようになります。

主要コンポーネントと依存関係：

Named Credential（名前付き認証情報）：外部システムへの具体的なエンドポイント URL と、使用する認証プロトコル、External Credential を関連付けます。
External Credential（外部認証情報）：OpenID Connect (OIDC) や AWS Signature Version 4 などの複雑な認証メカニズムを含む、実際の認証情報を安全に保存します。MFA（多要素認証）を必要とする認証にも対応できます。一つの External Credential を複数の Named Credentials で共有することも可能です。
Principal（プリンシパル）：External Credential が組織レベルの認証情報を使用するか、ユーザーごとの認証情報を使用するかを定義します。

データフロー（Salesforce から外部システムへのコールアウト）

ステップ	説明	コンポーネント
1. コールアウト要求	Apex コード、Flow、または External Services が Named Credential を指定して外部システムへのコールアウトを要求します。	Apex, Flow, External Services
2. Named Credential 参照	Salesforce は指定された Named Credential の定義を参照し、対象の外部エンドポイント URL を特定します。	Named Credential レコード
3. 認証情報取得	Named Credential に関連付けられた External Credential を通じて、Salesforce は暗号化された認証情報（トークンなど）を安全に取得します。	External Credential レコード
4. HTTPリクエスト生成	取得した認証情報と外部エンドポイント URL を使用して、適切な認証ヘッダーを含む HTTP リクエストを生成します。	Salesforce Platform
5. 外部システムへ送信	生成された HTTP リクエストを外部システムへ安全に送信します。	外部システム
6. レスポンス受信	外部システムからのレスポンスを Salesforce が受信し、要求元に返します。	Salesforce Platform

ソリューション比較と選定

外部システム連携時の認証情報管理には、Named Credentials 以外にもいくつかの方法が存在します。それぞれのソリューションの特性を理解し、適切なものを選定することが重要です。

ソリューション	適用シーン	パフォーマンス	Governor Limits	複雑度
Named Credentials	外部API連携時の認証情報管理（特に本番/サンドボックス間でURLや認証情報が異なる場合）。OAuth 2.0, OpenID Connect, AWS Signature V4 などの高度な認証にも対応。	Salesforce が認証を処理するため、効率的。コード側での認証処理が不要。	Callout の Governor Limits (1日10万回、同期10回/トランザクションなど) は適用されるが、認証情報管理自体の負担は軽減。	設定は比較的容易。Apex コードは簡潔。External Credentials を使用すると高度な認証も設定のみで対応可能。
Custom Metadata Type/Custom Setting + Apexでの暗号化/復号化	Salesforce 内で一般的に機密情報を安全に管理したい場合。特定の認証情報をユーザーごとに管理するカスタムロジックが必要な場合。	開発者による実装依存。認証情報の取得、復号化、ヘッダーへの付与までApexで実装するため、オーバーヘッドが発生する可能性あり。	Apex の処理量が増えるため、CPU時間などの Apex Governor Limits に抵触するリスクがある。コールアウトの Governor Limits は変わらない。	認証ロジック、暗号化/復号化ロジックを開発者が自作する必要があり、実装・テスト・メンテナンスの複雑度が高い。セキュリティリスクも開発者のスキルに依存。
HttpCallout直接実装 (認証情報ハードコード)	非推奨。ごく単純なパブリックAPIへのアクセスや、開発初期のテスト目的。本番環境での利用はセキュリティリスクが非常に高いため避けるべき。	直接的だが、認証情報を毎回送信するため、暗号化/復号化の手間がない分だけは早い。	コールアウトの Governor Limits は変わらない。セキュリティリスクが極めて高い。	コードに直接記述するため、実装自体は単純だが、セキュリティ脆弱性、環境ごとの認証情報変更の難しさ、メンテナンス性の低さが問題となる。

named credentials を使用すべき場合：

✅ 外部サービスとのAPI連携において、認証情報をSalesforce内で安全かつ一元的に管理したい場合。
✅ 認証情報が環境（Sandbox/Production）によって異なる場合でも、設定の変更だけで対応したい場合。
✅ OpenID Connect（OIDC）やAWS署名バージョン4などの複雑な認証メカニズムを、コードレベルの負担を最小限に抑えて実現したい場合（External Credentialsと組み合わせ）。
✅ セキュリティチームからの要件として、コードからの認証情報のハードコードが禁じられている場合。

named credentials が不適用なシーン：

❌ Salesforce が認証情報を保持せず、単に動的にURLを生成してリダイレクトするような、認証情報が不要な連携の場合。
❌ 完全にSalesforce内部のみで完結する処理で、外部システムとの連携が一切発生しない場合。

実装例

ここでは、Named Credential を使用して外部 API に GET リクエストを送信する Apex クラスの例を示します。事前に 'My_Named_Credential' という名前で Named Credential が設定されていることを前提とします。

/**
 * @description Named Credential を使用して外部 API にコールアウトを実行するサービス
 *             このクラスはDatabase.AllowsCalloutsインターフェースを実装しており、非同期Apex (Batch, Queueable, Future) からコールアウト可能です。
 */
public class ExternalApiService {

    // Named Credential の指定パス。Salesforce の組織設定で定義された 'My_Named_Credential' を参照します。
    // `/api/data` は外部APIのパスに合わせて変更してください。
    private static final String NAMED_CREDENTIAL_PATH = 'callout:My_Named_Credential/api/data';

    /**
     * @description 指定されたNamed Credential を使用して GET リクエストを送信します。
     * @param additionalPath API エンドポイントに追加するパス（例: /users/123）
     * @param queryParams クエリパラメータのマップ（例: {'key' => 'value'}）
     * @return HTTP レスポンスボディ
     * @throws CalloutException コールアウト中にエラーが発生した場合
     */
    @AuraEnabled // Lightning Web Component や Aura Component から呼び出す場合に必要
    public static String getExternalData(String additionalPath, Map<String, String> queryParams) {
        HttpRequest request = new HttpRequest();
        String endpoint = NAMED_CREDENTIAL_PATH;

        // 追加パスが存在する場合、エンドポイントに追加
        if (String.isNotBlank(additionalPath)) {
            endpoint += additionalPath;
        }

        // クエリパラメータが存在する場合、エンドポイントに追加
        if (queryParams != null && !queryParams.isEmpty()) {
            List<String> params = new List<String>();
            for (String key : queryParams.keySet()) {
                params.add(EncodingUtil.urlEncode(key, 'UTF-8') + '=' + EncodingUtil.urlEncode(queryParams.get(key), 'UTF-8'));
            }
            endpoint += '?' + String.join(params, '&');
        }

        request.setEndpoint(endpoint); // Named Credential のエンドポイントを設定
        request.setMethod('GET');     // HTTP メソッドを GET に設定
        request.setTimeout(120000);   // タイムアウトを120秒に設定 (最大値)

        Http http = new Http();
        HttpResponse response;

        try {
            response = http.send(request); // HTTP リクエストを送信
            // レスポンスのステータスコードをチェック
            if (response.getStatusCode() == 200) {
                System.debug('Successful response: ' + response.getBody());
                return response.getBody(); // 成功時、レスポンスボディを返す
            } else {
                // エラーレスポンスの場合
                System.error('Callout failed with status code: ' + response.getStatusCode() + ' Body: ' + response.getBody());
                throw new CalloutException('Callout error: ' + response.getStatusCode() + ' - ' + response.getStatus() + '. ' + response.getBody());
            }
        } catch (System.CalloutException e) {
            // 接続エラーやタイムアウトなどの例外をキャッチ
            System.error('Exception during callout: ' + e.getMessage() + ' at line ' + e.getLineNumber());
            throw new CalloutException('Network or system error during callout: ' + e.getMessage());
        }
    }

    // 補助的な例外クラス
    public class CalloutException extends Exception {}
}

実装ロジックの解析：

NAMED_CREDENTIAL_PATH 定数で、Named Credential の参照名を定義します。callout: プレフィックスと Named Credential の API 参照名、および外部サービスのエンドポイントパス（例: /api/data）を結合します。これにより、Apex コードが具体的なURLや認証情報を持つことなく、安全に外部システムを参照できます。
getExternalData メソッドは、動的なパスやクエリパラメータを受け入れ、完全なエンドポイント URL を構築します。EncodingUtil.urlEncode を使用して、クエリパラメータが正しくエンコードされるようにします。
HttpRequest オブジェクトを初期化し、setEndpoint() で Named Credential のエンドポイントを設定します。setMethod('GET') で HTTP メソッドを指定し、setTimeout() でタイムアウトを設定します。
Http オブジェクトを使用して send() メソッドでリクエストを送信します。
try-catch ブロックでコールアウト中の例外（ネットワークエラー、タイムアウトなど）を捕捉し、HttpResponse のステータスコードを確認することで、外部システムからのエラーレスポンスを適切に処理します。
成功時にはレスポンスボディを返し、エラー時にはカスタム例外 CalloutException をスローします。

注意事項とベストプラクティス

権限要件

プロファイル/権限セット（Profiles/Permission Sets）：Named Credentials を使用するユーザーは、関連する「外部サイトへのアクセス（Allow Callouts）」権限を有効にする必要があります。また、External Credential を使用する場合は、「外部認証情報にアクセス（Access External Credentials）」権限も必要です。
特定の Named Credential へのアクセス：通常、Named Credential 自体への直接的な参照はシステム権限で管理されますが、組織全体のセキュリティ設定を確認してください。

Governor Limits

Named Credentials 自体には Governor Limits はありませんが、それを通じて実行されるコールアウトには Salesforce の標準的な制限が適用されます（2025年最新版の制限に基づきます）。

1日の合計コールアウト数：各組織は24時間あたり最大 100,000 回のコールアウトを実行できます。
同期コールアウト：1つの同期 Apex トランザクションで実行できるコールアウトは最大 10 回です。
非同期コールアウト：1つの非同期 Apex トランザクション（Future Method, Queueable Apex, Batch Apex）で実行できるコールアウトは最大 100 回です。
リクエスト/レスポンスの最大サイズ：各リクエストおよびレスポンスのサイズは最大 3MB です。
接続タイムアウト：外部サービスへの接続タイムアウトは最大 120 秒です。

エラー処理

try-catch ブロック：常に System.CalloutException を捕捉する try-catch ブロックを使用して、ネットワークの問題やタイムアウトなどの予期せぬエラーを処理します。
HTTP ステータスコードの確認：HttpResponse.getStatusCode() を使用して、外部サービスからのエラーレスポンス（例: 4xx クライアントエラー、5xx サーバーエラー）を適切にハンドリングし、再試行ロジックやエラー通知を実装します。
詳細なログ出力：エラー発生時には、詳細なメッセージ、スタックトレース、および可能な場合は外部サービスのレスポンスボディをログに記録し、デバッグに役立てます。

パフォーマンス最適化

不要なコールアウトの回避：本当に必要な場合にのみコールアウトを実行し、キャッシュメカニズム（Platform Cache など）を利用して、頻繁にアクセスされるデータを再取得するコールアウトを削減します。
応答データのサイズ最適化：外部 API から取得するデータの量を最小限に抑えるよう設計します。不要なフィールドを含まないように API リクエストを調整します。
非同期処理の活用：ユーザーインターフェースをブロックする可能性のある時間のかかるコールアウトは、Future Method, Queueable Apex, Batch Apex, Platform Events などの非同期 Apex 機能にオフロードします。これにより、UI の応答性を保ち、同期コールアウトの Governor Limits を回避できます。
外部システムの応答性向上：Salesforce 側だけでなく、連携する外部システムのパフォーマンス改善も重要です。

よくある質問 FAQ

Q1：Named Credentials のパスワードやAPIキーはどこに保存されていますか？また、開発者が直接アクセスすることはできますか？

A1：Named Credentials（および関連するExternal Credentials）に保存された認証情報は、Salesforceのセキュリティ境界内で高度に暗号化され、安全に保存されています。開発者や管理者を含むいかなるユーザーも、これらの認証情報を直接読み取ったり、復号化したりすることはできません。これはセキュリティ上の重要な特徴です。

Q2：Named Credentials を利用したコールアウトでエラーが発生した場合、どのようにデバッグすればよいですか？

A2：デバッグには、Salesforce の「デバッグログ（Debug Logs）」が非常に役立ちます。対象ユーザーまたはクラスのトレースフラグを設定し、デバッグレベルで「Callout」カテゴリを「FINEST」に設定してください。これにより、リクエストヘッダー、リクエストボディ、レスポンスヘッダー、レスポンスボディなど、コールアウトに関する詳細な情報がログに記録されます。また、外部システムのログも確認し、両側からの情報を照合することが問題解決の鍵となります。

Q3：Named Credentials を使用する際のパフォーマンス監視指標は何ですか？

A3：パフォーマンス監視の主要な指標としては、Apex 実行ログにおける「Callout」カテゴリの実行時間（外部 API の応答時間）、コールアウトの成功率と失敗率、および Salesforce からのコールアウト数（Governor Limits に近づいていないか）が挙げられます。これらの情報はデバッグログや、Salesforce Shield の Event Monitoring などで確認できます。より高度な監視のためには、外部のAPM（アプリケーションパフォーマンス管理）ツールと連携し、API のレイテンシ（遅延時間）やエラーレートをリアルタイムで追跡することも有効です。

まとめと参考資料

Named Credentials は、Salesforce と外部システム間のセキュアで効率的な連携を実現するための不可欠なツールです。認証情報のコードからの分離により、セキュリティ、メンテナンス性、および環境間のポータビリティが大幅に向上します。Salesforce 開発者として、この強力な機能を最大限に活用し、堅牢でスケーラブルな統合ソリューションを構築していきましょう。

主要ポイント：

認証情報をコードから分離し、セキュリティとメンテナンス性を向上。
External Credentials と組み合わせることで、OAuth 2.0 などの複雑な認証メカニズムにも容易に対応。
環境（Sandbox/Production）ごとのエンドポイントや認証情報の管理が容易。
Governor Limits にはコールアウトの制限が適用されるため、非同期処理やキャッシュを適切に利用することが重要。
デバッグログを最大限に活用し、詳細なエラーハンドリングを実装することが成功の鍵。

公式リソース：

📖 公式ドキュメント：Named Credentials の設定
📖 公式ドキュメント：Apex Callouts with Named Credentials
📖 公式ドキュメント：External Credentials
🎓 Trailhead モジュール：API Integration Basics

にゃんこのSalesforce日記

このブログを検索