こんにちは！今回は、BubbleでOAuth2.0をマスターするためにAPI Connector「OAuth2 User-Agent Flow」の設定方法を解説します。
これまでにもOAuth2.0ログインの実装方法をいくつかのサービスを例に紹介してきましたが、今回はOAuth2.0の仕組みや各サービスが公開しているAPIドキュメントの見方、「OAuth2 User-Agent FLow」の動きなど裏側を中心に解説しています。様々なサービスの「OAuth2 User-Agent Flow」の設定に応用できる内容になっているので、今後OAuth2.0を設定するシーンでガイドとして本記事を参考にして頂ければ幸いです。
後半ではSpotify APIを例にAPIドキュメントの見方や「OAuth2 User-Agent Flow」の設定方法を解説しています。
Bubbleの優秀さ・便利さを実感できる内容になっていますのでぜひ最後までご覧下さい！
※過去のOAuth2.0ログイン実装方法解説記事
- OAuth2.0とは？
- API Connector「OAuth2 User-Agent Flow」の設定項目
- APIドキュメントの基本的な構成
- SpotifyアカウントでOAuth2.0＆ユーザーデータ取得
- まとめ
OAuth2.0とは？
OAuth2.0とは、第三者アプリケーションのデータベースにある情報に、IDやパスワードなどのログイン情報なしでアクセスできるようにする仕組みです。Bubbleアプリでもこの仕組みを使って「Twitterアカウントでログイン／Twitterのユーザー名を表示する」などの機能を実装することができます。
OAuth2.0の仕組みを解説します。
「OAuth2.0でBubbleアプリからサービスAのユーザー情報にアクセスする」場合、まずBubbleアプリはサービスAのデータへのアクセスを許可するAccess tokenが必要になります。Access tokenは以下の流れでサービスAからBubbleアプリに付与されます。
(1) BubbleアプリがAccess tokenをサービスAに要求する
(2) サービスAが、Bubbleアプリにデータへのアクセスを許可していいかユーザーに確認する
(3) ユーザーが許可すれば、サービスAがBubbleアプリにAccess tokenを渡す
これで、BubbleアプリはAccess tokenを用いてサービスAが提供するユーザー情報を要求できるようになりました。
Access tokenを得たBubbleアプリはAPIでサービスAにデータを要求し受け取ります。ここでは欲しいデータを指定します。
(4) BubbleアプリはAccess tokenを提示してAPIでサービスAにユーザーのデータを要求する
(5) サービスAはAccess tokenを確認し、Bubbleアプリにユーザーのデータを渡す
このような流れでデータを取得する流れになりますが、上記の(1)Access tokenの要求と(2)Access tokenの付与を標準化したものがOAuth2.0です。
OAuth2.0のフローは4つのフローが定義されており、アプリケーションのタイプや要求するデータ・権限等によって適切なフローを使い分ける必要があります。
例えば「Authorization code flow」では、Access tokenの要求には認証するサービス（サービスA）から付与されるAuthorization codeを提示する必要があります（(1)の前に「Authorization codeを取得する」というステップが追加されます）。
API Connector「OAuth2 User-Agent Flow」の設定項目
通常、OAuth2.0とユーザーデータのやり取りにはWebアプリの構築同様コードが必要ですが、BubbleならAPIConnectorの「OAuth2 User-Agent Flow」を用いてノーコードで簡単に実現できます。
OAuth2 User-Agent Flowは、赤い部分でOAuth2.0に必要な情報を、青い部分（Callの設定部分）でデータへのアクセスに必要な情報を設定して使います。
まずは各項目で設定する内容を整理します。
| 項目名 | 内容 |
|---|---|
| Authentication | 認証方法を選択します。今回解説する「OAuth2 User-Agent Flow」は、 ユーザーエージェント（通常はWebブラウザ）上でのやり取りを経て認証を得る方法です。上記で紹介した「Authorization code flow」も含みます。認証したユーザーに代わってAPIを使う場合ほとんどのサービスと接続できる認証方法です。 |
| App ID | 認証するサービスの開発者向けプラットフォーム等でBubbleアプリを登録した時に発行されるアプリケーション識別ID。Client IDであることが多いです。Dev. App IDは開発環境と本番環境で使用するIDを分けたい場合に設定します（オプション）。 |
| App Secret | 認証するサービスの開発者向けプラットフォーム等でBubbleアプリを登録した時に発行されるシークレットキー。Client Secretであることが多いです。Dev. App Secretは開発環境と本番環境で使用するキーを分けたい場合に設定します（オプション）。 |
| Scope | Access Tokenを要求するとき、ユーザーに要求するアクセス許可の範囲。send_email（メール送信）、 user-read-email（ユーザーのメールアドレス読み取り）など、スコープの名称や範囲は認証するサービスによって異なります。使用するAPIによって必要なスコープは異なり、各APIでアクセス許可が必要なスコープは認証サービスが公開しているAPIドキュメントに記載されています。 |
| Authentication goes in the header | 取得したAccess tokenをヘッダーに含めてデータへのアクセスを要求する場合、チェックをオンにします。ほとんどの場合でこのチェックボックスはオンになります。 |
| Token Name/Header key | デフォルト値はaccess_tokenになっていますが、「Authentication goes in the header」をオンにした場合Authorization: Bearerになります。Access tokenの取得後、APIの要求ヘッダーに「Authorization: Bearer ********(Access token)」とAccess tokenを含めてデータへのアクセスを要求します。ヘッダーに取得したAccess tokenを含める処理はBubbleがバックグラウンドで実行してくれます。 |
| Token is returned as querystring | トークンをURLの末尾に付ける形式で返す場合チェックします。ほとんどの場合でチェックは不要です。 |
| Requesting an access token uses Basic Auth | 基本認証で使用するAccess tokenを要求する場合にチェックします。ほとんどの場合でチェックは不要です。 |
| Add access_type=offline (Google APIs) | Google API使用時で、ユーザーがBubbleアプリにログインしていないときでもAPIへのアクセスが必要な場合にチェックをオンにします。 |
| Use a generic redirect URL | Access token付与後に認証するサービスがユーザーをリダイレクトするリダイレクトURIをカッコ内のURLにする場合にチェックをオンにします。ほとんどの場合で、オンにする方が問題なく処理を実行できます。 |
| Login dialog redirect | ユーザーにアプリのアクセス許可を求めるとき誘導するURL。ユーザーはここでアプリが求めるアクセス許可のスコープを確認しアクセスを許可します。認証サービスのアカウントへのログインも同時に求められます。たいていhttps://SERVICEDOMAIN/......./authorizeのような形式になります。 |
| Access token endpoint | Access tokenを発行するエンドポイント。たいていhttps://SERVICEDOMAIN/......./tokenのような形式のURLが入ります。エンドポイントは各認証サービスのAPIドキュメントで確認できます。 |
| User profile endpoint | ユーザーのプロフィール情報を返すエンドポイント。たいていhttps://SERVICEDOMAIN/......./meのような形式のURLが入ります。エンドポイントは各認証サービスのAPIドキュメントで確認できます。 |
| User ID key path | ユーザーIDのパス。ほとんどの場合でidですが認証するサービスによって異なります。 |
| User email key path | ユーザーのメールアドレスのパス。emailやmailが多いですが認証するサービスによって異なります。 |
APIドキュメントの基本的な構成
Oauth2.0をはじめ、APIで外部サービスと連携する場合は認証するサービスの開発者向けプラットフォームやAPIドキュメントを参考にAPIConnectorを設定することになります。
開発者向けプラットフォームは、Google APIならGoogle Cloud Platform、TwitterならTwitter Developer Platform、MicrosoftならMicrosoft Azure Active Directoryが該当します。APIドキュメントはプラットフォーム内で公開されています。
APIドキュメントは、ほとんどのサービスでクイックスタート、ガイド、ライブラリ、リファレンスで構成されています。それぞれ以下のような内容になっています。APIについて知りたいことがあるけど迷子になってしまった場合は以下を参考にしてみてください。
| 分類 | 内容 |
|---|---|
| クイックスタート | 開発環境の準備、APIを利用するときに最初にやっておきたいことやチュートリアル |
| ガイド | プラットフォームでのアプリの登録方法、APIの概要や認証フローの説明 |
| ライブラリ | デモアプリやプログラミング言語ごとの導入事例などの紹介 |
| リファレンス | APIエンドポイントごとのスコープや要求・応答サンプル |
クイックスタートを参考に事前準備を確認したら、開発者向けプラットフォームでのアプリの登録やOAuth2.0の流れをガイドで、使用するAPIのスコープやエンドポイントをリファレンスで確認しながらOAuth2 User-Agent Flowの値を設定していくことになります。
SpotifyアカウントでOAuth2.0＆ユーザーデータ取得
実際にAPIドキュメントを見ながらSpotifyでOAuth2.0とユーザーデータ取得の設定をしてみましょう！今回は、OAuth2.0で認証したユーザーのSpotify IDをログイン後のページで表示させるようにします。
アプリを登録する
アプリの登録については、ガイドのApp Settingsのページを参考にします。
まずはSpotify for Developersの開発者向けダッシュボードにログインし、OAuth2.0で認証したいBubbleアプリを登録します。
アプリごとのダッシュボードでClient IDとClient Secretが確認できます。
次に、右上の「EDIT SETTINGS」からBubbleアプリのURLとリダイレクトURIを登録します。リダイレクトURIは、API Connectorの認証方法を「OAuth2 User-Agent Flow」に設定したところで確認した「Generic Redirect URL」です。
OAuth2.0フローの選択
次に、4つあるOAuth2.0フローから今回のケースに適切なフローを選びます。それぞれのフローは各社のAPIドキュメントで使用できるケースと一緒に説明されているのでそちらを参考に選んでください。
Spotifyの場合はAuthorizationのページで説明されています。こちらを参照すると、今回のケースでは「Authorziation code flow」が最適だと分かります。
Authorization code flowはユーザーエージェントを介するフローなので、今回API Connectorでは「OAuth2 User-Agent Flow」を使用します。Spotify以外のサービスでも、Authoriation code flowを採用する場合「OAuth2 User-Agent Flow」が使用できます。
OAuth2 User-Agent Flowの設定をする
ドキュメントから必要な情報を探しながら実際にAPI ConnectorでOAuth2 User-Agent Flowの設定をしてみましょう。
適当なAPI Nameを設定したら、App IDに先程開発者向けプラットフォームで取得したClient IDを、App SecretにClient Secretの値を入力します。
Scopeは、使用するAPIに必要なアクセス許可を設定します。ユーザーのSpotify IDを表示するために使うAPIは「Get Current User's Profile」です。このAPIのドキュメントを見ると、要求の説明のなかで「user-read-private」と「user-read-email」スコープが必要だとされているので、この2つをScopeに入力します。
Spotify APIではスコープ一覧「Authorization Scopes」 から必要なスコープを拾うこともできます。
※SpotifyのAPIドキュメントではスコープが少し分かりにくいですが、他サービスのドキュメントでは各APIのページで必要なスコープがまとめて記載されている場合が多いので安心してください。
Authorization Code Flowのドキュメントから、「Login dialog redirect」はhttps://accounts.spotify.com/authorize、「Access token endpoint」はhttps://accounts.spotify.com/api/tokenと分かります。
User profile endpointはユーザープロフィールを取得するエンドポイントですが、今回使用する「Get Current User's Profile」APIのエンドポイントと同じです。「Get Current User's Profile」のページを見ると、要求のサンプルとして以下のように記載されています。Hostの末尾に/v1/meをつけたhttps://api.spotify.com/v1/meがエンドポイントになります。
User ID key pathとUser email key pathは、SpotifyのOAuth2.0ではデフォルトのidとemailのままでOKです。
最後にAuthentication goes in the headerとUse a generic redirect URLのチェックを忘れずに！これでOAuth2.0の設定は完了です。
OAuth認証テストをする
API Connectorでの設定が完了したら、OAuth2.0ログインのWorkflowを作成してテストします。
ログインページを用意し、ボタンを配置します。ボタンのWorkflowには「Account」→「Signup/login with a social network」を設定し、OAuth providerは作成したOAuth2.0認証APIを選択します。Step2にページ遷移を設定するとOAuth認証の結果が分かりやすくなります。
Previewでログインボタンをクリックすると、あなたのSpotifyアカウントに対してアクセス許可を求めるダイアログが表示されます。今回設定したスコープから、ダイアログの表示は以下のようになるはずです。
※このダイアログのページが、ユーザーにアクセス許可を要求するLogin dialog redirectページに当たります。
「同意する」をクリックしてBubbleアプリに戻り、Initialize完了のポップアップが表示されたらOAuth2.0認証の設定は完了です。
補足：Authorization codeとAccess tokenはどこへ？！
冒頭で、サービスAにデータを要求するにはAccess tokenが必要で、そのフローの一部をOAuth認証が担っているという説明をしました。さらに、今回採用したAuthorization code flowではAccess tokenの要求の前にAuthorization codeの取得が必要になります。
では、前段落で無事イニシャライズが完了した「Oauth2 User-Agent Flow」の実行で、Authorization code flowのどこまでが完了しているのでしょうか。
実は、Authorization codeの取得からそれを提示したAccess Tokenの取得まで完了しています。Bubbleが「OAuth2 User-Agent Flow」を実行している裏側で「Authorization codeを取得し、取得したAuthorization codeを含めてAccess tokenを要求する」処理を行ってくれているのですね。
なお、API Connectorで「OAuth2 User-Agent Flow」を使わず手動（「None or self-handled」）でOAuth2.0認証フローを設定するのは、難しいですが不可能ではありません。Access tokenと同時に付与されるRefresh tokenの有効期限を変更できるといったメリットもあります。
OAuth2.0認証のNone or self-handledでの設定方法・実行の流れが気になる方は以下のForumの投稿をご覧下さい。
https://forum.bubble.io/t/showcase-manual-oauth2-token-integration/79988forum.bubble.io
これ以降の処理は、Spotifyに登録されているユーザーデータを取得する処理になります。
Callを設定してユーザーデータを取得する
ユーザーがOAuth2.0認証した後はBubbleがユーザーに分からない形でWebサーバーでAccess tokenを保持し、API要求時にそのAccess tokenを提示することで認証したサービスのデータにアクセスしています。保持しているAccess tokenを提示してAPIを使用するには、「OAuth2 User-Agent Flow」にCallを追加して設定をします。
今回の例では、「SPOTIFY - OAuth」に「Add another call」でユーザーデータを要求・取得するCallを設定していきます。
まずはCallの設定項目を整理します。
| 項目 | 内容 |
|---|---|
| Use as | Callの使用方法。ActionではWorkflowでActionとして使用できるようになります。Dataではページ上の表示に変数として使用するなどデータとして使用できるようになります。 |
| Data type | 要求に対してサーバから返されるデータのタイプ。JSONであることが多いですが、APIドキュメントで確認します。 |
| 要求タイプ | GET、POSTなど。APIドキュメントで確認します。 |
| エンドポイント | APIエンドポイント。APIドキュメントで確認します。 |
| Headers | 要求のヘッダーに含める内容。APIドキュメントで確認します。 |
| Parameters | 要求本文（Request Body）に含める変数。APIドキュメントで確認します。 |
設定に必要な値を「Get Current User's Profile」のドキュメントから拾ってきましょう。
まずはCallに名前をつけます。今回は「Get me」としました。
このCallで取得するユーザーデータは、「ログイン後のページでSpotifyアカウントのIDを表示する」かたちで使用したいので、Use asは「Data」を選択します。
Data typeは、ドキュメントのResponse SampleからJSONであることが分かるのでJSONを選択します。
※Data typeはドキュメント「Authorization Code Flow」からも読み取れます。
要求タイプとエンドポイント、HeadersはRequest Sampleを参照します。
Requestの概要説明にも記載されていますが、要求タイプはGET、エンドポイントはHostapi.spotify.comに/v1/meを付けたhttps://api.spotify.com/v1/meを設定します。
次にHeadersは以下を設定します。
| Key | Value |
|---|---|
| Content-Type | application/json |
※Content-Typeは要求時にサーバーに送信するデータのタイプです。
なお、Request SampleでContent-typeの下にAuthorizationがあるので、要求時にAccess tokenを提示する必要があることが分かります。本来はAccess tokenもヘッダーに含めなければなりませんが、API Connector「OAuth2 User-Agent Flow」では、OAuth2.0の設定をしたときにAuthentication goes in the headerをチェックしたことでHeader keyにAuthorization: Bearerが設定されています。この設定のおかげで、各Callの処理時にAuthorization: Bearer *******(Access token)とAccess tokenがきちんとヘッダーにて提示される仕組みになっています。
今回のAPIではParametersはありません。Parametersがある場合、Request Sampleは以下のようになっています。
これでCallの設定も完了しました。
Call枠内下部の「Initialize call」をクリックして、データが取得できるか確認します。以下のように応答があれば成功です。
※Initialize時、401エラーが出たらAccess tokenの有効期限が切れています。もう一度PreviewでOAuth2.0認証をやり直してからCallのInitializeを行ってください。
OAuth2.0認証からCallまでのテスト
OAuth2.0認証をして、ユーザーのプロフィールデータの取得までできるかPreviewで確認します。
先程OAuth2.0認証のテストで作成した認証後の遷移ページに、ユーザーIDを表示する設定をします。CallのInitializeで確認したidをDynamic Dataとして使用しましょう。
Textエレメントを適当な位置に配置し、「Insert Dynamic Data」をクリック、「Get data from an external API」を選択し、「API provider」は作成したCall「Spotify - OAuth - Get me」を選択し、最後に「id」を設定します。
設定が完了したので、Previewで確認してみます。OAuth認証のページでログインをクリックし認証が完了すると、遷移後のページでSpotifyのユーザーIDが表示されました！
まとめ
今回の記事では、API Connector「OAuth2 User-Agent Flow」を使ったOAuth2.0認証とユーザーデータの取得方法を、解説しました。
ポイントはこちら。
Authorization codeの取得が必要になるAuthorization code flowでのOAuth2.0認証も、Oauth2 User-Agent FlowならAccess tokenの取得までワンストップでできる。
Oauth2 User-Agent FlowにCallを追加することで、取得したAccess tokenを自動的に各Callのヘッダーに含めてAPI要求を実行してくれる。
「OAuth2 User-Agent Flow」は、ノーコードツールとしてのBubbleの優秀さを思い出させてくれるトピックでしたね。
なお、OAuth2.0認証の設定で困ったときは、Forumの過去の質問が役立つことが多いので、遡ってみると良いかもしれません。
また、Spotify for Developersでは、ユーザーがよく再生しているアイテムや注目のプレイリストの取得など面白いAPIがたくさん公開されています。ぜひ皆さんの開発中のサービスにも取り入れてみてくださいね！
