| Suite | Team、Growth、Professional、EnterpriseまたはEnterprise Plus |
| Support | Team、ProfessionalまたはEnterprise |
検証済みのAI要約◀▼
OAuth 2.0を使用することで、ユーザーパスワードを保存せずに、アプリケーションのAPIリクエストを安全に認証できます。アプリを登録してOAuthの認証情報を生成し、クライアントのタイプを公開または秘密のいずれかを選択し、アクセストークンを取得するための認可フローを実装します。このセットアップにより、APIアクセスを効果的に管理し、トークンを必要に応じて更新することで、データと安全にやりとりできます。
OAuth 2.0を使用して、アプリケーションからZendeskへのすべてのAPIリクエストを承認することができます。OAuthは、アプリケーションがZendeskユーザーのパスワードのような秘密情報を保存および使用することなくZendeskのデータにアクセスするための安全な手段です。
OAuth認証を使用するには、アプリケーションをZendeskに登録する必要があります。また、OAuth認証フローをサポートするために、いくつかの機能をアプリケーションに追加する必要があります。
この記事では、次のトピックについて説明します。
- アプリケーションをZendeskに登録する
- OAuthクライアントの種類
- OAuth Client Credentials Grant Type（OAuthクライアントクレデンシャルグラントタイプ）
- OAuth認証フローをアプリケーションに実装する
関連記事：
- OAuth認証フローを実装するWebアプリを開発するチュートリアルについては、「OAuth Webアプリの開発」を参照してください。
- ZendeskアプリへのOAuth認証フローの実装方法については、「Adding third-party OAuth to a Support app」を参照してください。
- アプリケーションによるアカウントへのアクセスをユーザーに許可してもらう必要がない場合でも、OAuthトークンを使用してAPIリクエストを認証できます。「Creating and using OAuth tokens with the API（APIを使用したOAuthトークンの作成と使用）」を参照してください。
アプリケーションをZendeskに登録する
管理者は、ZendeskへのAPIコールを認証するために使用できるOAuth資格情報を生成するよう、アプリケーションを登録する必要があります。
アプリケーションを登録するには
- 管理センターで、サイドバーの「
アプリおよびインテグレーション」をクリックし、「API」>「OAuthクライアント」を選択します。 - OAuthクライアントリストの右側にある「OAuthクライアントを追加」をクリックします。
- 以下のフィールドに入力して、クライアントを作成します。
- クライアント名：アプリケーションの名前を入力します。この名前が、アプリケーションへのアクセス許可をユーザーに求めるときにクライアント名として表示されます。また、Zendeskにアクセスできるサードパーティアプリのリストにも、この名前が表示されます。
- 説明：省略可能です。ユーザーにアクセス許可を求める際に、ユーザーに表示するアプリの簡単な説明を入力します。
- 会社名：省略可能です。アプリケーションにアクセス許可を付与するようユーザーに求めるときに表示する会社名です。この情報は、アクセスを付与しようとしている相手を識別するのに役立ちます。
- ロゴ（オプション）：省略可能です。アプリケーションにアクセス許可を付与するようユーザーに求めるときに表示するロゴです。JPG、GIF、PNG形式の画像を指定できます。最適な結果を得るには、正方形の画像をアップロードします。画像のサイズは、認証ページに合わせて自動的に調整されます。
- 識別子：アプリ名として入力した名前が再フォーマットされ、自動的に設定されます。この名前は変更してもかまいません。
- クライアントの種類：PublicまたはConfidential。OAuthのPublicクライアントは、モバイルアプリやWebアプリなど、資格情報を安全に保存できない環境で実行されるアプリケーションです。Publicクライアントの場合は、PKCEを使用する必要があります。OAuthのConfidentialクライアントは、資格情報を安全に保持できるセキュアなサーバー上で実行されます。Confidentialクライアントの場合は、PKCE、クライアントシークレット、またはその両方を使用することができます。詳しくは「OAuthクライアントの種類」を参照してください。
- リダイレクトURL：ユーザーによるアクセス許可の決定をアプリケーションに送信するためにZendeskが使用するURLです。URLは絶対URLでなければなりません。相対URL、https（localhostまたは127.0.0.1でない場合）、改行で区切られたURLは入力しないでください。
- 「保存」をクリックします。
ページが更新され、事前に数値が入力された「シークレットキー」フィールドが新たに左下に表示されます。これが、OAuth2の仕様で指定されているclient_secret値です。
- 「シークレット」の値をクリップボードにコピーし、安全な場所に保存します。メモ：シークレット値のテキストボックスの幅より長い場合があるため、コピーする前には必ず、シークレット値全体を選択していることを確認してください。
重要：セキュリティ上の理由で、シークレット全体が表示されるのは一回限りです。「保存」をクリックした後は、最初の9文字以外は表示されなくなります。
- 「保存」をクリックします。
アプリケーションの一意のIDとシークレットの値の使用については、次項で説明します。
OAuthクライアントの種類
Zendesk OAuthクライアントには、OAuthクライアントの作成時に渡される kind プロパティがあり、以下のいずれかの値を指定できます。
- パブリックコメント：OAuthのPublicクライアントは、モバイルアプリやWebアプリなど、資格情報を安全に保存できない環境で実行されるアプリケーションです。Publicクライアントの場合は、PKCEを使用する必要があります。
- Confidential：OAuthのConfidentialクライアントは、資格情報を安全に保持できるセキュアなサーバー上で実行されます。Confidentialクライアントの場合は、PKCE、クライアントシークレット、またはその両方を使用することができます。
詳細については、「クライアントの種類」を参照してください。
Zendesk OAuthクライアントタイプは、Zendesk Supportのチケット管理システムにのみ適用されます。Chat、会話、Sellではサポートされていません。
既存のZendesk OAuthクライアントは、現在 kindプロパティが unknownに設定されています。これらの既存クライアントは、kindプロパティがpublicまたはconfidentialのいずれかに更新されるまで、影響を受けないままです。管理センターで作成される新しいOAuthクライアントは、作成時にkindプロパティを設定する必要があります。
kindプロパティを publicに変更する場合は、まずPKCEを実装する必要があります。これを行わないと、PKCEが直ちに必要となるため、クライアントが機能しなくなります。管理センターで作成されるすべてのOAuth新しいクライアントについて、kindプロパティを必ず設定してください。api/v2/oauth/clients endpointエンドポイントで作成したOAuthクライアントではkindプロパティは必須ではありませんが、Zendeskではこのプロパティを含めることを推奨しています。
OAuth Client Credentials Grant Type（OAuthクライアントクレデンシャルグラントタイプ）
OAuthクライアントクレデンシャルグラントタイプは、機密性の高いクライアントにのみ適用され、特定のクライアントシークレットのみを使用してOAuthトークンを作成することができます。このフローを使用するには、grant_type: client_credentials を使用して有効な client_secret パラメータを /oauth/tokens エンドポイントに渡し、新しいOAuthアクセストークンを生成します。他の認証フローとは異なり、このグラントタイプはリフレッシュトークンを返しません。トークンに関連付けられたユーザーは、使用されたクライアントにリンクされたユーザーと同じになります。必要に応じてexpires_inの値を含めることで、トークンの有効期限をミリ秒単位で指定できます。セキュリティ上の理由から、パブリッククライアントは、このグラントタイプを使用できません。詳細については、「OAuth Clients」を参照してください。
OAuthリフレッシュトークングラントタイプ
OAuthリフレッシュトークングラントタイプを使用すると、有効期限が切れたアクセストークン、または有効期限が切れそうなアクセストークンを更新できます。新しいOAuthアクセストークンを生成するには、grant_type: refresh_token を使用して https://{subdomain}.zendesk.com/oauth/tokens エンドポイントに refresh_token パラメータを渡します。これにより、新しいアクセストークンとリフレッシュトークンが返され、以前のものは無効になります。
OAuthクライアントは、期限切れのアクセストークンと期限切れのリフレッシュトークンを処理するフォールバックメカニズムを実装する必要があります。たとえば、アクセストークンの有効期限が切れたり、エラーが発生した場合は、アクセストークンをリフレッシュすることができます。ただし、リフレッシュプロセスが失敗した場合、またはアクセストークンにリンクされたリフレッシュトークンがない場合は、ユーザーを https://{subdomain}.zendesk.com/oauth/authorizations/new にリダイレクトして、アプリケーションを再承認する必要があります。詳細については、「OAuth Tokens for Grant Type」および「Creating and using OAuth access tokens with the API」を参照してください。
OAuth認証フローをアプリケーションに実装する
Zendeskは、アクセストークンを取得するための認可コードグラントフローをサポートしています。このフローでは、アクセストークンをリクエストする前に認可コードを取得する必要があるため、Authorization Code Grant Flow（認可コードグラントフロー）と呼ばれています。
このフローではリフレッシュトークンを利用することで、ユーザーの再認可を行わずに新しいアクセストークンを生成できます。APIが expires_in パラメータを通じてトークンの有効期間を指定している場合、アクセストークンは期限切れになる可能性があります。そのような場合には、有効期限が切れる前に提供されたリフレッシュトークンを使用して、アクセストークンを更新する仕組みを実装してください。
Authorization Code Grant Flowを実装するには、以下の機能をアプリケーションに追加する必要があります。
- ステップ1 - ユーザーをZendeskの認可ページに送る
- ステップ2 - 認可に関するユーザーの決定を処理する
- ステップ3 - Zendeskからアクセストークンを取得する
- ステップ4 - APIコールでアクセストークンを使用する
OAuth認証フローを実装するWebアプリを開発するチュートリアルについては、「OAuth Webアプリの開発」を参照してください。
認証コード付与メソッドは Proof Key for Code Exchange（PKCE）をサポートしています。詳細については、開発者向けドキュメントの「Using PKCE to make Zendesk OAuth access tokens more secure」を参照してください。
ステップ1 - ユーザーをZendeskの認可ページに送る
最初に、アプリケーションはユーザーをZendeskの認可ページに送る必要があります。このページでユーザーは、アプリケーションがユーザー自身の代理としてZendeskにアクセスすることを認可するよう求められます。ユーザーが認可または不認可を選択すると、Zendeskは選択内容とその他若干の情報をアプリケーションに送り返します。
ユーザーをZendeskの認可ページに送るには
アプリケーションに、ユーザーを次のURLに送るリンクボタンを追加します。
https://{subdomain}.zendesk.com/oauth/authorizations/new{subdomain} には、ホストマッピングされたサブドメインではなく、ご使用のZendeskのコアサブドメインを指定します。
POSTリクエストとGETリクエストのどちらを使用してもかまいません。以下のパラメータを含めます。
-
response_type：必須。Zendeskは応答で認可コードを返すので、応答タイプとして
codeを指定します。例：response_type=code - redirect_uri：必須。ユーザーのアクセス許可の決定をアプリケーションに送信するためにZendeskが使用するURLです。相対URLではなく、絶対URLを指定する必要があります。また、localhostまたは127.0.0.1を使用している場合を除き、セキュア接続（https）を指定してください。
- client_id：必須。アプリケーションをZendeskに登録したときに取得した一意のIDを指定します。前のセクションを参照してください。
- scope：必須。Zendeskリソースへのアクセスを制御するスコープをスペースで区切って列挙します。すべてのリソースあるいは特定のリソースに対する読み取りアクセス、書き込みアクセス、またはなり代わりアクセスを要求できます。「スコープを設定する」を参照してください。
-
state：ユーザーがアクセスを許可するか拒否するかを決定した後のZendeskからの応答に含まれる任意の文字列。このパラメータを使用して、クロスサイトリクエストフォージェリ（CSRF）攻撃を防ぐことができます。CSRF攻撃では、エンドユーザーを騙して、ログイン中のWebアプリケーション内で意図しない操作を実行するリンクをクリックさせるように誘導します。この種の攻撃から防御するには、
stateパラメータにいくつか値を追加し、その戻り値を検証します。 - code_challenge：PKCEを使用する場合は必須。コードベリファイアから得られるコードチャレンジを表す文字列。詳しくは、開発者向けドキュメントの「Generating the code_challenge value」を参照してください。
- code_challenge_method：PKCEを使用する場合は必須。コードチャレンジの取得に使用するメソッド。値として「S256」を指定します。
パラメータは必ずURLエンコードするようにしてください。
GETリクエストの例
https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20writeエンドユーザーのブラウザにZendeskの認可ページが開きます。認可するかどうかを選択した後、選択内容が、リクエスト内に指定されたリダイレクトURLに送信されます。
スコープを設定する
アプリのZendeskリソースへのアクセスを制御するには、スコープを指定する必要があります。readスコープは、アプリにGETエンドポイントへのアクセスを与えます。これには、関連リソースをサイドロードするアクセス許可が含まれます。writeスコープは、アプリにPOST、PUT、DELETEの各エンドポイントに対してリソースの作成、更新、削除を行うアクセス許可を与えます。
スコープについて詳しくは、「OAuth Tokens for Grant Types」を参照してください。
impersonateスコープでは、Zendeskの管理者がエンドユーザーの代理でリクエストを作成することができます。「Making API requests on behalf of end users（エンドユーザーの代理でAPIリクエストを作成する方法）」を参照してください。
たとえば、次のパラメータは、すべてのリソースに対する読み取りアクセスをアプリに付与します。
"scope": "read"次のパラメータは、すべてのリソースに対する読み取りおよび書き込みアクセスを付与します。
"scope": "read write"次のリソースに対するスコープを詳細に調整できます。
- チケット
- ユーザー
- 監査ログ（読み取り専用）
- 組織
- ヘルプセンター
- アプリ
- トリガ
- 自動化
- ターゲット
- Webhook
- zis
シンタックスは以下のようになります。
"scope": "resource:scope"たとえば、次のパラメータは、アプリのアクセスをチケットの読み取りのみに制限します。
"scope": "tickets:read"アプリにリソースへの読み取りと書き込みのアクセスを両方付与するには、両方のスコープを指定します。
"scope": "users:read users:write"アプリに対して、1つのリソース（組織など）への書き込みアクセスと、それ以外の全リソースへの読み取りアクセスを付与するには、次のように指定します。
"scope": "organizations:write read"ステップ2 - 認可に関するユーザーの決定を処理する
アプリケーションは、ユーザーの決定を通知するZendeskからの応答を処理する必要があります。この情報は、リダイレクトURL内のURLパラメータに含まれています。
ユーザーがアプリケーションにアクセスを付与するよう決定した場合、リダイレクトURLには認可コードが含まれます。以下に例を示します。
{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf認証コードは120秒しか有効ではありません。
ユーザーがアプリケーションへのアクセスを許可しないと決めた場合、リダイレクトURLには、ユーザーがアクセスを拒否したことをアプリに通知するerrorパラメータとerror_descriptionパラメータが含まれます。
{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+requestこれらの値を使用してアプリケーションのフローを管理します。URLにcodeパラメータが含まれる場合、次項で説明するように、Zendeskからアクセストークンを取得します。これはZendeskへのAPIコールに含めるトークンです。
ステップ3 - Zendeskからアクセストークンを取得する
ユーザーがアプリケーションにZendeskへのアクセスを許可し、その応答としてZendeskから認可コードを受け取った場合、アプリケーションはそのコードをアクセストークンと交換することができます。アクセストークンを取得するには、以下のエンドポイントに対するPOSTリクエストを作成します。
https://{subdomain}.zendesk.com/oauth/tokensリクエストには以下の必須パラメータを含めます。
- grant_type："authorization_code"の値を指定します。
- code：ユーザーがアクセスを付与された後でZendeskから受け取った認可コードを使用します。
- client_id： Support管理インターフェイス（「管理」>「チャネル」>「API」>「OAuthクライアント」）のOAuthクライアントで指定された一意のIDを使用します。詳しくは「アプリケーションをZendeskに登録する」を参照してください。
-
client_secret： Support管理インターフェイス（「管理」>「チャネル」>「API」>「OAuthクライアント」）のOAuthクライアントで指定されたシークレットを使用します。詳しくは「アプリケーションをZendeskに登録する」を参照してください。
code_challengeとcode_verifierのPKCEパラメータを使用する場合、client_secretは必要ありません。この特性を使用して、セキュリティ上の懸念から推奨されなくなったImplicit Grant Flow（インプリシットグラントフロー）から移行することができます。詳しくは、開発者向けドキュメントの「Using PKCE to migrate from the implicit grant flow」を参照してください。 - redirect_uri：ステップ1のリダイレクトURLと同じURLです。ID目的のみ。
- scope：「スコープを設定する」を参照してください。
-
code_verifier：PKCEを使用する場合は必須。
code_challengeの値を生成するための文字列。詳しくは、開発者向けドキュメントの「Generating the code_challenge value」を参照してください。 - expires_in：オプション。アクセストークンの有効秒数。詳しくは「OAuth Tokens for Grant Types」を参照してください。
- refresh_token_expires_in：オプション。リフレッシュトークンの有効秒数。詳しくは「OAuth Tokens for Grant Types」を参照してください。
リクエストはhttps経由で送信し、プロパティはJSON形式でフォーマットする必要があります。カスタムまたはサードパーティのアプリケーションを使用してAPIリクエストを行う場合、プロパティ値の適切なフォーマットについては、そのアプリケーションのドキュメントを参照してください。
curlの使用例
curl https://{subdomain}.zendesk.com/oauth/tokens \
-H "Content-Type: application/json" \
-d '{"grant_type": "authorization_code", "code": "{your_code}",
"client_id": "{your_client_id}", "client_secret": "{your_client_secret}",
"redirect_uri": "{your_redirect_url}", "scope": "read" }' \
-X POST応答の例
Status: 200 OK
{
"access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
"token_type": "bearer",
"scope":"read"
}ステップ4 - APIコールでアクセストークンを使用する
アプリは、アクセストークンを使用して、APIコールを実行できます。トークンをリクエストのHTTP認可ヘッダーに以下のように指定します。
Authorization: Bearer {a_valid_access_token}
たとえば、チケットをリストするcurlリクエストは以下のようになります。
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"
0件のコメント
サインインしてコメントを残します。