FileMaker から Google Cloud APIs を利用する際の認証について
こんにちは。
株式会社フルーデンスの小巻です。
FileMakerからGoogleの各APIを利用するためのソリューションをGitHubに公開しているのですが、解説記事を書いていませんでした。
よく質問をいただくので、解説記事を何回かに分けて公開したいと思います。
対象者
FileMaker と Google Cloud APIs の連携をしたい方
ゴール
自分のやりたいことを実現するためには、どのような認証方法使えば良いか、概要を理解できる。
はじめに
今回のブログでは、公式のドキュメントを引用しつつ補足説明をする形になります。
内容に間違っている点がありましたら、ご指摘頂ければと思います。
公式ドキュメント
Google Cloud APIsを利用する際の認証については、以下のドキュメントに記載がありますので、まずは一通り確認してください。
「認証ストラテジー」について
FileMakerからAPIを利用する場合は、以下の3種類になります。
| 要件 | 推奨 |
|---|---|
| 一般公開データに匿名でアクセスする | API キー |
| エンドユーザーに代わって限定公開データにアクセスする | OAuth 2.0 クライアント |
| Google Cloud 環境外でサービス アカウントに代わって非公開データにアクセスする | サービス アカウント キー |
GCP(Google Cloud Platform)にログインし「認証情報を作成」をクリックすると、上に記載した内容と同じ選択肢が表示されます。
「APIキー」について
API キーは、プリンシパルなしでアプリケーションを識別する暗号化された単純な文字列です。
一般公開データに匿名でアクセスする場合に便利で、割り当てや課金のためにAPI リクエストをプロジェクトに関連付けるために使用されます。
上記の公式ドキュメントの説明の通り、任意のアカウントのGmailやGoogle Calendarなどではなく、Goole Mapsなどのような匿名でAPIを利用する場合に「APIキー」を利用します。
例えば、APIキーを使い実行できるのは、以下のようなAPIです。
- Google Maps Platform
- Cloud Text-to-Speech
- Cloud Vision API
- Sheets API
- Cloud Translation – Basic
上記以外にも、様々なAPIが「APIキー」で利用できます。
自分が利用したいAPIが、「APIキー」で利用できる場合は「APIキー」を作成するだけですので、比較的簡単にAPIを利用することができます。
Google Calendarは、以前は「APIキー」でアクセスできたようですが、以下のURLを見ると、現在は「APIキー」ではアクセスできないようです。
Authorizing Requests to the Google Calendar API | Google Developers
「APIキー」の参考情報
API キーを使用する理由と条件 | OpenAPI を使用した Cloud Endpoints | Google Cloud
「OAuth 2.0 クライアント」について
アプリケーションがエンドユーザーに代わって Google Cloud APIs にアクセスする必要がある場合、アプリケーションは OAuth 同意フローを開始します。
ユーザーが OAuth 同意フローを完了すると、アプリケーションは、ユーザーの代わりにアプリケーションで Google Cloud APIs を呼び出せるようにするアクセス トークンを受け取ります。
公式の図を見て頂くと分かやすいと思います。
同意フローの大まかな説明
- 開発者は、アプリケーションを作成します。
- 開発者は、同意画面のURLを作成します。
- ユーザーは、ブラウザで同意画面のURLを開きます。
- ユーザーは、同意画面で同意します。
- ユーザーは、開発者が指定したリダイレクト先のURLに移動します。(URLに認可コードがセットされています。)
- リダイレクト先のWebサイトは、URLにセットされている認可コードにアクセスできます。
- この先は、環境によって様々です。
補足のために、具体例を2つ紹介します。
具体例1： OAuth 2.0 Playground
例えば、以下のPlaygroundのURLにアクセスし、Gmail APIを選択し「Authorize APIs」をクリックすると、以下のような同意画面が表示されます。
ログインします。
同意すると、予め指定されたURLにリダイレクトされます。
URLを確認すると、URLに「code=HOGE」のように、認可コードがセットされていることが確認できます。
この認可コードを使いrefresh_tokenとaccess_tokenを取得することができます。
「Exchange authorization code for tokens」をクリックします。
refresh_tokenとaccess_tokenが取得できます。
（refresh_tokenとaccess_tokenの違いやexpireなどについては、別の記事にて解説します。）
ここで取得したaccess_tokenをheaderにセットすることで、ログインしたユーザとしてGmail APIが利用できます。
「List possible operations」をクリックすると、利用できるAPIの一覧が表示されます。
「GetProfile Users」をクリックします。
Request URLに「https://gmail.googleapis.com/gmail/v1/users/{userId}/profile」とセットされます。
「{userId}」を「me」に変更し「https://gmail.googleapis.com/gmail/v1/users/me/profile」とします。
「Send the request」をクリックすることで、画面右側に該当のAPIのレスポンスが表示されます。
具体例2： TodoistのGoogle Calendar連携機能
Todoist というタスク管理ツールには、以下のようなGoogle Calendarと連携する機能があります。
「カレンダーを接続」をクリックします。
Playgroundの時と同様に、同意画面に移動します。
ログインし、同意すると、TodoistのプログラムからGoogle CalendarのAPIを利用できるようになります。
「APIキー」か「OAuth 2.0 クライアント」のどちらを使えば良いのか分からない場合の確認方法
基本的には、ユーザーの情報にアクセスする必要のあるAPIの場合は「OAuth 2.0 クライアント」を利用します。
また、各APIのドキュメントを読めば、どの認証方法を使うべきか分かるはずですが、最初のうちは分からないかもしれません。
例えば、先ほどのGmail APIが「APIキー」で使えるかどうかを確認したい場合、以下のように操作することで確認できます。
以下のAPIのReferenceのページに移動し「Try this method」の「Google OAuth 2.0」のチェックを外し、「EXECUTE」をクリックします。
Method: users.getProfile | Gmail API | Google Developers
エラーに「API keys are not supported by this API.」と記載されています。
「OAuth 2.0 クライアント」の参考情報
- The OAuth 2.0 Authorization Framework
- 上記のURLに、OAuth 2.0についての詳細が記載されていますので、より詳細な情報が知りたい方は、参照ください。
- OAuth2.0を使用してGoogleAPIにアクセスする | Google Identity Platform | Google Developers
無料版 Google アカウントではなく Google Workspace アカウントをおすすめする理由
アカウントの種類は、以下の2種類になります。
- 無料版 Google アカウント(hoge@gmail.com)
- Google Workspace アカウント(hoge@yourdomain.com)
業務で利用されるなら、無料版のGoogleアカウントを利用することはおすすめしません。
詳細は、別途記事にしますが、無料版 Google アカウントを対象にした「外部向け」のOAuth 2.0 クライアントを作成すると、スコープによってはGoogleの確認作業が必要になります。
また、現在のようなフローになるまで、仕様がかなり変更されていますし、今後も仕様が変更になる可能性が考えられます。
そのため、業務で安定して利用するなら、Google Workspace アカウントを利用し、「内部向け」のOAuth 2.0 クライアントを作成することをおすすめします。
OAuth 2.0 の「外部向け」や「内部向け」、確認作業などについては、以下のドキュメントをご確認ください。
Setting up OAuth 2.0 – Google Cloud Platform Console Help
「サービスアカウントキー」について
サービス アカウント | IAM のドキュメント | Google Cloud
サービス アカウントとは
サービス アカウントは、ユーザーではなく、Compute Engine 仮想マシン（VM）インスタンスなどのアプリケーションやコンピューティング ワークロードで使用される特別なアカウントです。
アプリケーションはサービス アカウントを使用して、承認された API 呼び出しを行います。
これは、サービス アカウント自体として承認されるか、ドメイン全体の委任により Google Workspace または Cloud Identity ユーザーとして承認されます。サービス アカウントは、アカウント固有のメールアドレスで識別されます。
サービス アカウントとユーザー アカウントの違い
サービス アカウントは、いくつかの重要な点がユーザー アカウントと異なります。
- サービス アカウントにはパスワードがなく、ブラウザやクッキーでログインできません。
- サービス アカウントは、Google への認証とデータの署名に使用される公開 / 秘密 RSA 鍵ペアに関連付けられています。
- あるサービス アカウントの代わりとして、他のユーザーまたは他のサービス アカウントを使用できます。
- ユーザー アカウントとは異なり、サービス アカウントは Google Workspace ドメインに属していません。
ドキュメントやイベントなどの Google Workspace アセットを Google Workspace ドメイン全体で共有しても、サービス アカウントとは共有されません。
同様に、サービス アカウントによって作成された Google Workspace アセットは、Google Workspace ドメインには作成されません。
そのため、Google Workspace と Cloud Identity 管理者はこれらのアセットを所有することも、管理することもできません。
サービス アカウントの使用と管理のベスト プラクティス | IAM のドキュメント | Google Cloud
サービス アカウントの使用と管理のベスト プラクティス
サービス アカウントは人間以外のユーザーを表します。
これは、カスタム アプリケーションなどのワークロードで、エンドユーザーの関与なしにリソースにアクセスする場合や、アクションを実行する必要がある場合を対象としています。
サービス アカウントを使用するタイミングの選択
サービス アカウントは多くの異なる目的で使用できますが、常に最適な選択肢であるとは限りません。
手動操作を必要としないシナリオにサービス アカウントを使用する
すべてのアプリケーションが人間のユーザーとやり取りを行うわけではありません。
アプリケーションがバックグラウンドで人手を介さず自動的に実行されている場合もあります。
ユーザー不在で実行されるアプリケーションには、バッチジョブ、キューから読み取られたメッセージがディスパッチされるワーカー プロセス、リソース モニタリング エージェントなどがあります。
上記の公式ドキュメントの説明の通り、FileMakerなどのアプリケーションがバックグラウンドで実行するようなケースで利用します。
サービスアカウントを作成し、その後キーを作成すると、下図のような認証情報が記載されたJSONファイルがダウンロードできますので、中身を確認すると「test-ab3euo@stable-hoge-123456.iam.gserviceaccount.com」のようなメールアドレスが割り当てられていることが分かります。
そのため、サービスアカウントから、Google DriveやGoogle Calendarを操作したい場合は、下図のように共有設定に「test-ab3euo@stable-hoge-123456.iam.gserviceaccount.com」を追加することで、サービスアカウントからアクセスできるようになります。
Google Driveの共有設定
Google Calendarの共有設定
Google Spreadsheetの共有設定
サーバー間アプリケーションにOAuth2.0を使用する | Google Identity Platform | Google Developers
ドメイン全体の権限をサービスアカウントに委任する
Google Workspaceアカウントをお持ちの場合、組織の管理者は、GoogleWorkspaceドメインのユーザーに代わってユーザーデータにアクセスすることをアプリケーションに許可できます。
たとえば、Google Calendar APIを使用してGoogleWorkspaceドメイン内のすべてのユーザーのカレンダーにイベントを追加するアプリケーションは、ユーザーに代わってサービスアカウントを使用してGoogle CalendarAPIにアクセスします。
ドメイン内のユーザーに代わってデータにアクセスすることをサービスアカウントに許可することは、サービスアカウントへの「ドメイン全体の権限の委任」と呼ばれることもあります。
上記の公式ドキュメントの説明の通り「GoogleWorkspaceドメインのユーザーに代わってユーザデータにアクセスすることをアプリケーションに許可」の設定をすることで、サービスアカウントから任意のユーザーのGoogle CalendarやGmailなどへアクセスできます。
どの認証を使うべきか
FileMakerからGoogleのAPIを利用する場合においては、以下のように考えれば良いと思います。
| ケース | 種類 |
|---|---|
| Google Mapsなどの「APIキー」でAPIが実行できる場合 | API キー |
任意のアカウントのGmailやGoogle Drive、Google Calendarなどにアクセスしたい場合
|
OAuth 2.0 クライアント |
| 共有設定をされた特定のリソースにアクセスしたい場合 | サービス アカウント キー |
次回
今回は、FileMakerからGoogleの各種APIを利用する際の認証について、説明しました。
次は「OAuth 2.0 クライアント」や「サービスアカウントキー」を使い、実際にFileMakerからGoogleの各APIをcurlコマンド(URLから挿入ステップ)で利用する際の解説記事を公開予定です。
リクエストがありましたら、Twitterなどでお気軽にお声かけ頂ければと思います。
お知らせ
前回のブログ(『「納品」をなくせばうまくいく』を読んで、感じたこと、考えたこと)でも書きましたが「一括請負の受託開発」をやめて「定額制の受託開発」を始めることにしました。
すぐに受け付けることはできないのですが、ECサイトを運営されている会社様でしたら、定額制の受託開発を1か月無料でお試し頂けるように考えております。
「ECサイトを運営されている会社様の、どのような課題を解決できるか？」という点についても、追って記事を公開します。
もし、少しでもご興味があるようでしたら、お問合せ頂ければと思います。
