OAuthクイックスタートガイド
始める前に
HubSpotでOAuthを使用するには、次のものが必要です。
- 開発者アカウント
- 開発者アカウントに関連付けられているアプリ
- アプリをインストールするためのHubSpotアカウント*(既存のアカウントを使用するか、またはテストアカウントを作成することができます)
*HubSpotアカウント上にアプリをインストールするには、スーパー管理者の権限が必要です
仕組み
HubSpotは、OAuth 2.0認証コード付与方式に対応しています。この処理は次の4つの基本ステップに分けることができます。
- アプリによってブラウザーウィンドウを開き、ユーザーをHubSpot OAuth 2.0サーバーに導く
- 要求された権限をユーザーが確認し、アプリにアクセス権を付与する
- クエリー文字列の中に認証コードを指定した状態で、ユーザーがアプリにリダイレクトされる
- アプリが、アクセストークンの認証コードを交換するためのリクエストをOAuth 2.0サーバーに送信する
このガイドの内容
- クイックスタートアプリ:HubSpotのOAuth 2.0サーバーで認証されるNode.jsデモアプリ
- OAuth 2.0トークンの取得:アプリでユーザーを認証する方法
- OAuth 2.0トークンの使用:トークンによりクエリーを実行する方法
- OAuth 2.0トークンのリフレッシュ:HubSpotで提供されるリフレッシュトークンの使い方
注:このガイドの全てのコードサンプルは、JavaScript(Node.js)で記述されています
クイックスタートアプリ
HubSpotのAPIでOAuth認証を初めて使用する場合、Node.jsで記述されているOAuth 2.0クイックスタートアプリ(英語)を確認することを強くお勧めします。このサンプルアプリは、OAuth 2.0の利用をできるだけ短時間で開始することを意図して設計されており、後述のOAuth 2.0トークンの取得に記載の全ての手順を実際に使用しています。
- Githubでアプリを取得する(英語)
OAuth 2.0トークンの取得
ステップ1:認証URLを作成し、ユーザーをHubSpotのOAuth 2.0サーバーに導く
HubSpotのOAuth 2.0サーバーにユーザーを導くための最初のステップは、認証URLの作成です。これによりアプリが特定されると共に、ユーザーに代わってアクセス権を求めるリソース(スコープ)が定義されます。認証URLの一部として指定できるクエリーパラメーターは、以下のとおりです。このステップの詳細については、リファレンスドキュメントを参照してください。
パラメーター | 必須 | 説明 | 例 |
---|---|---|---|
client_id |
はい | クライアントIDによってアプリが識別されます。アプリの設定ページで確認します。 |
|
scope |
はい | アプリが要求しているスコープ(URLエンコードのスペース区切り)。 |
|
redirect_uri |
はい | アプリが要求したスコープの認証後にユーザーがリダイレクトされるURL。本番環境アプリでは、httpsが必須です。 |
|
optional_scope |
いいえ | アプリにとって任意のスコープ。選択されたHubSpotポータルがその製品にアクセスできない場合は破棄されます。 |
|
state |
いいえ | リダイレクトされてアプリに戻ってきたユーザーの状態を維持するために使用できる一意の文字列値。 |
|
URLを作成したら、URLにユーザーを誘導してOAuth 2.0プロセスを開始します。
例
サーバーサイドのリダイレクトを使用:
HTMLリンクを使用:
追加のリダイレクトユーザー状態をエンコードする
一部のアプリでは、ユーザーを別の場所にリダイレクトしなければならない場合があります。例えば、アプリによっては、連携されている別のサブドメイン(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
クエリーパラメーター付きで返されます。ユーザーがアクセス権を付与しなかった場合、リクエストは送信されません。
例:
ステップ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 |
例:
トークンレスポンスの本文は、次の形式のJSONデータになります。
注:アクセストークンは、レスポンスのexpires_in
フィールドで示された秒数の経過後に期限切れになります(現時点では30分)。新しいアクセストークンの取得方法については、OAuth 2.0トークンのリフレッシュを参照してください。
OAuth 2.0トークンの使用
認証コードのフローが完了すると、ユーザーに代わってリクエストを行う権限がアプリに付与されます。そのためには、トークンをベアラートークンとしてAuthorization
HTTPヘッダーの中に指定します。具体的には、リファレンスドキュメントで確認できます。
例:
注:アクセストークンは、アプリから要求されたスコープを反映しますが、ユーザーが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 |
例:
トークンレスポンスの本文は、次の形式のJSONデータになります。
この新しいアクセストークンを、ユーザーの代わりに呼び出しを行う際に使用します。新しいトークンの有効期限が切れたら、同じ手順を繰り返して新たにトークンを取得できます。