メインコンテンツまでスキップ

Setting Up Gmail OAuth Authentication

このガイドでは、Gmail との OAuth 認証用の Google Cloud アプリケーションの作成手順を説明します。OAuth は従来のパスワード認証に比べて Gmail アカウントへのセキュアなアクセスを提供します。

Prerequisites​

  • Google アカウント（個人または Google Workspace）
  • Google Cloud Console へのアクセス
  • Perfex CRM のインストール URL（redirect URI 設定用）

Step-by-Step Setup​

Step 1: Create a Google Cloud Project​

  1. Google Cloud Console にアクセス
  2. ページ上部のプロジェクトドロップダウンをクリック
  3. "New Project" をクリック
  4. プロジェクト名を入力（例: "Perfex Mailbox OAuth"）
  5. "Create" をクリック
  6. プロジェクト作成を待ち、選択

Step 2: Enable Gmail API​

  1. Google Cloud Console で "APIs & Services" > "Library" に移動
  2. "Gmail API" を検索
  3. 結果から "Gmail API" をクリック
  4. "Enable" をクリック
  5. API が有効になるまで待つ
  1. "APIs & Services" > "OAuth consent screen" に移動
  2. "External" ユーザータイプを選択（Google Workspace アカウントの場合は "Internal" を選択可能）
  3. "Create" をクリック
  4. 必須情報を入力:
    • App name: アプリ名（例: "Perfex CRM Mailbox"）
    • User support email: メールアドレス
    • Developer contact information: メールアドレス
  5. "Save and Continue" をクリック
  6. "Scopes" ページで "Add or Remove Scopes" をクリック
  7. 以下のスコープを追加:
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/gmail.send
    • https://www.googleapis.com/auth/gmail.modify
  8. "Update" をクリックし、"Save and Continue"
  9. "Test users" ページ（External アプリタイプの場合）:
    • Gmail アドレスをテストユーザーとして追加
    • "Save and Continue" をクリック
  10. 確認して "Back to Dashboard" をクリック

Step 4: Create OAuth 2.0 Credentials​

  1. "APIs & Services" > "Credentials" に移動
  2. "Create Credentials" > "OAuth client ID" をクリック
  3. アプリケーションタイプで "Web application" を選択
  4. OAuth クライアント名を入力（例: "Perfex Mailbox Client"）
  5. "Authorized redirect URIs" で "Add URI" をクリック
  6. 以下の形式で redirect URI を追加:
https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail

your-domain.com を実際の Perfex CRM ドメインに置き換えてください。

  1. "Create" をクリック
  2. 重要: 両方をコピーして保存:
    • Client ID
    • Client Secret（「Show」をクリックして表示）

Step 5: Configure in Perfex CRM​

  1. Perfex CRM 管理画面に移動
  2. Mailbox > Configuration に移動
  3. 認証方法として "OAuth2" を選択
  4. プロバイダーとして "Gmail" を選択
  5. "Gmail Client ID" フィールドに Client ID を入力
  6. "Gmail Client Secret" フィールドに Client Secret を入力
  7. "Save Configuration" をクリック
  8. "Connect Gmail" ボタンをクリック
  9. Google ポップアップウィンドウでアプリケーションを承認
  10. 接続確認の成功メッセージが表示されます

Important Limitations & Considerations​

Google Test App Limitations​

These limitations are imposed by Google, not by our software.

  1. Token Expiry (7 Days) - 未検証アプリ（テストモードのアプリ）の OAuth トークンは 7 日 で期限切れ。7 日後、ユーザーは再接続の再承認が必要。Google の未検証アプリケーション向けセキュリティポリシー。

  2. Test User Restrictions - 「Test users」リストに追加されたユーザーのみ OAuth アプリを使用可能。最大 100 人のテストユーザー。アプリが検証・公開されるまでこの制限は適用。

  3. App Verification Process - 7 日間のトークン期限を解除するには、Google 検証 への申請が必要。検証には 数週間（通常 4〜8 週間）かかる場合あり。

App Verification & Publishing​

制限を解除するには:

  1. Submit for Verification

    • Google Cloud Console の "OAuth consent screen" に移動
    • "PUBLISH APP" ボタンをクリック
    • 検証フォームに記入（アプリの目的、機能、プライバシーポリシー URL、利用規約 URL、ビデオデモ（オプション推奨））
    • 審査に提出

  2. Verification Timeline

    • 初期審査: 1〜2 週間
    • 追加情報の要求: 変動（Google が clarification が必要な場合）
    • 最終承認: 合計 4〜8 週間（目安）

  3. After Verification

    • トークンは 7 日で期限切れにならない
    • テストユーザー制限なし
    • 任意の Gmail ユーザーがアプリを使用可能

Production vs Testing​

  • Testing Mode: クイックセットアップ、ただしトークンは 7 日ごとに期限切れ
  • Production Mode: 検証が必要、ただしトークンは期限切れにならない
  • 選択はお任せ - 当ソフトウェアは両モードに対応

Token Refresh​

当モジュールは可能な限りトークンの自動更新を処理します。ただし:

  • 未検証アプリ: トークンは 7 日で期限切れ、手動の再承認が必要
  • 検証済みアプリ: ユーザー操作なしでトークンが自動更新

Notes​

  • redirect URI は Google Cloud Console で設定したものと完全に一致する必要がある
  • Client Secret は安全に保管し、公開しないこと
  • ドメインを変更した場合は、Google Cloud Console の redirect URI を更新
  • OAuth フローは Google が完全に処理。当モジュールは開始とコールバック受信のみ

Troubleshooting​

"Redirect URI mismatch" エラー:

  • Google Cloud Console の redirect URI が https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail と完全一致することを確認
  • 末尾スラッシュや HTTP/HTTPS の不一致を確認

7 日後の「Token expired」:

  • 未検証アプリでは正常（Google のポリシー）
  • 「Connect Gmail」を再度クリックして再承認
  • 回避するには Google 検証への申請

"Access blocked" エラー:

  • メールが「Test users」リストに追加されていることを確認（未検証アプリの場合）
  • Google Cloud プロジェクトで Gmail API が有効かを確認

Gmail API が見つからない:

  • 正しい Google Cloud プロジェクトにいることを確認
  • API Library で「Gmail」を検索

Additional Resources​

備考

7 日間のトークン期限とテストユーザー制限は、未検証アプリケーションに対する Google のセキュリティポリシー です。当ソフトウェアによる制限ではありません。Google による検証後、これらの制限は解除されます。