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

Suite、すべてのバージョン

Team、Growth、Professional、EnterpriseまたはEnterprise Plus

Support

Team、ProfessionalまたはEnterprise

検証済みのAI要約◀▼

OAuth 2を使用することで、ユーザーパスワードを保存せずに、APIリクエストを安全に認証できます。アプリを登録してOAuth認証情報を生成し、認証コードフローを実装してアクセストークンを取得します。アクセストークンの有効期限が切れた場合は、リフレッシュトークンを使用して新しいアクセストークンを取得します。

ナビゲーションパス：「管理センター」>「アプリおよびインテグレーション」>「API」>「OAuthクライアント」

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

OAuth認証を使用するには、アプリケーションをZendeskに登録する必要があります。また、OAuthの認証コードフローと、期限切れのアクセストークンをリフレッシュトークンで更新する処理をサポートするために、アプリケーションにいくつかの機能を追加する必要があります。

Zendeskはクライアント認証グラントタイプのフローもサポートしており、OAuthクライアントのシークレットのみを使用してアクセストークンを作成できます。このグラントタイプは機密クライアントのみを対象としており、本記事では扱いません。詳細については、APIリファレンスの「Client credentials grant type」を参照してください。

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

アプリケーションをZendeskに登録する
OAuth認証フローをアプリケーションに実装する
期限切れのアクセストークンを置き換える

OAuth認証フローを実装するWebアプリケーションの構築方法については、「Using OAuth to authenticate Zendesk API requests in a web app」を参照してください。
ZendeskアプリへのOAuth認証フローの実装方法については、「Adding third-party OAuth to a Support app」を参照してください。
アプリケーションによるアカウントへのアクセスをユーザーに許可してもらう必要がない場合でも、OAuthトークンを使用してAPIリクエストを認証できます。詳しくは「OAuthアクセストークンの作成とAPIでの使用」を参照してください。

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

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

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

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

管理センターで、サイドバーの「 アプリおよびインテグレーション」をクリックし、「API」>「OAuthクライアント」を選択します。
OAuthクライアントリストの右側にある「OAuthクライアントを追加」をクリックします。
以下のフィールドに入力して、クライアントを作成します。
- クライアント名：アプリケーションの名前を入力します。この名前が、アプリケーションへのアクセス許可をユーザーに求めるときにクライアント名として表示されます。また、Zendeskにアクセスできるサードパーティアプリのリストにも、この名前が表示されます。
- 説明：省略可能です。ユーザーにアクセス許可を求める際に、ユーザーに表示するアプリの簡単な説明を入力します。
- 会社名：省略可能です。アプリケーションにアクセス許可を付与するようユーザーに求めるときに表示する会社名です。この情報は、アクセスを付与しようとしている相手を識別するのに役立ちます。
- ロゴ（オプション）：省略可能です。アプリケーションにアクセス許可を付与するようユーザーに求めるときに表示するロゴです。JPG、GIF、PNG形式の画像を指定できます。最適な結果を得るには、正方形の画像をアップロードします。画像のサイズは、認証ページに合わせて自動的に調整されます。
- 識別子：アプリ名として入力した名前が再フォーマットされ、自動的に設定されます。この名前は変更してもかまいません。
- クライアント kind：PublicまたはConfidential。OAuthのPublicクライアントは、モバイルアプリやWebアプリなど、資格情報を安全に保存できない環境で実行されるアプリケーションです。Publicクライアントの場合は、PKCEを使用する必要があります。OAuthのConfidentialクライアントは、資格情報を安全に保持できるセキュアなサーバー上で実行されます。Confidentialクライアントの場合は、PKCE、クライアントシークレット、またはその両方を使用することができます。詳しくは「クライアントの kind プロパティについて」を参照してください。
- リダイレクトURL：ユーザーによるアクセス許可の決定をアプリケーションに送信するためにZendeskが使用するURLです。URLは絶対URLでなければなりません。相対URL、https（localhostまたは127.0.0.1でない場合）、改行で区切られたURLは入力しないでください。
「保存」をクリックします。
ページが更新され、事前に数値が入力された「シークレットキー」フィールドが新たに左下に表示されます。これが、OAuth 2.0の仕様で指定されている client_secret 値です。
「シークレット」の値をクリップボードにコピーし、安全な場所に保存します。メモ：シークレット値のテキストボックスの幅より長い場合があるため、コピーする前には必ず、シークレット値全体を選択していることを確認してください。
重要：セキュリティ上の理由で、シークレット全体が表示されるのは一回限りです。「保存」をクリックした後は、最初の9文字以外は表示されなくなります。
「保存」をクリックします。

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

クライアントの kind プロパティついて

OAuthクライアントは、以下のいずれかの値を持つ kind プロパティを持ちます。

Confidential：OAuthのConfidentialクライアントは、資格情報を安全に保持できるセキュアなサーバー上で実行されます。Confidentialクライアントの場合は、PKCE、クライアントシークレット、またはその両方を使用することができます。
Public：OAuthのPublicクライアントは、モバイルアプリやWebアプリなど、資格情報を安全に保存できない環境で実行されるアプリケーションです。これらのクライアントは PKCE を使用する必要があります。

Confidential クライアントの例としては、サーバーサイドWebアプリケーションが挙げられます。認証サーバーがWebアプリケーションにトークンや資格情報を提供しても、それらが外部に露出することはありません。

Public クライアントの例としては、モバイルアプリケーションや、Webブラウザなどのユーザーエージェント上で動作するJavaScriptアプリケーションが挙げられます。これらのクライアントでは、資格情報は容易に取得でき（多くの場合、目に見える形で存在し）ます。

クライアント kind は、OAuth仕様ではクライアントタイプとも呼ばれます。詳しくは、OAuth 2.0仕様の「Client Types」を参照してください。

kind プロパティは、Zendesk Supportのチケット管理システムにのみ適用されます。Chat、会話、Sellではサポートされていません。

既存のZendesk OAuthクライアントは、現在 kindプロパティが unknownに設定されています。これらの既存クライアントは、kindプロパティがpublicまたはconfidentialのいずれかに更新されるまで、影響を受けないままです。管理センターで作成される新しいOAuthクライアントは、作成時にkindプロパティを設定する必要があります。

メモ：既存のZendesk OAuthクライアントを使用していて、kindプロパティを publicに変更する場合は、まずPKCEを実装する必要があります。これを行わないと、PKCEが直ちに必要となるため、クライアントが機能しなくなります。

管理センターで作成されるすべてのOAuth新しいクライアントについて、kindプロパティを必ず設定してください。api/v2/oauth/clients endpointエンドポイントで作成したOAuthクライアントではkindプロパティは必須ではありませんが、Zendeskではこのプロパティを含めることを推奨しています。

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

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

このフローではリフレッシュトークンを利用することで、ユーザーの再認可を行わずに新しいアクセストークンを生成できます。APIが expires_in パラメータを通じてトークンの有効期間を指定している場合、アクセストークンは期限切れになる可能性があります。このような場合、付与されたリフレッシュトークンを使用して、アクセストークンの有効期限が切れたときに新しいアクセストークンを取得する仕組みを実装してください。

Authorization Code Grant Flow（認証コードグラントフロー）を実装するには、以下の機能をアプリケーションに追加する必要があります。

ステップ1 - ユーザーをZendeskの認可ページに送る
ステップ2 - 認可に関するユーザーの決定を処理する
ステップ3 - Zendeskからアクセストークンを取得する
ステップ4 - APIコールでアクセストークンを使用する

OAuth認証コードフローを実装するWebアプリケーションの構築方法については、「Using OAuth to authenticate Zendesk API requests in a web app」を参照してください。

認証コードグラントメソッドは 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から認証コードを受け取った場合、アプリケーションはその認証コードをアクセストークンとリフレッシュトークンに交換して取得できます。トークンを取得するには、Create Token Grant TypeエンドポイントにPOSTリクエストを送信します。

https://{subdomain}.zendesk.com/oauth/tokens

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

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

grant_type："authorization_code"の値を指定します。
code：ユーザーがアクセスを許可された後にZendeskから受け取った認証コードを使用します。
client_id：管理センター（「アプリおよびインテグレーション」>「API」>「OAuthクライアント」）で作成したOAuthクライアントの一意のIDを指定します。詳しくは「アプリケーションをZendeskに登録する」を参照してください。
client_secret：管理センター（「アプリおよびインテグレーション」>「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：アクセストークンの有効期限（秒単位）。300秒（5分）から172,800秒（2日間）の間の値を指定してください。
refresh_token_expires_in：リフレッシュトークンの有効期限（秒単位）。604,800秒（7日間）から7,776,000秒（90日間）の間の値を指定してください。

詳細については、APIリファレンスの「Create Token Grant Type」エンドポイントを参照してください。

リクエストはhttps経由で送信し、プロパティはJSON形式でフォーマットする必要があります。カスタムまたはサードパーティのアプリケーションを使用してAPIリクエストを行う場合、プロパティ値の適切なフォーマットについては、そのアプリケーションのドキュメントを参照してください。

Pythonのrequestsライブラリを使用する

response = requests.post(
    f'https://{subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'authorization_code',
        'code': f'{your_code}',
        'client_id': f'{your_client_id}',
        'client_secret': f'{your_client_secret}',
        'redirect_uri': f'{your_redirect_url}',
        'scope': 'read',
        'expires in': 172800,
        'refresh_token_expires_in': 800000
    }
)

応答の例

Status: 201 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f",
  "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"

期限切れのアクセストークンを置き換える

アクセストークンは一定時間後に失効します。アクセストークンと共に受け取ったリフレッシュトークンを使用して、新しいアクセストークンをリクエストしてください。新しいアクセストークンを取得するために、認証コードフローを再度実行する必要はありません。

アプリケーションは、期限切れのアクセストークンと期限切れのリフレッシュトークンを処理するフォールバックメカニズムを実装する必要があります。たとえば、アクセストークンの期限が切れた場合やエラーが発生した場合は、ハンドラーを使用してアクセストークンを更新してください。更新プロセスが失敗した場合、またはアクセストークンに紐付いたリフレッシュトークンが存在しない場合は、ユーザーを https://{subdomain}.zendesk.com/oauth/authorizations/new にリダイレクトして、アプリケーションを再認可してください。

アクセストークンの期限切れを検出する

アクセストークンの有効期限を確認するには、トークンを使用してAPIリクエストを実行した後、401レスポンスを検出するコードを実装してください。レスポンスには以下のJSON文字列が含まれます。

{"error":"invalid_token","error_description":"The access token provided is expired, revoked, 
 malformed or invalid for other reasons."}

401レスポンスが返された場合は、アクセストークンと共に受け取ったリフレッシュトークンを使用してアクセストークンをリフレッシュするハンドラーを呼び出してください。

Pythonのrequestsライブラリを使用した例を以下に示します。

url = f'https://{your_subdomain}.zendesk.com/{endpoint}'
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(url, headers=headers)
if response.status_code == 401:     # if token has expired or is otherwise invalid
    access_token = refresh_access_token(refresh_token)
    headers['Authorization'] = f'Bearer {access_token}'
    response = requests.get(url, headers=headers)

アクセストークンを更新する

アクセストークンを更新するには、Create Token Grant TypeエンドポイントにPOSTリクエストを送信します。

https://{subdomain}.zendesk.com/oauth/tokens

リクエスト本文に以下のプロパティを含めてください。

grant_type："refresh token"という文字列を値として指定します。
refresh_token：アクセストークンと共に受け取ったリフレッシュトークンの値を指定します。
client_id：管理センター（「アプリおよびインテグレーション」>「API」>「OAuthクライアント」）で作成したOAuthクライアントのIDを指定します。詳しくは「アプリケーションをZendeskに登録する」を参照してください。
client_secret：管理センター（「アプリおよびインテグレーション」>「API」>「OAuthクライアント」）で作成したOAuthクライアントのシークレットを指定します。詳しくは「アプリケーションをZendeskに登録する」を参照してください。
scope：「スコープを設定する」を参照してください。
expires_in：アクセストークンの有効期限（秒単位）。300秒（5分）から172,800秒（2日間）の間の値を指定してください。
refresh_token_expires_in：リフレッシュトークンの有効期限（秒単位）。604,800秒（7日間）から7,776,000秒（90日間）の間の値を指定してください。

詳細については、APIリファレンスの「Create Token Grant Type」エンドポイントを参照してください。

Pythonのrequestsライブラリを使用したリクエストの例を以下に示します。

response = requests.post(
    f'https://{your_subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'refresh_token',
        'refresh_token': refresh_token,
        'client_id': client_id,
        'client_secret': client_secret,
        'scope': 'read',
        'expires in': 172800,
        'refresh_token_expires_in': 800000
    }
)

このリクエストは新しいアクセストークンとリフレッシュトークンを作成すると同時に、以前のトークンを無効化します。以下に応答の例を示します。

Status: 201 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f,
  "token_type": "bearer",
  "scope": "read"
}

両方のトークンを安全なデータストアに保存し、後で再利用できるようにします。