始める前に
HubSpotでOAuthを使用するには、次のものが必要です。
HubSpotアカウント上にアプリをインストールするには、スーパー管理者の権限が必要です。 仕組み
HubSpotは、OAuth 2.0認証コード付与方式に対応しています。この処理は次の4つの基本ステップに分けることができます。
- アプリによってブラウザーウィンドウを開き、ユーザーをHubSpot OAuth 2.0サーバーに導く
- 要求された権限をユーザーが確認し、アプリにアクセス権を付与する
- クエリー文字列の中に認証コードを指定した状態で、ユーザーがアプリにリダイレクトされる
- アプリが、アクセストークンの認証コードを交換するためのリクエストをOAuth 2.0サーバーに送信する
このガイドの内容
このガイドの全てのコードサンプルは、JavaScript（Node.js）で記述されています
クイックスタートアプリ
HubSpotのAPIでOAuth認証を初めて使用する場合、Node.jsで記述されているOAuth 2.0クイックスタートアプリ（英語）を確認することを強くお勧めします。このサンプルアプリは、OAuth 2.0をできるだけ早く使い始められるように設計されており、後述のOAuthトークンの取得セクションに記載の全ての手順を実際に示しています。
OAuthトークンの取得
1. 認証URLを作成し、ユーザーをHubSpotのOAuth 2.0サーバーに導く
HubSpotのOAuth 2.0サーバーにユーザーを導くための最初のステップは、認証URLの作成です。これによりアプリが特定されると共に、ユーザーに代わってアクセス権を求めるリソース（スコープ）が定義されます。認証URLの一部として指定できるクエリーパラメーターを以下の表に示します。このステップの詳細については、リファレンスドキュメントを参照してください。
*でマークされたフィールドは必須です。
| パラメーター | 説明 | 例 |
|---|
client_id* | クライアントIDによってアプリが識別されます。アプリの設定ページで確認します。 | 7fff1e36-2d40-4ae1-bbb1-5266d59564fb |
scope* | URLエンコードされたスペース（%20）で区切られた、アプリが要求しているスコープ。 | oauth%20crm.objects.contacts.read |
redirect_uri* | アプリが要求したスコープの認証後にユーザーがリダイレクトされるURL**。本番環境アプリでは、httpsが必須です**。 | https://www.example.com/auth-callback |
optional_scope | アプリにとって任意のスコープ。選択されたHubSpotポータルがその製品にアクセスできない場合は破棄されます。 | automation |
state | リダイレクトされてアプリに戻ってきたユーザーの状態を維持するために使用できる一意の文字列値。 | WeHH_yy2irpl8UYAvv-my |
// 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);
<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の同意確認を完了すると、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
}
{
"refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1",
"access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I",
"expires_in": 1800
}
アクセストークンは、レスポンスのexpires_inフィールドで示された秒数の経過後に期限切れになります（現時点では30分）。新しいアクセストークンの取得の詳細については、後述のOAuthトークンのリフレッシュセクションをご参照ください。 OAuthトークンの使用
認証コードのフローが完了すると、ユーザーに代わってリクエストを行う権限がアプリに付与されます。これを行うには、トークンをベアラートークンとして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トークンのリフレッシュ
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
}
{
"refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1",
"access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I",
"expires_in": 1800
}
関連記事
HubSpotでの認証方式
OAuthの利用
トークンを管理する
