はじめに
Garoon 2018年8月版 からCSRFトークンを取得する関数が実装されました。
今回はCSRFトークンの簡単な説明と利用例を過去のサンプルを用いて説明していきます。
CSRFトークンとは？
CSRFトークンを使う理由は、kintone版の記事が参考になります。
引用１）kintone REST API をセッション認証で実行する場合は、CSRFトークンが必要となります。（HTTPメソッドがPOST, PUT, DELETEの場合のみ）
Garoonに置き換えて考えましょう。
Garoonの場合、ユーザー認証にはパスワード認証とセッション認証の2つが存在します。
Garoon REST APIの共通仕様のユーザー認証をご確認ください。
引用１にある通り、セッション認証で実行する場合はCSRFトークンが必要になります。（GET以外）
引用２）kintone内（JavaScript）でAPIを実行する場合は、HTTPメソッドに関わらずCSRFトークンは不要となります。
ただし、例外としてJavaScriptからXMLHttpRequestを使ってREST APIを実行する時はCSRFトークンが必要となります。
kintone REST APIはAPIを叩くための独自関数kintone.api()が用意されています。
この関数を使ってkintone REST APIを実行する場合はCSRFトークンは必要ないという意味です。
こちらもGaroonに置き換えて考えてみましょう。
Garoon REST APIもGaroon独自関数のGaroon.api()を使えばCSRFトークンが必要ない。
と置き換えることができますが、現在Garoon REST APIを実行する用の独自関数は実装されていません。（2018年8月現在）
そのため、Garoon REST APIを実行するには、XMLHttpRequestで実行する必要があります。
つまり、Garoon REST APIでGETメソッド以外をセッション認証で実行する際は、CSRFトークンが必要となります。
2019年2月版Garoonより、garoon.api()が実装されます。
このアップデートにより、Garoonもkintoneと同様に
garoon.api()を用いてAPIを実行する場合は、HTTPメソッドに関わらずCSRFトークンが不要となります。
まとめ
Garoon内のJavaScriptカスタマイズにおいて、garoon.api()を使用してGaroon REST APIを実行する場合、CSRFトークンは不要。
ただし、以下の条件すべてに当てはまる場合、CSRFトークンを使用する必要があります。
- garoon.api()以外でAPIを実行
- セッション認証
- GETメソッド以外
サンプル
ここからは実際に過去のサンプル記事のシナリオを用いてCSRFトークンを利用します。
細かいワークフローの設定は上記の記事を参考に設定してください。
「wf_to_sch.js」のコードだけ、下に提示したサンプルコードを用いてください。
サンプルコード
68行目の{subdomain}のみ、ご自身の環境のサブドメイン名に変更してください。
サンプルコード解説
16行目
こちらが新規で追加されたGaroon JavaScript APIです。
18～41行目
リクエストボディを生成している関数です。
スケジュール登録APIでは、登録する情報をボディに乗せる必要があります。
オブジェクトの詳細な構造はスケジュールのeventオブジェクトが参考になります。
44～63行目
ワークフロー申請が承認されたときのイベントのイベントオブジェクトから、リクエストボディに必要な情報を抜き出しています。
詳細はワークフローのrequestオブジェクトをご確認ください。
66～73行目
このサンプルコードでは、jQuery.ajax()を用いてREST APIを実行しています。
jQuery.ajax()について
公式リファレンス：http://api.jquery.com/jquery.ajax/
おわりに
CSRFトークンを取得できるようになり、Garoon REST APIが簡単に実行できるようになったことがわかるかと思います。
Garoon REST APIは今後も機能を増やしてく予定です。
Garoonのこの機能にAPIが欲しい！などの要望がありましたら、次期Garoon REST API 人気投票から簡単なアンケートにご協力お願いします。
このTipsは、2018年8月版 Garoonで確認したものになります。
記事に関するフィードバック
記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。