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"
65件のコメント
Dane
This error means that you are not using a valid token. It's possible that instead of an OAuth, you are just using an API token. Please try to follow the steps again and contact our support directly if you encounter the same issue.
0
Prashant Bajpai
Hello,
I generated the access token using OAuth client flow with "read" scope. When I try fetching any details, I get this error -
What am I doing wrong?
0
Dane
OAuth 2 is used to authenticate all your application's API requests to Zendesk. Once it has been completed, you can refer to Zendesk API, for all the available data that you can extract from your Zendesk instance.
0
Mullai Rajan
How to get the Client's data such as email id, username, etc., After being OneAuthenticated in my Application, to be specific after obtaining the access_token, How to extract or fetch the client's Data?
Just like the JSON, we get from the 'me.json' request.
1
Dainne Kiara Lucena-Laxamana
Hi a a.
Based from the screenshot you provided I would suggest looking into this developer doc as well to help you with the Help Center API.
The "invalid authorization request no such client" error can occur when the Client ID/secret is incorrect, or if an incorrect redirect URL is configured.
The OAuth "Client ID" that should be used is the "Unique Identifier" value that's displayed in the Admin Center > Apps and integrations () > APIs > Zendesk APIs > OAuth Clients screen:
If using our APIs to access the list of OAuth clients, it's the "identifier" attribute returned by the /api/v2/oauth/clients endpoint. Make sure to use this identifier value and not the 'id' value returned by the API.
Hope this helps!
0
a a
i am getting this error
0
Wyatt
Hi, is there a way to force a user to re-login when they go through the OAuth flow? I tried adding "&login=true" to the URL, but that did not work.
0
Pavan
Hi Support Team,
How do I renew the token which is generated using https://{{baseurl}}/oauth/tokens? Please help.
0
Georg
Thanks, Dainne!
0
Dainne Kiara Lucena-Laxamana
Hi Georg
This might be an article (OAuth Tokens-Scopes) worth checking out. It provides details regarding the scopes parameter so you can set the access as either "read" or "write". Hope this helps!
0
サインインしてコメントを残します。