Zendeskとの連携機能を構築する場合、最終的にはAPIリクエストを認証する必要があります。APIトークンは単純なスクリプトには有効ですが、OAuthは、ユーザーに代わってZendeskデータにアクセスする本番アプリケーションの標準です。これにより、ユーザーはパスワードを共有せずに特定の権限を付与でき、アプリがアクセスできるものを細かく制御できます。
ただし、OAuthの設定は、これまでに行ったことがない場合は複雑に感じられる可能性があります。リダイレクト、認証コード、スコープ、およびシークレットを管理する必要があります。このガイドでは、アプリの登録から最初の認証済みAPI呼び出しの実行まで、プロセス全体をステップごとに説明します。
よりシンプルなアプローチをお探しの場合は、eesel AIがZendesk認証を自動的に処理します。アカウントを一度接続すると、バックグラウンドでOAuthフローを管理します。ただし、カスタム統合を構築する必要がある場合は、読み進めてください。
必要なもの
始める前に、以下を確認してください。
- Suite Growthプラン以上、またはSupport Professionalプラン以上のZendeskアカウント
- Zendeskインスタンスへの管理者アクセス（または付与できる人）
- OAuth 2.0の概念（認証コード、アクセストークン、リダイレクト）の基本的な理解
- OAuthフローをテストできる開発環境
実験的な利用であれば、Zendeskは開発用のトライアルアカウントを提供しています。また、認証フローとエンドポイントの最新の詳細については、Zendesk OAuthの公式ドキュメントを確認してください。
ステップ1：ZendeskでOAuthクライアントを登録する
最初のステップは、Zendeskにアプリケーションについて知らせることです。これにより、ユーザーがアプリを接続するときに承認するOAuthクライアントが作成されます。
OAuthクライアントセクションに移動します。
- Zendeskにサインインし、Admin Center（サイドバーの歯車アイコンをクリック）に移動します。
- 左側のサイドバーで**アプリと連携機能（Apps and integrations）**を選択します。
- API → **OAuthクライアント（OAuth Clients）**をクリックします。
- 右側の**OAuthクライアントを追加（Add OAuth client）**をクリックします。
クライアントの詳細を入力します。
- 名前（Name）: アプリの表示名。ユーザーがアプリを承認するときに表示されます。
- 説明（Description）: オプションですが、アプリの機能をユーザーが理解するのに役立ちます。
- 会社（Company）: 会社名
- ロゴ（Logo）: オプション。アプリを表す正方形の画像（JPG、GIF、またはPNG）をアップロードします。
- クライアントの種類（Client Kind）: パブリック（Public）またはコンフィデンシャル（Confidential）を選択します。
- コンフィデンシャル（Confidential）: クライアントシークレットを安全に保存できるサーバーサイドアプリの場合。
- パブリック（Public）: シークレットが公開される可能性のあるモバイルアプリまたはJavaScriptアプリケーションの場合。これらはPKCEを使用する必要があります。
- リダイレクトURL（Redirect URLs）: ユーザーがアプリを承認した後にZendeskがユーザーを送信するURL。HTTPSである必要があります（開発中のlocalhostを除く）。必要に応じて、複数のURLを別々の行に追加します。
認証情報を保存します。
保存（Save）をクリックすると、ZendeskはクライアントID（Client ID）（「識別子（Identifier）」と呼ばれる）と**クライアントシークレット（Client Secret）**を生成します。すぐに両方をコピーしてください。シークレットは一度しか表示されません。紛失した場合は、新しいものを生成する必要があります。
ステップ2：適切なOAuthフローを選択する
Zendeskは、2つの主要なOAuth 2.0グラントタイプをサポートしています。ユースケースに一致するものを選んでください。
**認可コードフロー（Authorization code flow）**は、ユーザー向けのアプリケーション用です。ユーザーがアプリをZendeskアカウントに接続する場合、Zendeskの認証ページにリダイレクトします。ログインし、権限を承認すると、Zendeskは認証コードとともにアプリにリダイレクトします。サーバーはこのコードをアクセストークンと交換します。
このフローはリフレッシュトークンをサポートしているため、ユーザーに再認証を要求せずに新しいアクセストークンを取得できます。アクセストークンは期限切れになります（5分から2日間で設定できます）が、リフレッシュトークンはより長く（7〜90日間）持続します。
**クライアント資格情報フロー（Client credentials flow）**は、マシンツーマシンの認証用です。ユーザーは関与しません。アプリはクライアントIDとシークレットを使用して、アクセストークンを直接取得します。これは、スケジュールに従ってZendeskデータにアクセスする必要があるバックエンドサービスに適しています。
**PKCE（Proof Key for Code Exchange）**は、パブリッククライアントのセキュリティを追加します。クライアントシークレットを安全に保存できないモバイルアプリまたはシングルページアプリケーションを構築する場合は、認可コードフローでPKCEを使用します。これにより、認証コード傍受攻撃を防ぎます。
ステップ3：OAuthスコープを設定する
スコープは、アプリがZendeskでアクセスできるものを制御します。必要な権限のみを要求する特定の範囲に絞ることは、最小権限の原則に従い、ユーザーがアプリを信頼する可能性を高めます。
Zendeskは、3つの主要なスコープタイプを提供しています。
- read: GETエンドポイントへのアクセス。関連リソースをサイドロードする権限が含まれます。
- write: リソースの作成、更新、および削除のためのPOST、PUT、およびDELETEエンドポイントへのアクセス。
- impersonate: 管理者がエンドユーザーに代わってAPIリクエストを行うことを許可します。
より細かく制御するために、リソース固有のスコープをリクエストすることもできます。
tickets:readまたはtickets:writeusers:readまたはusers:writeorganizations:readまたはorganizations:writemacros:readまたはmacros:writetriggers:readまたはtriggers:write
たとえば、アプリがチケットの読み取りとユーザープロファイルの更新のみを必要とする場合は、包括的なread writeアクセスではなく、tickets:read users:writeをリクエストします。
**重要：**Zendeskでのユーザーの実際の権限は依然として適用されます。OAuthスコープでチケットの書き込みが許可されていても、読み取り専用アクセス権を持つユーザーは、アプリを通じてチケットを作成できません。
ステップ4：認証フローを実装する
Webアプリケーションで最も一般的なアプローチである、認可コードフローを実装する方法を次に示します。
ユーザーを認証エンドポイントに送信します。
必要なパラメーターを指定して、ユーザーをこのURLにリダイレクトします。
https://{subdomain}.zendesk.com/oauth/authorizations/new
次のクエリパラメーターを含めます。
response_type=code（必須）client_id={your_client_id}（必須）redirect_uri={your_redirect_url}（必須、登録したものと一致する必要があります）scope={requested_scopes}（必須、スペースで区切ります）state={random_string}（推奨、CSRF攻撃を防ぎます）
URLの例：
https://yourcompany.zendesk.com/oauth/authorizations/new?response_type=code&client_id=your_client_id&redirect_uri=https://yourapp.com/callback&scope=read%20write&state=abc123
リダイレクトを処理します。
ユーザーがアクセスを承認または拒否すると、Zendeskは次のいずれかでredirect_uriにリダイレクトします。
- 認証コード：
?code=7xqwtlf3rrdj8uyeb1yf&state=abc123 - エラー：
?error=access_denied&error_description=User+denied+access
stateパラメーターが送信したものと一致することを確認し、コードを抽出します。認証コードは120秒後に期限切れになるため、すぐに交換してください。
コードをトークンと交換します。
ZendeskのトークンエンドポイントにPOSTリクエストを送信します。
import requests
response = requests.post(
f'https://{subdomain}.zendesk.com/oauth/tokens',
data={
'grant_type': 'authorization_code',
'code': authorization_code,
'client_id': client_id,
'client_secret': client_secret,
'redirect_uri': redirect_uri,
'scope': 'read',
'expires_in': 172800, # 2 days
'refresh_token_expires_in': 7776000 # 90 days
}
)
tokens = response.json()
access_token = tokens['access_token']
refresh_token = tokens['refresh_token']
両方のトークンを安全に保存します。アクセストークンはAPI呼び出しに使用するものです。リフレッシュトークンを使用すると、現在のトークンが期限切れになったときに新しいアクセストークンを取得できます。
ステップ5：APIリクエストでアクセストークンを使用する
アクセストークンを使用すると、Zendesk APIへの認証済みリクエストを作成できます。
Authorizationヘッダーにトークンを含めます。
Authorization: Bearer {access_token}
リクエストの例：
import requests
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(
f'https://{subdomain}.zendesk.com/api/v2/tickets.json',
headers=headers
)
トークンの有効期限を処理します。
アクセストークンが期限切れになると、APIリクエストは次のエラーで401ステータスを返します。
{
"error": "invalid_token",
"error_description": "The access token provided is expired, revoked, malformed or invalid for other reasons."
}
リフレッシュトークンを使用して、新しいアクセストークンを取得します。
response = requests.post(
f'https://{subdomain}.zendesk.com/oauth/tokens',
data={
'grant_type': 'refresh_token',
'refresh_token': refresh_token,
'client_id': client_id,
'client_secret': client_secret,
'scope': 'read'
}
)
new_tokens = response.json()
リフレッシュトークンも期限切れになっている場合は、ユーザーに認証フローを再度実行させる必要があります。
よくある問題とトラブルシューティング
「無効なリダイレクトURI（Invalid redirect URI）」エラー： 認証リクエストのリダイレクトURLは、OAuthクライアントに登録されているURLのいずれかと完全に一致する必要があります。末尾のスラッシュ、httpとhttps、およびサブドメインの違いを確認してください。
スコープの権限が拒否されました： OAuthスコープは、ユーザーの実際のZendesk権限によって制限されることに注意してください。読み取り専用アクセス権を持つエージェントは、OAuthスコープで許可されていても、チケットを書き込むことはできません。
クライアントシークレットが部分的にしか表示されない： Zendeskは、作成直後に一度だけ完全なシークレットを表示します。コピーしなかった場合は、OAuthクライアント設定で新しいシークレットを生成する必要があります。
localhostでのテスト： Zendeskでは、開発用のリダイレクトURLとしてhttp://localhostおよびhttp://127.0.0.1を使用できます。ポートを含む正確なURL（例：http://localhost:3000/callback）を登録してください。
認証コードの期限切れ： コードは120秒間のみ有効です。ユーザーの承認に時間がかかりすぎる場合、またはコード交換に遅延がある場合は、エラーが発生します。フローを再度開始します。
セキュリティのベストプラクティス
**シークレットを安全に保管する：**ソースコードにクライアントシークレットをハードコードしたり、バージョン管理にコミットしたりしないでください。環境変数またはシークレット管理サービスを使用します。OWASP OAuthチートシートは、OAuth実装に関する追加のセキュリティ推奨事項を提供します。
**HTTPSをどこでも使用する：**本番環境のすべてのリダイレクトURLはHTTPSを使用する必要があります。唯一の例外は、開発中のlocalhostです。
**パブリッククライアントにPKCEを実装する：**シークレットが公開される可能性のあるモバイルアプリまたはブラウザーベースのアプリを構築する場合は、PKCEを使用します。コード検証ツールを生成し、ハッシュしてコードチャレンジを作成し、認証リクエストとともにチャレンジを送信します。
**適切なトークンの有効期限を設定する：**有効期間の短いトークンの方が安全です。ほとんどのアプリケーションでは、24時間がセキュリティと利便性の適切なバランスです。
**認証情報を定期的にローテーションする：**定期的に新しいクライアントシークレットを生成し、アプリケーションを更新します。シークレットが侵害された疑いがある場合は、すぐにローテーションします。
**状態パラメーターを検証する：**リダイレクトの状態パラメーターが送信したものと一致することを常に確認してください。これにより、悪意のあるサイトがユーザーをだまして不要なアクセスを承認させるCSRF攻撃を防ぎます。
eesel AIでOAuthの複雑さを回避する
カスタムOAuth連携機能を構築するには、時間と継続的なメンテナンスが必要です。認証フロー、トークンの更新、エラーケース、およびセキュリティアップデートを処理する必要があります。多くのチームにとって、これはエンジニアリング時間を最適に活用する方法ではありません。
eesel AIは、よりシンプルなパスを提供します。AIエージェントは、ワンクリックでZendeskアカウントに接続します。OAuth認証を自動的に処理するため、実際に問題を解決する自動化の構築に集中できます。
認証コードとリフレッシュトークンを交換するコードを作成する代わりに、次のことができます。
- ヘルプセンターの記事と過去のチケットでAIをトレーニングする
- チケットをエンドツーエンドで解決する自動化を設定する
- 複雑な問題をプレーンな英語のルールで人間にエスカレートする
- ライブになる前に、過去のデータでシミュレーションを実行する
高度にカスタム化された連携機能を構築する場合、OAuthが適切な選択肢となる可能性があります。ただし、エンジニアリングのオーバーヘッドなしでAIを活用したサポート自動化が必要な場合は、eesel AIをお試しください。
