2を使用して、アプリケーションからZendeskへのすべてのAPIリクエストを承認することができます。OAuthは、アプリケーションがZendeskユーザーのパスワードのような秘密情報を保存および使用することなくZendeskのデータにアクセスするための安全な手段です。OAuth認証を使用するには、アプリケーションをZendeskに登録する必要があります。OAuth認証フローをサポートするために、いくつかの機能をアプリケーションに追加する必要があります。この記事では、次のトピックについて説明します。Webアプリの開発」を参照してください。ZendeskアプリへのOAuth認証フローの実装方法については、「OAuthの追加」を参照してください。アプリケーションによるアカウントへのアクセスをユーザーに許可してもらう必要がない場合でも、OAuthトークンを使用してAPIリクエストを認証できます。API(APIを使用したOAuthトークンの作成と使用)」を参照してください。アプリケーションをZendeskに登録する管理者は、ZendeskへのAPI呼び出しを認証するために使用できるOAuth資格情報を生成するよう、アプリケーションを登録する必要があります。メモ:このセクションでは、1個のZendeskアカウントを共用するユーザー用のOAuthクライアントの設定方法について説明します。1個のZendeskアカウントだけではなく、多数のZendeskアカウントとアプリケーションがやり取りする場合、グローバルOAuthクライアントを要求することができます。グローバルOAuthクライアントは、複数のZendeskインスタンスに対してAPI認証を実行する安全かつクリーンな手段です。詳細については、「Zendeskインテグレーション用のグローバルOAuthクライアントの要求」を参照してください。)をクリックして「チャネル」カテゴリから「API」を選択します。「チャネル/API」ページで「OAuthクライアント」タブをクリックし、クライアントの一覧の右上にある(+)アイコンをクリックします。次のフィールドに入力して、クライアントを作成します。クライアント名:アプリケーションの名前を入力します。この名前が、アプリケーションへのアクセス許可の付与をユーザーに求めるときにクライアント名として表示されます。Zendeskにアクセスできるサードパーティアプリのリストにも、この名前が表示されます。ユーザーにアクセス許可を求める際に、ユーザーに表示するアプリの簡単な説明を入力します。会社名:省略可能です。アプリケーションにアクセス許可を付与するようユーザーに求めるときに表示する会社名です。この情報は、アクセスを付与しようとしている相手を識別するのに役立ちます。ロゴ(オプション):省略可能です。アプリケーションにアクセス許可を付与するようユーザーに求めるときに表示するロゴです。JPG、GIF、PNG形式の画像を指定できます。最適な結果を得るには、正方形の画像をアップロードします。画像のサイズは、認証ページに合わせて自動的に調整されます。一意のID:アプリ名として入力した名前が再フォーマットされ、自動的に設定されます。この名前は変更してもかまいません。リダイレクトURL:ユーザーによるアクセス許可の決定をアプリケーションに送信するためにZendeskが使用するURLです。URLは絶対URLでなければなりません。相対URL、https(localhostまたは127.0.0.1でない場合)、改行で区切られたURLは入力しないでください。「保存」をクリックします。ページが更新され、事前に数値が入力された「シークレットキー」フィールドが新たに左下に表示されます。これが、OAuth2の仕様で指定されているclient_secret値です。「シークレット」の値をクリップボードにコピーし、安全な場所に保存します。メモ:シークレット値のテキストボックスの幅より長い場合があるため、コピーする前には必ず、シークレット値全体を選択していることを確認してください。重要:セキュリティ上の理由で、シークレット全体が表示されるのは1回限りです。「保存」をクリックした後は、最初の9文字以外は表示されなくなります。「保存」をクリックします。アプリケーションの一意のIDとシークレットの値の使用については、次項で説明します。OAuth認証フローをアプリケーションに実装するZendeskでは、さまざまなOAuthフローをサポートしています。Flow(認可コードグラントフロー)について詳細に説明します。Grantフローと同じです。Grant(パスワードグラント)オプションは、サーバーサイドグラントタイプであり、エンドユーザーとのインタラクションを必要としません。Flow(認可コードグラントフロー)と呼ばれています。このフローは更新トークンを使用しません。アクセストークンは期限切れになりません。Flowを実装するには、以下の機能をアプリケーションに追加する必要があります。Webアプリの開発」を参照してください。ユーザーを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を指定します。前のセクションを参照してください。Zendeskリソースへのアクセスを制御するスコープをスペースで区切って列挙します。すべてのリソースあるいは特定のリソースに対する読み取りアクセス、書き込みアクセス、またはなり代わりアクセスを要求できます。「スコープを設定する」を参照してください。state:ユーザーがアクセスを許可するか拒否するかを決定した後のZendeskからの応答に含まれる任意の文字列。このパラメータを使用して、クロスサイトリクエストフォージェリ(CSRF)攻撃を防ぐことができます。CSRF攻撃では、エンドユーザーを騙して、ログイン中のWebアプリケーション内で意図しない操作を実行するリンクをクリックさせるように誘導します。この種の攻撃から防御するには、stateパラメータにいくつか値を追加し、その戻り値を検証します。パラメータは必ず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の各エンドポイントに対してリソースの作成、更新、削除を行うアクセス許可を与えます。impersonateスコープでは、Zendeskの管理者がエンドユーザーの代理でリクエストを作成することができます。users(エンドユーザーの代理でAPIリクエストを作成する方法)」を参照してください。次のパラメータは、すべてのリソースに対する読み取りアクセスをアプリに付与します。scope=read次のパラメータは、すべてのリソースに対する読み取りおよび書き込みアクセスを付与します。write次のリソースに対するスコープを詳細に調整できます。監査ログ(読み取り専用)組織ヘルプセンターアプリトリガ自動化ターゲットシンタックスは以下のようになります。scope=resource:scopeたとえば、次のパラメータは、アプリのアクセスをチケットの読み取りのみに制限します。scope=tickets:readアプリにリソースへの読み取りと書き込みのアクセスを両方付与するには、両方のスコープを指定します。users:writeアプリに対して、1つのリソース(組織など)への書き込みアクセスと、それ以外の全リソースへの読み取りアクセスを付与するには、次のように指定します。認可に関するユーザーの決定を処理するアプリケーションは、ユーザーの決定を通知するZendeskからの応答を処理する必要があります。この情報は、リダイレクトURL内のURLパラメータに含まれています。ユーザーがアプリケーションにアクセスを付与するよう決定した場合、リダイレクトURLには認可コードが含まれます。例:{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf認可コードの有効期限は短期間です。ユーザーがアプリケーションへのアクセスを許可しないと決めた場合、リダイレクト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呼び出しに含めるトークンです。Zendeskからアクセストークンを取得するユーザーがアプリケーションにZendeskへのアクセスを許可し、その応答としてZendeskから認可コードを受け取った場合、アプリケーションはそのコードをアクセストークンと交換することができます。アクセストークンを取得するには、以下のエンドポイントに対するPOSTリクエストを作成します。https://{subdomain}.zendesk.com/oauth/tokensリクエストには以下の必須パラメータを含めます。grant_type:値をauthorization_codeとして指定します。code:ユーザーがアクセスを付与された後でZendeskから受け取った認可コードを使用します。client_id:アプリケーションをZendeskに登録したときに取得した一意のIDを指定します。client_secret:アプリケーションをZendeskに登録したときに取得したシークレット値を指定します。redirect_uri:ステップ1のリダイレクトURLと同じURLです。scope:readを値として指定します。リクエストはhttps経由で送信し、パラメータはJSON形式でフォーマットする必要があります。API呼び出しでアクセストークンを使用するアプリは、アクセストークンを使用して、API呼び出しを実行できます。トークンをリクエストのHTTP認可ヘッダーに以下のように指定します。{a_valid_access_token}たとえば、チケットをリストするcurlリクエストは以下のようになります。Flowとほぼ同じですが、ステップ3を必要としないという点で異なります。このフローでは、認可コードではなくトークンをリクエストします。response_typeパラメータの値にcodeではなくtokenを指定します。エンドユーザーがアクセスを認可した場合、トークンはリダイレクトURLに直接送信されます。リクエストの例https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=token&client_id={your_unique_identifier}&scope=read%20write応答の例ユーザーがアプリケーションにアクセスを付与すると、トークンがリダイレクトURLに含められます。{redirect_url}#access_token=gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo&token_type=bearerユーザーがアプリケーションにアクセスを付与しないと決定した場合、URLにはerrorパラメータとerror_descriptionパラメータが含まれます。Typeは、Zendeskのユーザー名とパスワードをアクセストークンと直接交換する場合に使用します。このグラントタイプは、アプリケーションがZendeskのユーザー名とパスワードを取得できる場合にのみ使用するようにしてください。通常は、Zendeskから高い特権を与えられたアプリケーションがこれに該当します。アプリケーション側では、ユーザー名とパスワードを絶対に保管しないでください。ユーザー名とパスワードの取得は安全性の高い手段で行う必要があります。POST通常、Zendeskのユーザー名はagent@zendesk.comの形式のユーザーアドレスです。