社内アプリケーションをテストまたは構築している場合は、基本認証(ユーザー名とパスワードが必須)、またはAPIトークン認証(依然としてユーザー名が必要)の場合のように、APIリクエストを特定のユーザーに関連付けたくない場合があります。3番目の選択肢として、OAuthアクセストークンを使用する方法があります。
一見したところ、OAuthトークンを作成することは、承認フローが複雑なため、大変な作業のように思うかもしれません。しかし、プロセスの最も複雑な部分をスキップしてAPIから直接アクセストークンを取得することができます。この記事では、テスト目的で独自のOAuthトークンだけを簡単な手順で作成する方法について説明します。
OAuthクライアントを作成する
まず最初に、テスト用のOAuthクライアントを作成します。
- 管理センターで、サイドバーにあるアプリおよびインテグレーションアイコン()をクリックし、「API」>「Zendesk API」を選択します。
- 「OAuthクライアント」タブで、リストの右上部にある「OAuthクライアントを追加」をクリックします。
テスト目的でクライアントを設定することは、通常のOAuthクライアントを作成することとは少し異なります。以下の違いに注意してください。
- リダイレクト先は有効なHTTPS URLである必要があります、しかし、このプロジェクトでは実際のWebサイトである必要はありません。例:https://somesite.com.
- コードで使用するクライアントの名前は、一意の識別子にします。OAuthクライアントAPIのList ClientsエンドポイントでクライアントIDを取得することもできます。
- 将来の参考にするために、現在のシークレットをコピーしておくと良いかもしれません。作成した後に再度表示されることはありませんが、OAuth Webアプリを構築するため、または他のプロジェクトで使用する場合は、これが必要になります。
- 他のフィールドはすべてダミーデータで埋められます。
アクセストークンを作成する
これで、OAuthトークンAPIを使ってトークンを作成するために必要なものがすべて揃いました。cURLを使ってリクエストを作成する方法は次のとおりです。
curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
-H "Content-Type: application/json" \
-d '{"token": {"client_id": "your_client_id", "scopes": ["read", "write"]}}' \
-X POST -v -u {email_address}:{password}
このコードについて注意すべき点がいくつかあります。
- サブドメインのプレースホルダを必ず自分のサブドメインに置き換えることを忘れないでください
- "client_id"の値は、OAuthクライアントページからコピーした番号です。
- 特にリソースへの読み取り専用アクセスをテストしているのでなければ、スコープを["read", "write"]に設定してください。
- 組織でシングルサインオン(SSO)を使用していて、ZendeskアカウントからZendeskパスワードが削除されている場合は、リクエストの認証にAPIトークンを使用する必要があります。
-u {email_address}/token:{api_token}
Support APIのドキュメントで「API token」を参照してください。
cURLリクエストを実行します。いくつかのプロパティを含むトークンオブジェクトからなるJSONパッケージが返されます。
"full_token"の値がアクセストークンです。コピーして安全に保管してください。
レスポンスの"expires_at"プロパティが"null"になることに注意してください。つまり、クライアント自体を削除するまでトークンは機能しません。また、次回管理センターのOAuthクライアントリストにアクセスすると、新しいクライアントのアクティブなトークンの数が1つ増えているはずです。
新しいアクセストークンを使用する
アクセストークンを使う対象がなければ、アクセストークンには意味がありません。 以下の例では、いずれもユーザー名やパスワードを使用していません。それは意図的な設計です。OAuthアクセストークンはどんなユーザーアカウントにも依存しません。これは、アプリやスクリプトで使う際の利点の1つです。
アクセストークンを使用してAPIリクエストを認証する
認証を要件とするすべてのAPIコールには、OAuthアクセストークンを使用しできます。たとえば、通常はチケットエンドポイントに次のようなコールが行なわれます。
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-u {email_address}:{password}
アクセストークンを使用すると、次のようになります。
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-H "Authorization: Bearer {access_token}"
APIクライアントでアクセストークンを使用する
また、ZendeskのAPIクライアントのいずれかで、OAuthアクセストークンを使用することもできます。たとえば、Rubyクライアントは、次のように、通常ユーザー名とパスワード(またはAPIトークン)を使用した認証を必要とします。
config.username = "user email" config.password = "user password"
代わりにアクセストークンを使用すると、次のようになります。
config.access_token = "your OAuth access token"