Salesforce指定ログイン情報（Named Credentials）を徹底解説：セキュアなAPI連携の実現

執筆者：Salesforce 連携エンジニア

背景と応用シナリオ

Salesforceプラットフォームの強力な機能の一つは、外部システムとシームレスに連携できる能力にあります。ERP、決済ゲートウェイ、マーケティングオートメーションツールなど、多種多様な外部サービスとのAPI連携は、今日のビジネスにおいて不可欠です。しかし、これらの連携を実現する上で、最も重要な課題の一つが「認証情報の管理」です。

かつて、多くの開発者はApexコード内にエンドポイントURLやパスワード、APIキーを直接書き込んでいました（ハードコーディング）。あるいは、カスタム設定（Custom Settings）やカスタムメタデータ（Custom Metadata）に認証情報を保存する方法も取られていました。これらのアプローチには、以下のような深刻な問題が潜んでいます。

セキュリティリスク：コードやメタデータ内に平文で認証情報を保存することは、情報漏洩の大きなリスクとなります。権限のないユーザーがこれらの情報にアクセスできてしまう可能性があります。
メンテナンス性の低下：外部システムの認証情報（パスワードなど）やエンドポイントURLが変更された場合、コードやメタデータを直接修正し、再度デプロイする必要があります。特に、Sandbox環境と本番環境でエンドポイントが異なる場合、環境ごとの管理が非常に煩雑になります。
コードの複雑化：認証方式（例：OAuth 2.0）によっては、アクセストークンの取得・更新といった複雑なロジックをApexで自前で実装する必要があり、開発工数が増大します。

これらの課題を解決するためにSalesforceが提供する標準機能が、Named Credential (指定ログイン情報) です。Named Credentialは、API連携におけるエンドポイントURLと認証情報を一元的に、かつ安全に管理するための仕組みです。これにより、連携エンジニアや開発者は、認証情報の管理という煩雑な作業から解放され、ビジネスロジックの実装に集中できるようになります。

例えば、以下のようなシナリオでNamed Credentialは絶大な効果を発揮します。

社内の基幹システム（ERP）から最新の在庫情報を取得する。
外部の決済代行サービスのAPIを呼び出して、クレジットカード決済を実行する。
Google Maps APIを利用して、取引先責任者の住所を地図上に表示する。

原理説明

Named Credentialの核心は、「連携先のエンドポイント定義」と「認証プロトコル」を抽象化し、Salesforceプラットフォームに管理を委任する点にあります。開発者はApexコードから、物理的なURLではなく、設定したNamed Credentialの名前を指定してAPIコールアウトを実行します。

Salesforceは、この呼び出しを受け取ると、Named Credentialに紐づけられた実際のURLと認証情報を自動的にHTTPリクエストに付与し、外部システムへの通信を実行します。この仕組みにより、コードと認証情報が完全に分離されるのです。

Named Credentialの主要な構成要素

Named Credentialを設定する際には、以下の主要な項目を定義します。

名前 (Label) / 名前 (Name): このNamed Credentialを識別するための表示名とAPI参照名です。ApexコードからはAPI参照名を使用します。
URL: 連携先APIのエンドポイントのルートURLです。（例: https://api.example.com）
ID種別 (Identity Type):
- 指定ユーザ (Named Principal): 連携に使用する認証情報を一つに固定する方式です。システム間連携のように、特定の連携用ユーザとして外部サービスにアクセスする場合に使用します。Salesforceの全ユーザがこの共通の認証情報を使ってAPIを呼び出します。
- ユーザごと (Per User): APIを呼び出すSalesforceユーザごとに、個別の認証情報を使用する方式です。例えば、各ユーザが自身のGoogle Driveアカウントに接続する場合など、ユーザ個人の権限で外部サービスを操作するシナリオに適しています。
認証プロトコル (Authentication Protocol):
- No Authentication: 認証が不要な公開APIなどで使用します。
- Password Authentication: ユーザ名とパスワードによる基本認証（Basic Authentication）や、それに類する認証方式で使用します。
- OAuth 2.0: 最も広く利用されている認証プロトコルの一つです。Salesforceがアクセストークンの取得や更新（リフレッシュトークンフロー）を自動で管理してくれるため、開発者は複雑なOAuthフローを実装する必要がありません。
- JWT / JWT Token Exchange: サーバ間でセキュアに情報を交換するためのJWT（JSON Web Token）を利用した認証フローです。

これらの設定を一度行えば、Apexからの呼び出しは非常にシンプルになります。`HttpRequest`オブジェクトのエンドポイントとして、`callout:Your_Named_Credential_Name/optional_path`という特殊な形式のURLを指定するだけです。

示例コード

ここでは、`My_ERP_System`という名前のNamed Credentialを使用して、外部のERPシステムから商品情報を取得するApexコードの例を示します。このNamed Credentialは、URLが`https://api.erp.example.com`、認証方式がパスワード認証で設定されていると仮定します。

以下のコードは、Salesforce公式ドキュメントで紹介されている標準的な実装方法です。

// 商品情報を取得するためのApexクラス
public class ProductService {

    // 商品情報を取得するメソッド
    public static String getProductInfo(String productId) {
        
        // 1. HttpRequestオブジェクトのインスタンスを作成
        HttpRequest req = new HttpRequest();

        // 2. エンドポイントを設定
        // 'callout:' プレフィックスとNamed CredentialのAPI参照名 'My_ERP_System' を使用
        // '/products/' + productId の部分が、Named CredentialのURLに追加されるパス
        req.setEndpoint('callout:My_ERP_System/products/' + productId);

        // 3. HTTPメソッドを 'GET' に設定
        req.setMethod('GET');

        // 4. HTTPオブジェクトのインスタンスを作成してリクエストを送信
        Http http = new Http();
        HttpResponse res = null;
        
        try {
            // 5. APIコールアウトを実行
            // Salesforceプラットフォームが裏側で認証ヘッダーを自動的に付与してくれる
            res = http.send(req);

            // 6. レスポンスのステータスコードを確認
            if (res.getStatusCode() == 200) {
                // 成功した場合、レスポンスボディ（JSONなど）を返す
                System.debug('成功: ' + res.getBody());
                return res.getBody();
            } else {
                // エラーが発生した場合の処理
                System.debug('エラー: ステータスコード ' + res.getStatusCode() + ' - ' + res.getStatus());
                // 実際のプロジェクトでは、カスタム例外をスローするなどのエラーハンドリングを実装
                return null;
            }
        } catch (System.CalloutException e) {
            // コールアウト例外（接続タイムアウト、DNS解決エラーなど）をキャッチ
            System.debug('コールアウト例外が発生: ' + e.getMessage());
            // エラーをログに記録するなどの処理
            return null;
        }
    }
}

このコードの最も重要な点は、`req.setEndpoint('callout:My_ERP_System/products/' + productId);` の行です。ここには実際のURLや認証情報は一切含まれていません。`My_ERP_System` という論理的な名前を指定するだけで、Salesforceが残りのすべて（URLの解決、認証ヘッダーの付与）を処理してくれます。

もし将来、ERPシステムのURLが `https://api-v2.erp.example.com` に変更されたり、パスワードが更新されたりしても、このApexコードを修正する必要は一切ありません。変更が必要なのは、Salesforceの[設定]画面にある`My_ERP_System`というNamed Credentialの定義だけです。これにより、システムは非常に高い保守性と柔軟性を獲得します。

注意事項

Named Credentialは非常に便利な機能ですが、効果的に利用するためにはいくつかの注意点を理解しておく必要があります。

権限管理

Named Credentialの作成・編集: Named Credentialを定義するには、「アプリケーションのカスタマイズ」権限が必要です。通常、この権限はシステム管理者や一部の開発者に限定されます。
ユーザごとの認証: ID種別を「ユーザごと」に設定した場合、各ユーザは[個人設定] -> [外部システムの認証設定]から、自身の認証情報を設定する必要があります。ユーザがこの設定を完了しない限り、そのユーザはAPIコールアウトを実行できません。
External Credentials (外部ログイン情報): 近年のリリースでは、Named CredentialはExternal CredentialとPrincipal (プリンシパル)という、より柔軟なコンポーネントに分割されました。External Credentialは認証プロトコルと権限セットを定義し、Named CredentialはエンドポイントとExternal Credentialへのリンクを定義します。この新しいモデルでは、権限セットを通じてAPI連携の実行権限をユーザに付与するため、より詳細なアクセス制御が可能になります。新規の連携プロジェクトでは、この新しいモデルの採用を検討すべきです。

API制限とガバナ制限

Named Credentialを使用しても、Salesforceのガバナ制限が免除されるわけではありません。1つのApexトランザクション内で実行できるコールアウトの合計数（通常100回）や、合計タイムアウト時間（通常120秒）などの制限は引き続き適用されます。大量のデータを扱う連携処理を実装する場合は、非同期処理（Queueable, Batch Apex, Futureメソッド）の利用を検討してください。

エラー処理

上記のサンプルコードにもあるように、APIコールアウトは常に成功するとは限りません。ネットワークの問題、外部システムのダウン、認証情報の誤りなど、様々な原因で失敗する可能性があります。そのため、`try-catch`ブロックによる`System.CalloutException`の捕捉と、`HttpResponse`のステータスコードのチェックは必須です。`401 Unauthorized`（認証エラー）、`403 Forbidden`（アクセス権なし）、`404 Not Found`（リソースなし）、`500 Internal Server Error`（相手側サーバエラー）など、想定されるステータスコードに応じた適切なエラーハンドリングとログ記録を実装することが、安定した連携システムを構築する鍵となります。

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

Named Credentialは、Salesforceにおける外部システム連携のセキュリティ、保守性、開発効率を劇的に向上させるための基本かつ不可欠な機能です。連携エンジニアとして、この機能を深く理解し、適切に活用することは非常に重要です。

以下に、Named Credentialを利用する上でのベストプラクティスをまとめます。

認証情報のハードコーディングは絶対に避ける: いかなる理由があっても、Apexコードやカスタムメタデータに認証情報を直接記述してはいけません。常にNamed Credentialを使用してください。
環境ごとにNamed Credentialを用意する: 開発(Dev)、ステージング(UAT)、本番(Prod)など、環境ごとに対応するNamed Credentialを作成します。これにより、Apexコードを変更することなく、デプロイ先の環境に応じた適切なエンドポイントに接続できます。
適切なID種別を選択する: システム全体で共通の認証情報を使う場合は「指定ユーザ」を、実行ユーザ個人の権限でAPIを呼び出す必要がある場合は「ユーザごと」を選択します。要件に合わない選択をすると、セキュリティ上の問題や意図しない動作につながる可能性があります。
最新の機能（External Credentials）を検討する: 新規開発においては、権限セットベースのアクセス制御が可能なExternal Credentialsモデルの利用を積極的に検討しましょう。これにより、よりセキュアで管理しやすい連携アーキテクチャを設計できます。
堅牢なエラーハンドリングとロギングを実装する: 外部連携は失敗する可能性があることを前提に設計します。どのAPIコールで、どのようなエラーが発生したかを追跡できるよう、詳細なログを記録する仕組みを必ず実装してください。

これらのベストプラクティスを遵守することで、Salesforceと外部システム間の連携を安全かつ効率的に構築し、ビジネスの要求に迅速に対応できる、スケーラブルなソリューションを実現できるでしょう。

にゃんこのSalesforce日記

このブログを検索