> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.jp/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuthの利用 | OAuthクイックスタートガイド

> このクイックスタートガイドとNode.jsのサンプルアプリを使って、アプリのOAuthを設定する方法をご紹介します。

<style>
  {`
    .github-link a div,
    .github-link a div p {
      display: inline;
      margin: 0;
      padding: 0;
    }
    .github-link {
      background-color: rgb(255, 255, 255);
      border-radius: 24px;
      box-shadow: rgba(0, 0, 0, 0.25) 0px 2px 4px 0px;
      padding: 5px;
      max-width: 247px;
      display: flex;
      align-items: center;
      margin-bottom: 20px;
    }
    .github-icon {
        display: inline;
        width: 24px;
        margin-right: 8px;
        flex-shrink: 0;
    }
    .table-key, .table-key div, .table-key p {
      margin: 0;
      font-size: 14px;
    }
    `}
</style>

## 始める前に

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

* [開発者アカウント](https://app.hubspot.com/signup-hubspot/developers)
* 開発者アカウントに関連付けられている[アプリ](/apps/legacy-apps/public-apps/overview)
* アプリをインストールするためのHubSpotアカウント（既存のアカウントを使用するか、または[テストアカウントを作成する](/getting-started/account-types)ことができます）

<Warning>
  HubSpotアカウント上にアプリをインストールするには、[スーパー管理者](https://knowledge.hubspot.com/ja/user-management/hubspot-user-permissions-guide#super-admin)の権限が必要です。
</Warning>

### 仕組み

HubSpotは、[OAuth 2.0認証コード付与方式](https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type)に対応しています。この処理は次の4つの基本ステップに分けることができます。

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

### このガイドの内容

* [クイックスタートアプリ](#quickstart-app)：HubSpotのOAuth 2.0サーバーで認証されるNode.jsデモアプリ
* [OAuthトークンの取得](#getting-oauth-tokens)：アプリでユーザーを認証する方法
* [OAuthトークンの使用](#using-oauth-tokens)：トークンによりクエリーを実行する方法
* [OAuthトークンのリフレッシュ](#refreshing-oauth-tokens)：HubSpotで提供されるリフレッシュトークンの使い方

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

## クイックスタートアプリ

HubSpotのAPIでOAuth認証を初めて使用する場合、Node.jsで記述されている[OAuth 2.0クイックスタートアプリ](https://github.com/HubSpot/oauth-quickstart-nodejs)（英語）を確認することを強くお勧めします。このサンプルアプリは、OAuth 2.0をできるだけ早く使い始められるように設計されており、後述の[OAuthトークンの取得](#getting-oauth-tokens)セクションに記載の全ての手順を実際に示しています。

<Card title="クイックスタートアプリを確認する" href="https://github.com/HubSpot/oauth-quickstart-nodejs" icon="github" horizontal />

## OAuthトークンの取得

### 1. 認証URLを作成し、ユーザーをHubSpotのOAuth 2.0サーバーに導く

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

<p className="table-key">
  <span style={{ color: 'red' }}>\*</span>でマークされたフィールドは必須です。
</p>

| パラメーター                                              | 説明                                                                                                               | 例                                       |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `client_id`<span style={{color:"red"}}>\*</span>    | クライアントIDによってアプリが識別されます。アプリの設定ページで確認します。                                                                          | `7fff1e36-2d40-4ae1-bbb1-5266d59564fb`  |
| `scope`<span style={{color:"red"}}>\*</span>        | URLエンコードされたスペース（`%20`）で区切られた、アプリが要求している[スコープ](/apps/legacy-apps/authentication/scopes#list-of-available-scopes)。 | `oauth%20crm.objects.contacts.read`     |
| `redirect_uri`<span style={{color:"red"}}>\*</span> | アプリが要求したスコープの認証後にユーザーがリダイレクトされるURL\*\*。本番環境アプリでは、`https`が必須です\*\*。                                               | `https://www.example.com/auth-callback` |
| `optional_scope`                                    | アプリにとって任意のスコープ。選択されたHubSpotポータルがその製品にアクセスできない場合は破棄されます。                                                          | `automation`                            |
| `state`                                             | リダイレクトされてアプリに戻ってきたユーザーの状態を維持するために使用できる一意の文字列値。                                                                   | `WeHH_yy2irpl8UYAvv-my`                 |

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

以下のコードブロックは、さまざまなリダイレクトタイプの使用例を示しています。

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

```js theme={null}
// 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リンクを使用**:

```html theme={null}
<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サービスに関する簡単な説明を含む同意ウィンドウをユーザーに提示します。ここで、ユーザーはアプリにアクセス権を付与できます。

<Frame>
  <img src="https://www.hubspot.jp/hubfs/Knowledge_Base_2023/%5BExample%5D%20Install%20Screen.png" alt="インストールプロンプトウィンドウの例" />
</Frame>

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

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

### 3. OAuthサーバーのレスポンスを処理する

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

**例**:

```js theme={null}
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`に送信します（以下に記載の値を使用）。このステップの詳細については、この[リファレンスドキュメント](/api-reference/auth-oauth-v1/guide)を参照してください。

| パラメーター          | 説明                             | 例                                       |
| --------------- | ------------------------------ | --------------------------------------- |
| `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`  |

**例**:

```js theme={null}
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データになります。

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

<Warning>
  ### 注：

  アクセストークンは、レスポンスの`expires_in`フィールドで示された秒数の経過後に期限切れになります（現時点では30分）。新しいアクセストークンの取得の詳細については、後述の[OAuthトークンのリフレッシュ](#refreshing-oauth-tokens)セクションをご参照ください。
</Warning>

## OAuthトークンの使用

認証コードのフローが完了すると、ユーザーに代わってリクエストを行う権限がアプリに付与されます。これを行うには、トークンをベアラートークンとして`Authorization` HTTPヘッダーに指定します。具体的には、[リファレンスドキュメント](/api-reference/auth-oauth-v1/guide)で確認できます。

**例**:

```js theme={null}
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
  }
);
```

<Warning>
  ### 注：

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

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

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

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

| パラメーター          | 説明                             | 例                                       |
| --------------- | ------------------------------ | --------------------------------------- |
| `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`  |

**例**:

```js theme={null}
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データになります。

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

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

## 関連記事

[HubSpotでの認証方式](/apps/legacy-apps/authentication/intro-to-auth)

[OAuthの利用](/apps/legacy-apps/authentication/working-with-oauth)

[トークンを管理する](/api-reference/auth-oauth-v1/guide)