Salesforce 指定ログイン情報（Named Credentials）を活用したセキュアで保守性の高い API 連携マスターガイド

皆さん、こんにちは。Salesforce 統合エンジニア (Salesforce Integration Engineer) です。日々の業務で Salesforce と外部システムを連携させる際、認証情報の管理に頭を悩ませた経験はありませんか？今回の記事では、その悩みを解決する強力な機能、Named Credential (指定ログイン情報) について、統合エンジニアの視点から深く掘り下げて解説します。

背景と応用シナリオ

Salesforce をプラットフォームとして利用する上で、外部の Web サービスとの連携は不可欠です。例えば、ERP システムから在庫情報を取得したり、決済ゲートウェイと連携して支払処理を行ったり、外部の気象情報 API を呼び出して取引先責任者の地域情報に天候を付与するなど、そのユースケースは多岐にわたります。

これらの連携を実装する際、最も重要な課題の一つが「認証情報の管理」です。従来の方法では、API キーやユーザー名、パスワードといった機密情報を Apex コード内にハードコーディングしたり、カスタム設定やカスタムメタデータに保存したりすることが一般的でした。しかし、このアプローチにはいくつかの深刻な問題点があります。

従来の認証情報管理の課題

セキュリティリスク: コードやカスタムメタデータに認証情報を平文で保存すると、権限を持つユーザーが容易に閲覧できてしまい、情報漏洩のリスクが高まります。
メンテナンス性の低下: 認証情報（特にパスワードやアクセストークン）が変更された場合、コードや設定を修正し、再度デプロイする必要があります。連携先が複数ある場合や、サンドボックスと本番環境でエンドポイント URL が異なる場合、管理は非常に煩雑になります。
コードの複雑化: 認証処理（OAuth 2.0 のトークン取得・更新など）をすべて Apex で自前で実装する必要があり、コードが複雑化し、バグの温床となり得ます。

これらの課題を解決するために Salesforce が提供しているのが、Named Credential です。Named Credential は、API 連携における認証情報とエンドポイント URL を一元的に、かつ安全に管理するための仕組みです。これを利用することで、開発者は認証の詳細を意識することなく、セキュアで保守性の高いインテグレーションを迅速に構築できます。

原理の説明

Named Credential の核心は、「認証の抽象化」と「エンドポイントの分離」にあります。これにより、インテグレーションの構築が劇的に簡素化されます。

コンポーネント

最新の Named Credential は、主に2つのコンポーネントで構成されています。

External Credential (外部ログイン情報): 認証プロトコル（OAuth 2.0, JWT, Basic 認証など）と、そのプロトコルに必要なパラメータ（クライアント ID, シークレット, スコープなど）を定義します。これは再利用可能な認証設定のテンプレートのようなものです。
Named Credential (指定ログイン情報): External Credential を参照し、実際のエンドポイント URL とを結びつけます。また、この Named Credential をどのプロファイルや権限セットのユーザーが利用できるかを制御します。

この2段階の構成により、例えば複数の API エンドポイントが同じ認証メカニズムを利用する場合、一つの External Credential を複数の Named Credential で共有でき、管理がさらに効率化されます。

認証フロー

開発者が Apex コードから Named Credential を使ってコールアウトを行うと、Salesforce プラットフォームが裏側で以下の処理を自動的に実行します。

Apex コードは callout:MyNamedCredential/path という特殊な URL を指定してリクエストを送信します。
Salesforce は MyNamedCredential の設定を読み込みます。
関連付けられた External Credential の定義に基づき、必要な認証処理（例: OAuth 2.0 のアクセストークンの取得・更新）を自動的に実行します。
取得した認証情報（API キーやアクセストークンなど）を HTTP ヘッダーに自動的に付与します。
Named Credential に設定されたエンドポイント URL と Apex コードで指定されたパスを結合し、最終的なリクエスト URL を構築して外部サービスにリクエストを送信します。

この仕組みにより、Apex コードからは認証情報が完全に隠蔽され、開発者はビジネスロジックの実装に集中できます。エンドポイントの URL がサンドボックスから本番に変わっても、コードの修正は不要で、Named Credential の設定を変更するだけで対応可能です。

示例代码

ここでは、Named Credential を使用して外部の REST API (GET) を呼び出す Apex コードの例を示します。このコードは、My_API_Credential という名前の Named Credential が設定済みであることを前提としています。

このコードは Salesforce Developer の公式ドキュメントで紹介されている標準的なコールアウトの形式に準拠しています。

Apex クラス: ExternalAPIService.cls

public class ExternalAPIService {

    /**
     * @description 指定ログイン情報を使用して外部 API からデータを取得するメソッド
     * @param recordId 取得対象のレコード ID (例: 'orders/12345')
     * @return API レスポンスのボディ (JSON 文字列など)
     */
    public static String getRecordData(String recordId) {
        // 1. HttpRequest オブジェクトをインスタンス化します。
        // これは、これから送信する HTTP リクエストの詳細を定義するためのオブジェクトです。
        HttpRequest req = new HttpRequest();

        // 2. エンドポイントを設定します。
        // 'callout:My_API_Credential' の部分が指定ログイン情報の名前です。
        // Salesforce はこの名前を解決し、設定されたベース URL に '/records/' と recordId を自動的に連結します。
        // 例: ベース URL が https://api.example.com の場合、
        // 最終的な URL は https://api.example.com/records/12345 となります。
        // コード内に URL をハードコーディングする必要がありません。
        req.setEndpoint('callout:My_API_Credential/records/' + recordId);

        // 3. HTTP メソッドを設定します。ここではデータを取得するため 'GET' を指定します。
        // 他にも 'POST', 'PUT', 'DELETE', 'PATCH' などが利用可能です。
        req.setMethod('GET');
        
        // 4. (オプション) ヘッダーを設定します。
        // 認証ヘッダー (例: 'Authorization: Bearer ...') は Salesforce が自動で付与するため、
        // ここで設定する必要はありません。ここでは、リクエストのコンテンツタイプを指定しています。
        req.setHeader('Content-Type', 'application/json;charset=UTF-8');

        // 5. Http オブジェクトをインスタンス化し、リクエストを送信します。
        Http http = new Http();
        HttpResponse res = null;

        try {
            // http.send(req) を実行すると、Salesforce プラットフォームが
            // 指定ログイン情報に基づいた認証処理を行い、実際に外部へリクエストを送信します。
            res = http.send(req);
        } catch(System.CalloutException e) {
            // コールアウトが失敗した場合 (ネットワークエラー、タイムアウトなど) の例外処理です。
            // エラーをログに記録したり、カスタム例外をスローしたりする処理をここに記述します。
            System.debug('Callout error: '+ e.getMessage());
            // 呼び出し元にエラーを通知するために例外を再スローすることもできます。
            throw new AuraHandledException('外部 API への接続に失敗しました: ' + e.getMessage());
        }

        // 6. レスポンスを処理します。
        // HTTP ステータスコードが 200 (成功) の場合のみ、レスポンスボディを返します。
        if (res.getStatusCode() == 200) {
            System.debug('Success! Response Body: ' + res.getBody());
            return res.getBody();
        } else {
            // 200 以外のステータスコードが返ってきた場合の処理です。
            // API からのエラーメッセージなどをログに記録します。
            System.debug('Error from endpoint. Status: ' + res.getStatus() + 
                         ', Status Code: ' + res.getStatusCode() + 
                         ', Response Body: ' + res.getBody());
            // 適切なエラーハンドリングを行います。
            throw new AuraHandledException('API からエラーが返されました: ' + res.getStatus());
        }
    }
}

このコードの最大の利点は、認証に関する記述が一切ないことです。トークンの取得、リフレッシュ、ヘッダーへの設定といった複雑な処理はすべて Salesforce プラットフォームが担ってくれます。これにより、コードはシンプルで読みやすく、本質的なビジネスロジックに集中できます。

注意事項

Named Credential は非常に強力な機能ですが、利用にあたってはいくつかの注意点があります。

権限管理

Named Credential の作成・編集: 「アプリケーションのカスタマイズ」権限が必要です。通常はシステム管理者や一部の開発者に限定されるべきです。
Named Credential の利用: Named Credential を利用するユーザーには、その Named Credential に関連付けられた External Credential Principal Access を権限セットやプロファイル経由で付与する必要があります。これにより、「誰が」「どの外部システムへ」アクセスできるかを細かく制御できます。

API 制限 (Governor Limits)

Named Credential を利用したコールアウトも、Salesforce のガバナ制限（1トランザクションあたりのコールアウト回数、合計タイムアウト時間など）の対象となります。大量のデータを扱うバッチ処理などで利用する際は、制限に抵触しないよう設計に注意が必要です。

エラーハンドリング

サンプルコードにも示した通り、System.CalloutException を適切にキャッチする必要があります。これは、ネットワークの問題やタイムアウト、DNS の解決失敗などで発生します。
また、API 側のエラー（例: HTTP 401 Unauthorized, 404 Not Found, 500 Internal Server Error）も考慮に入れる必要があります。HttpResponse.getStatusCode() をチェックし、ステータスコードに応じた分岐処理を実装することが堅牢な連携システムを構築する鍵です。

セキュリティ

Named Credential を利用することで、コード内から認証情報がなくなりますが、Named Credential の設定自体へのアクセス権管理は非常に重要です。本番環境の認証情報を安易に開発者サンドボックスにコピーしない、最小権限の原則に従う、といった基本的なセキュリティ対策を怠らないでください。
また、callout: スキームは Apex だけでなく、数式項目やフローなどでも利用可能です。意図しない情報漏洩を防ぐため、どの機能で Named Credential を利用するかは慎重に検討してください。

まとめとベストプラクティス

Named Credential は、Salesforce と外部システム間の API 連携を、セキュアかつ効率的に実現するためのデファクトスタンダードと言うべき機能です。

統合エンジニアの視点から、以下のベストプラクティスを推奨します。

常に Named Credential を使用する: 新規のインテグレーションを構築する際は、必ず Named Credential の利用を第一に検討してください。コードやカスタム設定に認証情報やエンドポイントをハードコーディングすることは避けましょう。
環境ごとに設定を分離する: 開発、ステージング、本番といった各環境で、それぞれに対応する Named Credential を作成します。コードは同じままで、デプロイ先の環境で適切なエンドポイントと認証情報が自動的に使われるため、デプロイメントプロセスが大幅に簡素化されます。
再利用可能な External Credential を設計する: 複数の API が同じ認証基盤（例えば、同じ OAuth IdP）を利用している場合、共通の External Credential を作成し、それを複数の Named Credential で共有します。これにより、認証設定の変更が一箇所で済み、管理が容易になります。
適切な認証プロトコルを選択する: 連携先の API がサポートする認証プロトコルを正確に理解し、最もセキュアな方式（例: OAuth 2.0）を選択してください。
詳細なデバッグログと監視: 連携に問題が発生した際、どこで問題が起きているのか（Salesforce 側か、ネットワークか、外部 API 側か）を切り分けるために、適切なデバッグログを実装し、API コールアウトのエラーを監視する仕組みを導入することが重要です。

Named Credential をマスターすることは、Salesforce プラットフォームにおけるインテグレーションの品質を一段階引き上げることにつながります。ぜひこの強力な機能を活用して、安全で、保守性が高く、拡張しやすい連携ソリューションを構築してください。

にゃんこのSalesforce日記

このブログを検索