はじめに
業務でCybozuのAPIを学習する機会があったので、今回は特にAPIを使う前の準備で発生する認証の手順とその種類、選び方について記載していきます。
BizRobo!と連携するときに限らず、Cybozu APIを利用するためには必ず実施しなければならない手順なので参考になれば幸いです。
本記事ではkintoneを主軸に記載しています。
3つの認証方法
Cybozu APIには3つの認証方法があります。
1. パスワード認証
2. APIトークン認証
3. OAuth認証
まずはこれらの違いについて説明をしていきます。
パスワード認証
概要
Cybozu.comに登録されているログイン名とパスワードを利用する認証方法です。
普段kintoneにアクセスしている情報のみで認証が完了するため、これが最も簡単な方法です。
設定の手順
手順はこちら
まず権限の確認と編集を実施します。アクセス権がない方は管理者に問い合わせましょう。
アプリ画面より、右の歯車から設定に移動します。
設定 > アクセス権 > アプリに移動します。
ユーザーや組織ごとの権限の範囲を設定します。
今回使用するユーザーはすべてにチェックが入っているので、これらの操作が画面上とAPI操作どちらでも可能になります。
これで設定が完了しました。では実際に認証していきます。
まずはログイン名とパスワードを「:」で区切ります。
例 : ログイン名「hoga」, パスワードが「fugafuga」の場合
hoga:fugafuga
BizRobo!では認証と同時にkintone操作も実行しています。
なのでkintone操作に必要なkintoneのドメインをここに追加します。区切り文字はカンマ「,」です。
例 : ドメイン「https://hogehoge.com」, ログイン名「hoga」, パスワードが「fugafuga」の場合
https://hogehoge.com,hoga:fugafuga
これをDAステップで指定するとkintone操作が可能になります。
メリット
すぐにAPIの操作ができる
後述する認証に比べて準備が圧倒的に少ないので、手っ取り早く触ることができます。
まずテストしてみる場合には最適です。
認証から実行までが現場で完結する
権限の範囲に問題がなければ管理者と連携する必要がないので、API連携を実行するまでの工程が全て現場で完結します。
管理者にとって想定外の権限が付与されている場合は例外ですが・・・
デメリット
ユーザーの権限を変更しなければならない
もしやりたいことが今の権限でできない場合、このユーザーだけ特別な事情で権限を変更することになります。それがもし複数のアプリ、ユーザーに適用すると管理が大変なことになります。
利用シーン
調査に利用する
仕様の確認や、やりたいことができるのかどうか調査するときに利用すると便利です。
まず1人で試してみてから、開発に向けて後述する認証を実行するとスムーズに進みます。
個人の業務自動化に
管理者の承認を必要としない+普段のkintone操作の権限と同じなので、自分の仕事を自動化したいときには最適です。API連携という名のコーナーで差をつけましょう。
開発者が管理者のあなただけなら
もともと全権限を持っているユーザーであるあなたしか開発を担当しない場合、パスワード認証で十分なケースがほとんどです。サクっと認証を終わらせて開発に入りましょう。
APIトークン認証
概要
アプリごとに発行できるAPIトークンで認証する方法です。
管理者に発行申請してもらう必要はありますが、発行自体は簡単なのでお手軽に実行できます。
これはパスワード認証と違ってAPIトークンに付与される権限に依存するため、ユーザーの権限を変更することなくAPI連携が可能になります。
たとえば「レコードの削除」権限がないユーザーが削除の権限を持つAPIトークンを利用すると削除が可能になります。
設定と手順
手順はこちら
管理者ではない方は管理者にAPIトークンの発行申請をしましょう。
以下の手順を共有すればしていただけると思うので、権限の範囲を伝えましょう。
今回は「レコードの削除」以外の権限を持ったAPIトークンを発行します。
アプリ画面より、右の歯車から設定に移動します。
設定 > カスタマイズ/サービス連携 > APIトークンに移動します。
APIトークンの管理画面に遷移するので、「生成する」ボタンをクリックします。
APIトークンが作成できました。
次に権限の設定をします。今回はレコードの削除以外を許可するので、そのようにチェックを入れます。
最後に保存して完了です。では実際にBizRobo!で認証していきます。
パスワード認証と同じようにkintoneのドメインとAPIトークンを「,」で区切って実行します。
例 : ドメイン「https://hogehoge.com」, APIトークン「fugafugaToken」の場合
https://hogehoge.com,fugafugaToken
メリット
ユーザーの権限を変更しなくてよい
パスワード認証のデメリットであるユーザー権限の変更をせずとも、APIトークンに権限を付与することで実行が可能になります。APIトークンに付与した権限は普段のkintone操作に影響しないので管理者も安心です。
1つのAPIトークンで複数のユーザーに同じ権限を付与できる
APIトークンは複数のユーザーが利用できるので権限を一括管理することができます。
また、APIトークンは一度のAPI実行に9個まで利用できるので、わざわざ実行先のアプリを変更するたびに設定を編集する必要がなくなります。
デメリット
一度に9個までのAPIトークンしか利用できない
開発の規模が大きくなると、9個までという制約が重くのしかかります。
そういった場合はOAuth認証を検討するタイミングかと思います。
漏洩リスク
APIトークンはただの文字列なので、漏洩のリスクがあります。
管理者はユーザーへの提供を慎重に行いましょう。
利用シーン
運用のスタートアップに
本番環境での運用はまずAPIトークンでやってみましょう。パスワード認証のように既存の設定をいじるわけでもなく、だめだったらAPIトークンを削除するだけで軌道修正ができるので柔軟に対応できます。
OAuth認証
概要
Cybozu.comで作成できるOAuthクライアントを利用した認証方法です。
いままでの認証はどちらもアプリ単位でしたが、OAuth認証はkintone全体の権限を操作できます。
例えば「レコードの削除」をOAuth認証で許可すると全アプリのレコードを削除できるようになります。
なのでCybozu管理者が開発に参加する大規模な開発時に使用しましょう。
設定と手順
手順はこちら
Cybozu.com共通管理画面にアクセスします。
システム管理 > OAuthにアクセスします。
高度な連携を設定する > OAuth クライアントの追加にアクセスします。
OAuthクライアントを作成します。以下の情報を入力します。
- クライアント名：必須。クライアントの名前です。例として「Cybozu Connector Test」を指定します。
- クライアントロゴ：省略可。クライアントのロゴ画像です。
-
リダイレクトエンドポイント：必須。OAuthクライアントが認可コードを受け取るURLです。例として「https://localhost:15002/CybozuApp/」を指定します。
「保存」をクリックすると、クライアントが作成できます。
以下の項目が自動で生成されるので、これらをメモします。
- クライアントID：アプリケーションをcybozu.comに登録したときに生成される一意のIDです。
- クライアントシークレット：アプリケーションをcybozu.comに登録したときに生成されるシークレット値です。
- 認可エンドポイント：OAuthの認可エンドポイントURLです。
- トークンエンドポイント：OAuthのトークンエンドポイントURLです。
値はいつでもOAuthクライアントの編集画面で確認できます。
鉛筆マークをクリックすると編集画面に遷移します。
OAuthクライアントが作成できたので、次はこれを利用できるユーザーを選択します。
デフォルト値は誰も選択されていない状態なので忘れずに追加しましょう。
追加できたら、実際にOAuth認証を実行します。
具体的な仕組みは割愛するので興味がある方は調べてみてください。
まず認可コードをもらうためのURLを作成します。{}内の項目を環境に合わせて変更します。
URL
https://{subdomain}.cybozu.com/oauth2/authorization?client_id={クライアントID}&redirect_uri={リダイレクトエンドポイント}&state={state}&response_type=code&scope=k:app_record:read k:app_record:write k:app_settings:read k:app_settings:write
- subdomain : 自身の環境のkintoneドメイン
- state : OAuth 2.0の仕様に従って、CSRF対策のためのランダムな値を指定します。特に問題なければ「stateTest」とかでもOKです。
-
scope : ここで権限の範囲を指定します。今回は以下の項目を許可します。
- アプリのレコードの閲覧（k:app_record:read）
- アプリのレコードの追加、変更、削除（k:app_record:write）
- アプリの設定の閲覧（k:app_settings:read）
- アプリの設定の更新（k:app_settings:write）
URLを作成してブラウザに叩いたら、以下のような確認画面に遷移します。問題なければ「許可」をクリックします。
成功するとURLの途中に「../?code=fugafuga」があります。これが認可コードです。
これらをもとにDAステップで認証すれば完了です。
メリット
広範囲の権限を一括管理
アプリ全体に対して権限を付与するため、10個以上のアプリを操作したい場合は非常に有用です。
管理者と強く連携しながらkintone全体を操作するならかなり便利な認証になります。
デメリット
他2つ比べると手順が大変
やはりネックになってくるのは手順の複雑さです。OAuthとは？からつまづきポイントがあるので、大規模開発に向けて根気強く目指していく方針が重要となります。
権限の範囲が広大すぎる
ひとつの権限を渡すだけで、良くも悪くもアプリで全体にまで影響します。
kintoneの管理が盤石ではない状態で触るのはリスクが高い認証になっています。
利用シーン
kintone全体を操作する大規模開発
kintone全体を自動化する場合はOAuth認証が有効です。特に操作したいアプリが常に10個以上ある場合は管理がぐっと楽になります。
テスト
OAuth認証は権限の範囲がとても広いので、テスト環境で試す場合は非常に有効です。もし管理者がOAuth認証を許可してくれた場合は、制限のない自由な世界を楽しみましょう。
まとめ（認証の選び方）
| 認証方法 | 手軽さ | 個人開発 | 小規模開発 アプリ1～9個まで |
中～大規模開発 アプリ10個～ |
|---|---|---|---|---|
| パスワード認証 | ◎ | ◎ | × | × |
| APIトークン認証 | 〇 | △ | ◎ | △ |
| OAuth認証 | × | △ | × | ◎ |
まずはパスワード認証でkintone APIを触ってみる
管理者との連携がいらないパスワード認証で、今の権限の範囲で遊んでみましょう。そこから実現できることや足りない権限を洗い出し、「良いことたくさんあるからAPIトークン or OAuth認証してくれ！」と管理者にアピールしましょう。
APIトークン認証で本格的に着手～運用まで
パスワード認証ではゴールまでたどり着けないケースがほとんどだと思います。
足りないものを洗い出し、管理者と連携して進めていきましょう。
煮詰まってきたらOAuth認証で大規模な自動化へ
APIトークン認証を使ってどんどんkintone開発が進んでいくと、APIトークン認証の制限の壁に当たります。
そうなったらOAuth認証を使ってkintoneのあらゆる操作、アプリを連携していきましょう。
以上が認証についての手順と選び方でした。
特にパスワード認証とAPIトークン認証はEUCとして非常に活用できる認証なのでぜひ検討してみてください。
認証を終えて、楽しくAPI連携していきましょう！