OAuthクイックスタートガイド

始める前に

HubSpotでOAuthを使用するには、次のものが必要です。

*HubSpotアカウント上にアプリをインストールするには、スーパー管理者の権限が必要です

仕組み

HubSpotは、OAuth 2.0認証コード付与方式に対応しています。この処理は次の4つの基本ステップに分けることができます。

  1. アプリによってブラウザーウィンドウを開き、ユーザーをHubSpot OAuth 2.0サーバーに導く
  2. 要求された権限をユーザーが確認し、アプリにアクセス権を付与する
  3. クエリー文字列の中に認証コードを指定した状態で、ユーザーがアプリにリダイレクトされる
  4. アプリが、アクセストークンの認証コードを交換するためのリクエストをOAuth 2.0サーバーに送信する
 

このガイドの内容

注：このガイドの全てのコードサンプルは、JavaScript（Node.js）で記述されています

 

クイックスタートアプリ

HubSpotのAPIでOAuth認証を初めて使用する場合、Node.jsで記述されているOAuth 2.0クイックスタートアプリ（英語）を確認することを強くお勧めします。このサンプルアプリは、OAuth 2.0の利用をできるだけ短時間で開始することを意図して設計されており、後述のOAuth 2.0トークンの取得に記載の全ての手順を実際に使用しています。

OAuth 2.0トークンの取得

ステップ1：認証URLを作成し、ユーザーをHubSpotのOAuth 2.0サーバーに導く

HubSpotのOAuth 2.0サーバーにユーザーを導くための最初のステップは、認証URLの作成です。これによりアプリが特定されると共に、ユーザーに代わってアクセス権を求めるリソース（スコープ）が定義されます。認証URLの一部として指定できるクエリーパラメーターは、以下のとおりです。このステップの詳細については、リファレンスドキュメントを参照してください。

認証URLクエリーパラメーター
パラメーター 必須 説明 例
client_id はい クライアントIDによってアプリが識別されます。アプリの設定ページで確認します。

7fff1e36-2d40-4ae1-bbb1-5266d59564fb
scope はい アプリが要求しているスコープ（URLエンコードのスペース区切り）。

contacts%20social
redirect_uri はい アプリが要求したスコープの認証後にユーザーがリダイレクトされるURL。本番環境アプリでは、httpsが必須です。

https://www.example.com/auth-callback
optional_scope いいえ アプリにとって任意のスコープ。選択されたHubSpotポータルがその製品にアクセスできない場合は破棄されます。

automation
state いいえ リダイレクトされてアプリに戻ってきたユーザーの状態を維持するために使用できる一意の文字列値。

WeHH_yy2irpl8UYAvv-my

URLを作成したら、URLにユーザーを誘導してOAuth 2.0プロセスを開始します。

例

サーバーサイドのリダイレクトを使用：

// Build the auth URL const authUrl = 'https://app.hubspot.com/oauth/authorize' + `?client_id=${encodeURIComponent(CLIENT_ID)}` + `&scope=${encodeURIComponent(SCOPES)}` + `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`; + `&state=${encodeURIComponent(STATE)}`; // Redirect the user return res.redirect(authUrl);

HTMLリンクを使用：

<a href="https://app.hubspot.com/oauth/authorize?scope=contacts%20social&redirect_uri=https://www.example.com/auth-callback&client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&state=xxxxxxxx">Install</a>
追加のリダイレクトユーザー状態をエンコードする

一部のアプリでは、ユーザーを別の場所にリダイレクトしなければならない場合があります。例えば、アプリによっては、連携されている別のサブドメイン（userA.integration.comやuserB.integration.comなど）にリダイレクトする必要がある場合があります。これを行うには、stateパラメーターを使用して、ユーザー状態に関する詳細情報をエンコードします。 

1. stateパラメーターのnonce値を生成して保存します。

2. nonceをキーとして使用して、ユーザーの状態をローカルデータストアに保存します。

3. 認証URLに、状態パラメーターとしてnonce値を含めます。 

4. ユーザーが認証され、リダイレクトURLにリダイレクトされたら、stateパラメーターを検証し、保存されたユーザー状態を取得するためのキーとして使用します。 

5. そこから、必要に応じてユーザーをリダイレクトします（例：ユーザー固有のURLに再度リダイレクトする）。

ステップ2：HubSpotがユーザーに同意を求める

HubSpotは、アプリの名前と、アプリがアクセス権限を要求しているHubSpot APIサービスに関する簡単な説明を含む同意ウィンドウをユーザーに提示します。ここで、ユーザーはアプリにアクセス権を付与できます。

［例］インストール画面

注：アプリをインストールするユーザーは、要求された全てのスコープに対するアクセス権を持っている必要があります。必要なアクセス権を持っていない場合は、インストールが失敗し、エラーページが表示されます。この権限エラーページが表示された場合は、スーパー管理者にアプリのインストールを依頼する必要があります。

この段階でアプリが行う処理はありません。アクセス権が付与されると、HubSpot OAuth 2.0サーバーが、認証URLで定義されたコールバックURIにリクエストを送信します。

ステップ3：OAuth 2.0サーバーのレスポンスを処理する

ユーザーがステップ2の同意確認を完了すると、OAuth 2.0サーバーはGETリクエストを認証URLで指定されたリダイレクトURIに送信します。問題が発生せず、ユーザーがアクセス要求を承認した場合、リダイレクトURIに対するリクエストがcodeクエリーパラメーター付きで返されます。ユーザーがアクセス権を付与しなかった場合、リクエストは送信されません。

例：
app.get('/oauth-callback', async (req, res) => { if (req.query.code) { // Handle the received code } });

ステップ4：認証コードをトークンと交換する

アプリはOAuth 2.0サーバーから認証コードを受け取ったら、コードをアクセス／リフレッシュトークンと交換できます。そのためには、URL形式でエンコードされたPOSTリクエストをhttps://api.hubapi.com/oauth/v1/tokenに送信します（以下に記載の値を使用）。このステップの詳細については、このリファレンスドキュメントを参照してください。

パラメーター 説明 例
grant_type authorization_codeでなければなりません authorization_code
client_id アプリのクライアントID 7fff1e36-2d40-4ae1-bbb1-5266d59564fb
client_secret アプリのクライアントシークレット 7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d
redirect_uri ユーザーがアプリを認証した場合のリダイレクトURI https://www.example.com/auth-callback
code OAuth 2.0サーバーから受信した認証コード 5771f587-2fe7-40e8-8784-042fb4bc2c31
例：
const formData = { grant_type: 'authorization_code', client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, code: req.query.code }; request.post('https://api.hubapi.com/oauth/v1/token', { form: formData }, (err, data) => { // Handle the returned tokens }

トークンレスポンスの本文は、次の形式のJSONデータになります。

{"refresh_token":"6f18f21e-a743-4509-b7fd-1a5e632fffa1","access_token":"CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I","expires_in":1800}

注：アクセストークンは、レスポンスのexpires_inフィールドで示された秒数の経過後に期限切れになります（現時点では30分）。新しいアクセストークンの取得方法については、OAuth 2.0トークンのリフレッシュを参照してください。

OAuth 2.0トークンの使用

認証コードのフローが完了すると、ユーザーに代わってリクエストを行う権限がアプリに付与されます。そのためには、トークンをベアラートークンとしてAuthorization HTTPヘッダーの中に指定します。具体的には、リファレンスドキュメントで確認できます。

例：
request.get('https://api.hubapi.com/contacts/v1/lists/all/contacts/all?count=1', { headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' } }, (err, data) => { // Handle the API response } );

注：アクセストークンは、アプリから要求されたスコープを反映しますが、ユーザーがHubSpotアカウントで実行できる操作に関する権限や制限を反映することはありません。例えば、担当するコンタクトのみを表示する権限を持つユーザーが、crm.objects.contacts.readスコープに対する要求を許可した場合、生成されるアクセストークンでは、許可したユーザーの担当するコンタクトだけでなく、アカウント内の全てのコンタクトを表示できます。 

OAuth 2.0トークンのリフレッシュ

OAuthアクセストークンは定期的に有効期限が切れます。これは、トークンが侵害されても、攻撃者によるアクセスを極力短時間に限定するためです。トークンの利用可能な秒数は、認証コードがアクセストークンと交換された時点で、expires_inフィールドに指定されます。

アプリは受信したリフレッシュトークンを新しいアクセストークンと交換できます。そのためには、URL形式でエンコードされたPOSTリクエストをhttps://api.hubapi.com/oauth/v1/tokenに送信します。その際に、以下の値を使用します。このステップの詳細については、リファレンスドキュメントを確認してください。

パラメーター 説明 例
grant_type refresh_tokenでなければなりません refresh_token
client_id アプリのクライアントID 7fff1e36-2d40-4ae1-bbb1-5266d59564fb
client_secret アプリのクライアントシークレット 7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d
redirect_uri ユーザーがアプリを認証した場合のリダイレクトURI https://www.example.com/auth-callback
refresh_token ユーザーがアプリを認証したときに受け取るリフレッシュトークン b9443019-30fe-4df1-a67e-3d75cbd0f726
例：
const formData = { grant_type: 'refresh_token', client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, refresh_token: REFRESH_TOKEN }; request.post('https://api.hubapi.com/oauth/v1/token', { form: formData }, (err, data) => { // Handle the returned tokens }

トークンレスポンスの本文は、次の形式のJSONデータになります。

// Sample response { "refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1", "access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I", "expires_in": 1800 }

この新しいアクセストークンを、ユーザーの代わりに呼び出しを行う際に使用します。新しいトークンの有効期限が切れたら、同じ手順を繰り返して新たにトークンを取得できます。

 

関連ドキュメント

HubSpotでの認証方式

OAuthの利用

トークンを管理する