日本語
  1. Zendeskヘルプ
  2. Support
  3. Supportの使い方
  4. Zendesk Supportのセキュリティとユーザーアクセス

アプリケーションでのOAuth認証の使用

Charles Nadeau
  • 編集済み
Zendesk Documentation Team

Suiteすべてすべてのプラン

ファストパス：管理センター >「アプリおよびインテグレーション」>「API」>「Zendesk API」

OAuth 2を使用して、アプリケーションからZendeskへのすべてのAPIリクエストを承認することができます。OAuthは、アプリケーションがZendeskユーザーのパスワードのような秘密情報を保存および使用することなくZendeskのデータにアクセスするための安全な手段です。

OAuth認証を使用するには、アプリケーションをZendeskに登録する必要があります。また、OAuth認証フローをサポートするために、いくつかの機能をアプリケーションに追加する必要があります。

この記事では、次のトピックについて説明します。

関連記事：

アプリケーションをZendeskに登録する

管理者は、ZendeskへのAPIコールを認証するために使用できるOAuth資格情報を生成するよう、アプリケーションを登録する必要があります。

メモ：このセクションでは、1個のZendeskアカウントを共用するユーザー用のOAuthクライアントの設定方法について説明します。1個のZendeskアカウントだけではなく、多数のZendeskアカウントとアプリケーションがやりとりする場合、グローバルOAuthクライアントを要求することができます。グローバルOAuthクライアントは、複数のZendeskインスタンスに対してAPI認証を実行する安全かつクリーンな手段です。詳細については、「Set up a global OAuth client」を参照してください。

アプリケーションを登録するには

  1. 管理センターで、サイドバーにあるアプリおよびインテグレーションアイコン（）をクリックし、「API」>「Zendesk API」を選択します。
  2. 「Zendesk API」ページで「OAuthクライアント」タブをクリックし、OAuthクライアントの一覧の右上にある「OAuthクライアントを追加」をクリックします。
  3. 次のフィールドに入力して、クライアントを作成します。
    • クライアント名：アプリケーションの名前を入力します。この名前が、アプリケーションへのアクセス許可をユーザーに求めるときにクライアント名として表示されます。また、Zendeskにアクセスできるサードパーティアプリのリストにも、この名前が表示されます。
    • 説明：省略可能です。ユーザーにアクセス許可を求める際に、ユーザーに表示するアプリの簡単な説明を入力します。
    • 会社名：省略可能です。アプリケーションにアクセス許可を付与するようユーザーに求めるときに表示する会社名です。この情報は、アクセスを付与しようとしている相手を識別するのに役立ちます。
    • ロゴ（オプション）：省略可能です。アプリケーションにアクセス許可を付与するようユーザーに求めるときに表示するロゴです。JPG、GIF、PNG形式の画像を指定できます。最適な結果を得るには、正方形の画像をアップロードします。画像のサイズは、認証ページに合わせて自動的に調整されます。
    • 一意のID：アプリ名として入力した名前が再フォーマットされ、自動的に設定されます。この名前は変更してもかまいません。
    • リダイレクトURL：ユーザーによるアクセス許可の決定をアプリケーションに送信するためにZendeskが使用するURLです。URLは絶対URLでなければなりません。相対URL、https（localhostまたは127.0.0.1でない場合）、改行で区切られたURLは入力しないでください。
  4. 「保存」をクリックします。

    ページが更新され、事前に数値が入力された「シークレットキー」フィールドが新たに左下に表示されます。これが、OAuth2の仕様で指定されているclient_secret値です。

  5. 「シークレット」の値をクリップボードにコピーし、安全な場所に保存します。メモ：シークレット値のテキストボックスの幅より長い場合があるため、コピーする前には必ず、シークレット値全体を選択していることを確認してください。
    重要：セキュリティ上の理由で、シークレット全体が表示されるのは1回限りです。「保存」をクリックした後は、最初の9文字以外は表示されなくなります。
  6. 「保存」をクリックします。

アプリケーションの一意のIDとシークレットの値の使用については、次項で説明します。

OAuth認証フローをアプリケーションに実装する

Zendeskでは、さまざまなOAuthグラントタイプをサポートしています。この記事では、Authorization Code Grant Flow（認可コードグラントタイプ）について詳細に説明します。Implicit Grant Type（インプリシットグラントタイプ）は、認可コードを使用しないという点以外は、Authorization Code Grant Typeと同じです。3番目のオプションのPassword Grant Type（パスワードグラントタイプ）は、サーバーサイドグラントタイプであり、エンドユーザーとのインタラクションを必要としません。

Authorization Code Grant Flow（認可コードグラントフロー）

このフローでは、アクセストークンをリクエストする前に認可コードを取得する必要があるため、Authorization Code Grant Flow（認可コードグラントフロー）と呼ばれています。

このフローは更新トークンを使用しません。アクセストークンは期限切れになりません。

Authorization Code Grant Flowを実装するには、以下の機能をアプリケーションに追加する必要があります。

OAuth認証フローを実装するWebアプリを開発するチュートリアルについては、「OAuth Webアプリの開発」を参照してください。

ステップ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パラメータにいくつか値を追加し、その戻り値を検証します。

パラメータは必ず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
メモ：このエンドポイントは、OAuth Tokens APIのCreate Tokenエンドポイントと混同しないようにしてください。どちらのエンドポイントも有効なOAuthアクセストークンを返しますが、エンドポイントは同じパス、同じJSONフォーマット、同じリクエストパラメータを共有していません。

リクエストには以下の必須パラメータを含めます。

  • grant_type："authorization_code"の値を指定します。
  • code：ユーザーがアクセスを付与された後でZendeskから受け取った認可コードを使用します。
  • client_id： Support管理インターフェイス（「管理」>「チャネル」>「API」>「OAuthクライアント」）のOAuthクライアントで指定された一意の識別子を使用します。「アプリケーションをZendeskに登録する」を参照してください。
  • client_secret： Support管理インターフェイス（「管理」>「チャネル」>「API」>「OAuthクライアント」）のOAuthクライアントで指定されたシークレットを使用します。「アプリケーションをZendeskに登録する」を参照してください。
  • redirect_uri：ステップ1のリダイレクトURLと同じURLです。ID目的のみ。
  • scope：「スコープを設定する」を参照してください。

リクエストはhttps経由で送信し、パラメータはJSON形式でフォーマットする必要があります。

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"

Implicit Grant Flow（インプリシットグラントフロー）

Implicit Grant Flowは、Authorization Code Grant 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パラメータが含まれます。

{redirect_url}#error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

Password Grant Type（パスワードグラントタイプ）

Password Grant Typeは、Zendeskのユーザー名とパスワードをアクセストークンと直接交換する場合に使用します。このグラントタイプは、アプリケーションがZendeskのユーザー名とパスワードを取得できる場合にのみ使用するようにしてください。通常は、Zendeskから高い特権を与えられたアプリケーションがこれに該当します。アプリケーション側では、ユーザー名とパスワードを絶対に保管しないでください。ユーザー名とパスワードの取得は安全性の高い手段で行う必要があります。

リクエストの例

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "password", "client_id": "{your_client_id}", 
    "client_secret": "{your_client_secret}", "scope": "read",
    "username": "{zendesk_username}", "password": "{zendesk_password}"}' \
  -X POST

通常、Zendeskのユーザー名はagent@zendesk.comの形式のユーザーアドレスです。

応答の例

Status: 200 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "bearer",
  "scope":"read"
}
15
ページの先頭へ戻る

0 コメント

サインインしてコメントを残してください。

関連記事

Powered by Zendesk