2. Authorization（オーソリゼーション） ～前半～

Authorization（オーソリゼーション） ～前半～

この記事は、Notion APIドキュメントを日本語訳し、筆者の言葉で非開発者でも理解できるよう編集したものです。

なお本記事は「Authorization」のページについての解説です。

また基本的な専門用語等の説明については、その言葉の定義や概念が複雑な場合、または文章の前後を理解するにあたって説明が必要であると判断した場合など、筆者の判断にて補足として記載することとしています。

なお、本気記事は パブリックインテグレーションの設定 に続く内容です。 Notion APIを初めて使用するのであれば、パブリックインテグレーションの設定も必ず理解しておきましょう。 またAuthorizationを理解することを優先とするため、Notion SDKなど一部情報を省略して簡素なHTMLにて解説します。

Authorization（オーソリゼーション）とは？

Authorization（以下、「オーソリゼーション」）は、Notion APIがユーザーのワークスペースや情報にアクセスするための認証機能になります。

ユーザーがAPIを介したアプリを利用するには、アプリによるユーザーのリソース（情報）へのアクセス許可を行う流れが一般的にです。Notion APIも同じように、ユーザーは自分のページにアプリがアクセスする認証操作をしなければいけません。

Notion APIによるオーソリゼーションの流れ

パブリックインテグレーションの設定を完了したあと、以下の手順を踏むことでオーソリゼーションが完了します。 オーソリゼーション全体の流れは少し複雑なため、前半と後半で分けて考えると良いでしょう。

※下図はOAuthの仕組みを解説するものではありません。あくまでNotion APIの実装にあたり、ブラウザの画面遷移をはじめとした各種プログラムによる視覚的に捉えられる動きをイメージしたものです。

【オーソリゼーションの流れ ～前半～】

オーソリゼーションの流れ ～前半～ の図

【オーソリゼーションの流れ ～後半～】

オーソリゼーションの流れ ～後半～ の図

事前の準備

前回の記事ではパブリック設定を理解することを優先したため、設定を任意とした箇所がいくつかあります。

本記事では実際にオーソリゼーションを構築するため、テンプレートページとリダイレクトURIを作成して使用します。

事前の準備１：ユーザーに渡すテンプレートページを用意する

本記事ではユーザーが使用するページとして、テンプレートページを提供します。
つまりオーソリゼーションの際にテンプレートページをユーザーに渡し、以降、Notion APIはユーザーに提供したテンプレートページにアクセスして読み書きできるようになるという流れです。

とはいえ、本記事はオーソリゼーションを構築するテストですので、適当なページを作成する程度で構いません。

筆者は以下のようなページを用意しました。

テンプレートページ

ダークモードを使用しているので、見づらかったらごめんなさい。
続いて、作成したテンプレートページをWEBで公開します。

テンプレートページをWEBで公開

Web公開用リンクが生成されますので、コピーしてください。

Web公開用リンクをコピー

最後にパブリックインテグレーションの設定ページにアクセスし、ディストリビューション内の「テンプレートのNotion URL」にコピーしたテンプレートページのURLをペーストして「変更を保存」をクリックします。

テンプレートページをインテグレーションに設定

画像にはリダイレクトURIが設定されていますが、この時点で設定されていなくても問題ありません。この後の「事前の準備2」で設定します。

事前の準備２：正式なリダイレクトURIを設定する

改めて「オーソリゼーションの流れ ～後半～」の画像を見てください。
「①リダイレクトURLに含まれたcodeを開発者（＝サーバーに置いたプログラム）が取得する」とあります。

オーソリゼーションの流れ ～後半～ の図

前回の記事では、インテグレーションで設定するリダイレクトURIを「とりあえず今は適当なURLでいいよ」と案内しましたが、本来は「Notionがレスポンスを返せるURI」でなければなりません。

なぜならユーザーがオーソリゼーションの操作を完了すると、NotionはリダイレクトURI（URL）にAPI利用に必要なパラメーターを返してくるからです。（※正確には、ユーザーのブラウザがリダイレクトURI（URL）に遷移する際、そのリダイレクトURI（URL）にパラメーターが追加された状態になります。）

↓ こんな感じになります

codeが追加されたリダイレクトURI

つまりリダイレクトURIは、パラメーターの受け取りやPOSTリクエストなどを行える、サーバーサイドのURLにする必要があります。（クライアントサイドのJavaScriptでもできるけど、セキュリティの点から絶対ダメ。全部丸見え。）

ではリダイレクトURIを何にするかですが、とりあえず自身のサーバーに「auth.php」というファイルを作成しましょう。
そしてリダイレクトURIには、いったんauth.phpのURLを設定してください。

実際のコードはAPI実行前に実装すればよいので、まずはリダイレクトURIを設定することを優先します。

※リダイレクトURIの詳細は本記事の最後にご紹介しますが、ここでは「パラメーターを受け取る必要があるから、適当なURIじゃだめなんだ」と認識しておけばよいでしょう。

Notion APIのオーソリゼーションフローを構築する

では実際にオーソリゼーションのフローを構築していきましょう。

STEP１：各種キーの取得とオーソリゼーションページの作成

最初にインテグレーションのシークレットページで、3つのキーを確認してメモ帳などにコピペします。
クラウドなどで保管するのはオススメしません。というか、やってはいけない。

インテグレーションのシークレットをコピーして控える

Notion APIに限らず、API関連のキーというのは銀行の暗証番号と同じくらい大事なものと認識しましょう。

バレちゃいけないキーが漏洩して悪用され、うん百万という被害を受けたという事例も存在します。
この記事でおこなう作業でそんな被害につながる可能性は極めて低いですが、今日この時点で「APIキーってそんなに大事なんだ」という認識を持った方が良いでしょう。

Notion API公式ドキュメントでは、上図3つのキーを.envという特別なファイルで保存すると説明されています。

OAUTH_CLIENT_ID=<your-client-id>
OAUTH_CLIENT_SECRET=<your-client-secret>
NOTION_AUTH_URL=<your-auth-url>

シークレット情報を控えたら、続いて外部ユーザーが認証を行うためのページなりクリックボタンなりを用意します。

この記事だけでページの作り方まで解説できませんので、以下に至極簡単なHTMLを用意しました。 メモ帳やVS Codeなどにコピペして、htmlファイルとしてデスクトップなどに保存してください。 （認証URLにはシークレット情報が含まれるため、クラウドに上げたり、サーバーに置いたりするのはやめましょう）

<!DOCTYPE HTML>
<html lang="ja">
<head>
    <meta charset="utf-8">
    <title>Notion認証</title>
    <meta name="description" content="">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
    <p>API認証</p>
    <a href="ここに認証URLを入力する">クリックして認証を行う</a>
</body>
</html>

上記コードの11行目だけを編集します。 インテグレーションのシークレットページに記載してある認証URLを入力しますが、以下のようになっているはずです。

リダイレクトURIは「%」や「数字」で暗号化されたような状態になっているかと思いますが、それはそのままで問題ありません。
※正確には暗号化ではなく、エンコードです。通常の文字列で生成されたURLだと文字化けなどによりエラーを起こす可能性があるため、プログラムが認識できる形式に変換しているというワケです。

保存したHTMLファイルをダブルクリックすると、以下のような画面が表示されるはずです。

HTMLの画面

クリックするとブラウザの画面が変わり、以下のようなプロンプトが表示されます。

プロンプト画面

  1. Notion APIがアクセスしようとしているアカウントが表示されています。
    クリックすればアカウントを切り替えられます。（筆者は動作テストのため「ユーザー1」という名前のアカウントを作成しました）
  2. パブリックインテグレーションの機能の項目で設定した、「アクセスする外部ユーザーの情報」がここに反映されています。
    筆者の場合、「コンテンツを読み取る」「コンテンツを更新」「コンテンツを挿入」「メールアドレスを含むユーザー情報を読み取る」の4つを選択したため、画像のような4項目が表示されています。
    つまりここで、外部ユーザーに対し「私の作ったアプリが、あなたのページにアクセスしてこんなことするけど良い？」と聞いているわけです。
  3. ここではAPIを信用できるものかどうかの判断のため、「NotionはAPIのチェックをしてないから、心配ならプライバシーポリシーや利用規約のページを見てね」という注意が書かれています。
    当然、プライバシーポリシーや利用規約のリンクの部分は、パブリックインテグレーションで設定したURLがリンクされています。

上記まで理解できましたら、「次へ」をクリックすると以下の画面に遷移します。

プロンプト画面

開発者（つまり、あなた）が作ったテンプレートを共有するかどうか、また外部ユーザーが「共有してもいいかな」と思うページを指定するかを選択するプロンプトです。

あなたが作成したテンプレートをユーザーに渡して作業する場合、「開発者が提供するテンプレートを使用する」を選んで、「アクセスを許可する」をクリックすれば、リダイレクトURIに遷移して完了です。

STEP2に続きますが、いよいよ情報量が多くなるためAuthorizationの構築 ～後半～ に続きます。お疲れさまでした。

リダイレクトURIの補足

以上でオーソリゼーションの前半が終了です
 リダイレクトURIの存在がイマイチ理解できないかもしれませんので、補足も踏まえて改めて説明します。

Notion APIの公式ドキュメントでは、以下のような案内があります。

Notion APIの公式ドキュメント

If the user follows the prompt to Allow access for the integration, then Notion generates a temporary code and sends a request to the redirect URI with the following information in the query string:

引用：Step 2: Notion redirects the user to the integration’s redirect URI and includes a code parameter

書かれている内容は上述した私の解説と同じです。

「ユーザーがインテグレーションのアクセスを許可すると、Notionは一時的なコードを生成してクエリ文字列に次の情報を含むリクエストをリダイレクトURI に送信します。」

クエリ文字列というのは、簡単に言えばURLの後ろに付く、『？』以降のゴチャゴチャした文字列です。（ここは深く考えると沼なので、そういうものという認識で十分です）

そしてNotionが返してくるクエリ文字列は、以下であると解説されています。

パラメータ 説明 必須
code 一時的な認証コード ✅
state ユーザーにアクセス許可を求める際にインテグレーションが提供した値 　

クエリ文字列は「パラメーター」と言って、この後のステップで必要になる大事な情報です。
つまりユーザーがオーソリゼーションを完了すると、インテグレーションのページに設定したリダイレクトURIにパラメーターが追加されたうえでユーザーのブラウザがリダイレクトされます。

↓ こんな感じ

パラメーター追加されたURI

「https://」と「?」の間にあるのが、筆者が設定したリダイレクトURIです。

ユーザーが認証操作を終えるとユーザーのブラウザはリダイレクトURIに遷移しますが、画像のとおりリダイレクトURIには「?」に続いてcodeやstateといったパラメーターが追加されます。

だからこそ、記事内で「リダイレクトURIは適当なURLじゃだめだよ」と解説したということですね。


Next Post Previous Post