Chatwork Creator's Note

ビジネスチャット「Chatwork」のエンジニアとデザイナーのブログです。

ビジネスチャット「Chatwork」のエンジニアとデザイナーのブログです。

読者になる

OAuth2 offline_accessスコープ対応

こんにちは、かとじゅんです。

今回はOAuth2のスコープに offline_access という新しいスコープが追加されたので以下にお知らせします。ひとことで言うと、チャットワークと連携するBOTを作りやすくするスコープです!

詳しくはこちらを参照ください。

チャットワークAPIドキュメント

用語の定義

まず目的を説明する前に、用語の定義から説明させてください。

offline_accessのoffline(オフライン)とは、リソースオーナー(チャットワークユーザー)が、OAuth2クライアント(以下、クライアント)上で不在の状態のことを指します。逆はオンラインと呼びます。わかりにくければ、オフラインがログアウト状態、オンラインがログイン状態と考えて差し支えありません。つまり、offline_accessとは、リソースオーナーのオフライン時でも、クライアントがチャットワーク APIにアクセスできるスコープです。

従来はどうだったか

これまでと同様offline_accessスコープを利用しない場合は、従来どおり14日間でリフレッシュトークンの期限が切れるため、 クライアントはリソースオーナーから認可を再度受ける必要があります。たとえば、受付サービスの設定画面からOAuth2の認可を受けたとしても、14日後には受付サービスからチャットワークの通知連携が切れてしまうことになります。この動作は、現在でもデフォルトの動作仕様であり、offline_accessスコープを指定しない場合は14日間でリフレッシュトークンは期限切れとなります。 このようにリソースオーナーがクライアント上でオンラインとは限らないユースケースでは、不都合が生じてしまいます。実際、チャットワーク APIユーザ会でも、もう少し長くできないかという要望もあったため、offline_access スコープに対応しました。

offline_accessスコープ

前置きが少し長くなってしまいましたが、そのoffline_accessスコープを指定した場合、リフレッシュトークンの期限はリソースオーナーが認可を失効するまで利用でき、その間はアクセストークンを更新し続けられます。他の仕様は何も変わりません。認可の失効も今までどおりの方法(管理画面)で可能です。認可が失効されるまで、クライアントは一度認可を受けるといつでも新しいアクセストークンが手に入ります。特にBOTなどの用途ではこのような認可方法は重宝するでしょう。スコープの指定とリフレッシュトークンの期限の関係は、以下のようになります。

スコープ リフレッシュトークンの払出 リフレッシュトークンの期限
offline_accessの指定なし(デフォルト) あり 14日間
offline_access あり 無期限

※ オンライン・オフラインにかかわらず、期限内であっても認可が失効された場合は、リフレッシュトークンはその時点で無効になります。

オンラインとオフラインのどちらを使うべきか

使いやすくなる反面、リフレッシュトークンの期限は実質無限であるため、漏洩のリスクはオンラインに比べ相対的にあがります。リフレッシュトークンをクライアントで漏洩しないように秘匿することは言うまでもありませんが、オンラインが前提のクライアントであれば、offline_accessスコープを指定しないようにしてください。さらに、オフライン時でも利用したい場合は、offline_accessスコープを指定するとよいでしょう。

offline_accessスコープはOAuth2の仕様に含まれるのか?

もともとoffline_accessというスコープ名は、OAuth2には含まれておらず、OpenID Connectにあります。例えば、Googleのoffline_accessでは、offline_accessを指定したときだけ、リフレッシュトークンが払い出され、クライアントはリソースオーナーがオフラインでもアクセストークンの更新が継続できます。これらの仕様は参考にしていますが、そのまま取り込んでいないので、独自仕様だと考えてください。弊社の場合は、すでにデフォルトでリフレッシュトークンを払い出す仕様となっていましたので、前述したように、offline_accessスコープ指定の有無に関わらず、リフレッシュトークンは払い出されます。リフレッシュトークンの期限のみが変わります。

オンライン時のリフレッシュトークンの期限について

最後に本題とは直接関係ありませんが、オンライン時の注意点をご案内します。現状、オンライン時のリフレッシュトークンの期限は14日間ですが、offline_accessスコープを追加したことにより、かなり短くなる可能性があります(仕様変更がある場合は別途お知らせします)。このリフレッシュトークンの期限はあらかじめ予測せずに、アクセストークンの更新時にinvalid_grantエラーが返ってきた場合は、そのリフレッシュトークンはすでに無効化されています。そのまま継続的な更新を続けても無意味ですので、定期更新を中断し認可を最初からやり直すようにしてください。

以上、簡単ですが、OAuth2の機能追加のお知らせでした。ご質問・不明点がある場合はこちらまでお問い合わせください!