APIキー連携を非公開アプリ(Private App)に移行する

HubSpot APIキーを使用する内部連携を構築した場合、APIキーは全てのHubSpot CRMデータに対する読み取りアクセス権と書き込みアクセス権の両方を提供しますが、これは、APIキーが侵害された場合にセキュリティー上のリスクをもたらす可能性があります。非公開アプリに移行することにより、連携が必要とする特定のスコープを認証できます。これにより、アカウント内で連携がリクエストしたり変更したりできるデータを制限する、アクセストークンが生成されます。

さらに、APIキーではトークンの更新が必要ですが、非公開アプリ(Private App)のアクセストークンは更新が不要です。したがって、アプリにトークンの更新処理を組み込む必要がありません。

既存のAPIキー連携を非公開アプリ(Private App)に移行するには、次の手順に従います。本番環境で変更する前に、まず開発者テストアカウントサンドボックスアカウントなどのテスト環境を使用することをお勧めします。

このガイドの内容

注:非公開アプリ(Private App)では、拡張機能、カスタム タイムライン イベント、Webhookはサポートされていません。既存の連携でこれらの機能のいずれかを使用している場合は、代わりにOAuthを使用する公開アプリを作成する必要があります。

新しい非公開アプリを作成する

  • HubSpotアカウントで、メイン ナビゲーション バーにある設定アイコンをクリックします。
  • 左のサイドバーメニューで、[連携]>[非公開アプリ]の順に進みます。
  • [非公開アプリを作成]をクリックします。
  • [基本情報]タブで、アプリの詳細を設定します。
    • アプリの名前を入力します。
    • プレースホルダーロゴの上にカーソルを置き、アップロードアイコンをクリックして、アプリのロゴとして機能する正方形の画像をアップロードします。
    • アプリの説明を入力します。
  • [スコープ]タブをクリックします。
  • 次に、連携で使用しているAPIに基づいて、認証するスコープを選択します。アプリに必要なスコープを見つけるには、次の手順に従います。
    • 既存の連携で使用しているHubSpot APIのリストを作成します。
    • APIリクエストごとに、関連する開発者ドキュメント(コンタクトAPIなど)に移動します。
    • [エンドポイント]タブをクリックし、連携で使用しているエンドポイントまでスクロールします。
    • [必要な条件]セクションで、エンドポイントを使用するために必要なスコープを見つけます。可能な場合は常に、[標準スコープ]に表示されているスコープではなく、[詳細スコープ]に表示されているスコープを選択してください。きめ細かいスコープがない場合は、標準スコープを使用してください。locate-scope-in-endpoints-tab-for-private-app-migration
    • 非公開アプリの設定に戻り、一致するスコープの横にある[読み取り]または[書き込み]チェックボックスをオンにします。[スコープを検索]検索バーを使用してスコープを探すこともできます。select-matching-scope-for-private-app
  • スコープの選択が完了したら、右上の[アプリを作成]をクリックします。アプリ作成後、いつでもアプリに変更を加えることができます。
  • ダイアログボックスで、アプリのアクセストークンの情報を確認してから、[作成を続行]をクリックします。

非公開アプリを作成したら、そのアクセストークンを使用してAPIリクエストを開始できます。非公開アプリの設定ページの[詳細]タブで、アクセストークンの下の[トークンを表示]をクリックすると、トークンが表示されます。

show-private-app-access-token-migration-guide

連携のAPIリクエストの認証方式を更新する

hapiKeyクエリーパラメーターを使用してAPIリクエストを行う代わりに、リクエストのAuthorizationヘッダーに非公開アプリのアクセストークンを含めます。リクエストを行うときは、Authorizationヘッダーの値をBearer YOUR_ACCESS_TOKENに設定します。

例えば、Node.jsとaxiosライブラリーを使用してコンタクトAPIを呼び出す場合、リクエストは次のようになります。

axios.get('https://api.hubapi.com/crm/v3/objects/contacts', { headers: { 'Authorization': `Bearer ${YOUR_ACCESS_TOKEN}`, 'Content-Type': 'application/json' } }, (err, data) => { // Handle the API response } );

非公開アプリのアクセストークンはOAuthを基盤として実装されるので、HubSpotのクライアントライブラリーのいずれかを使用して、アクセストークンで認証された呼び出しを行うこともできます。例えば、Node.jsクライアントライブラリーを使用している場合は、アプリのアクセストークンを渡すことにより、OAuthクライアントをインスタンス化できます。

const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN });

非公開アプリへの移行を完了するには、コードからHubSpot APIキーへの参照を全て削除し、代わりに上記のアプローチに従って非公開アプリのアクセストークンを使用します。リクエストにトークンをハードコーディングするのではなく、実行するリクエストに応じて、トークンを格納するシークレットを作成します。シークレットを使用すると、サーバーレス関数でトークンを使用するときなどに、トークンが公開されることを防止できます。アクセストークンをシークレットとして格納するには、次の手順に従います。

  • ターミナルで、hs secrets add secretNameを実行します。シークレットの名前は、その後簡単に参照できるように、シンプルなものにすることをお勧めします。
  • アクセストークンをターミナルに貼り付けて、Enterキーを押します。

その後は、環境変数としてシークレットにアクセスできます。詳しくは、後述のサーバーレス関数の例をご確認ください。

APIキーへの参照が全て削除されたことを確認するには、HubSpotアカウントのコールログをチェックします。

  • HubSpotアカウントで、メイン ナビゲーション バーにある設定アイコンをクリックします。
  • 左のサイドバーで、[連携]>[APIキー]の順に進みます。
  • [コールログ]タブで最近のリクエストをチェックし、非公開アプリのアクセストークンを使用するために以前の参照を全て削除して以降、リクエストが実行されていないことを確認します。

check-api-key-call-log-after-migrationコードからAPIキーへの参照が全て削除されたことを確認したら、キーを無効化できます。

リクエストを検証し、ログを監視する

コードからHubSpot APIキーへの参照を全て削除し、それらを非公開アプリのアクセストークンへの参照に置き換えたら、それ以上のコードの変更は不要です。

開発者テストアカウントまたはサンドボックスアカウントで上記の手順を実施したら、本番アカウントで同じプロセスを再現します。次に、非公開アプリのAPIコールログを監視し、アプリの全てのリクエストが400エラーを返していないことを確認します。

  • HubSpotアカウントで、メイン ナビゲーション バーにある設定アイコンをクリックします。
  • 左のサイドバーメニューで、[連携]>[非公開アプリ]の順に進みます。
  • 非公開アプリの名前をクリックします。
  • [ログ]タブをクリックします。
  • スコープが欠けているために失敗したAPIリクエストについては、403エラーが表示されます。連携のランタイムログにアクセスする場合は、対応するAPIリクエストに対するレスポンスに、欠けているスコープの詳細を示すエラーメッセージが含まれている必要があります。

403-error-after-private-app-migration

  • 非公開アプリに新しいスコープを含める必要がある場合は、次の手順に従います。
    • [詳細]タブをクリックします。
    • [詳細を編集]をクリックします。
    • ページの最上部にある[スコープ]をクリックします。
    • 欠けているスコープの横のチェックボックスを全てオンにしたら、右上の[変更をコミット]をクリックします。

select-missing-scopes-private-app-migration

非公開アプリの作成と管理、および非公開アプリの制限については、非公開アプリのガイドをご確認ください。

実装の例

以下では、一般的なAPIキーの使用方法と、APIキーを非公開アプリのアクセストークンに移行する方法について詳しく説明します。

サーバーレス関数

サーバーレス関数内でAPIキーを使用している場合は、上記と同様に、非公開アプリのアクセストークンを認証に使用できます。関数が実行する必要があるスコープが非公開アプリに存在することを確認してください。 

非公開アプリのアクセストークンを使用してサーバーレス関数を認証するには、次の手順に従います。

  • 「アクセストークン」カードで、[トークンを表示]をクリックしてアクセストークンを表示します。次に、[コピー]をクリックして、トークンをクリップボードにコピーします。
    show-private-app-access-token-1
  • アクセストークンをコピーした状態のまま、そのトークンを保存するための新しいシークレットを作成します。
    • ターミナルで、hs secrets add secretNameを実行します。シークレットの名前は、その後簡単に参照できるように、シンプルなものにすることをお勧めします。
    • アクセストークンをターミナルに貼り付けて、Enterキーを押します。
  • サーバーレス関数のserverless.jsonファイルで、secrets配列にシークレット名を追加します。
// example serverless.json file { "runtime": "nodejs12.x", "version": "1.0", "secrets": ["secretName"], "endpoints": { "getPrompts": { "method": "GET", "file": "serverlessFunction.js" } } }
  • サーバーレス関数のJavaScriptファイルで、Authorizationヘッダーの値をBearer secretNameに設定します。例えば、Node.jsとaxiosを使用してコンタクトAPIを呼び出す場合、リクエストは次のようになります。
// example serverless function const axios = require('axios'); exports.main = (context, sendResponse) => { axios.get(`https://api.hubapi.com/crm/v3/objects/contacts`, { headers: { 'Authorization': `Bearer ${process.env.secretName}`, 'Content-Type': 'application/json' } } ) sendResponse({statusCode: 200}); };

アプリのトークンを使用してAPIを呼び出す方法について詳細をご確認ください。

1回限りのジョブ

プロパティーの作成のような1回限りのジョブを実行するためにAPIキーを使用している場合は、代わりに非公開アプリを作成して、そのアクセストークンでコールを認証できます。非公開アプリを作成すると、非公開アプリに適切なスコープが存在する限り、そのアクセストークンを任意の1回限りのジョブで再利用できます。非公開アプリのスコープは、HubSpotの非公開アプリの設定から、いつでも更新できます。または、非公開アプリを削除して、実行する必要があるジョブに固有の新しい非公開アプリを作成することもできます。

private-app-edit-scopes

カスタムオブジェクトの作成

APIキーを使用してカスタムオブジェクトを作成する代わりに、非公開アプリを作成して、そのアクセストークンでコールを認証できます。ただし、必要なスコープが非公開アプリに存在することが条件となります。例えば、Postmanを使用してカスタムオブジェクトを作成する場合は、認証タイプをBearerトークンに設定し、[トークン]フィールドにトークンを入力します。

postman-private-app-access-token-field

 

カスタム コード ワークフロー アクション

「カスタムコード」ワークフローアクションでAPIキーを使用している場合は、代わりに非公開アプリのアクセストークンを使用できます。ただし、必要なスコープが非公開アプリに存在することが条件となります。更新するには、ワークフローエディターでカスタムアクションを開き、次の変更を行います。

const hubspotClient = new hubspot.Client({ accessToken: process.env.secretName });