トークン

服屋のショッピングモールを作ったと考えてみてください。コンテンツスタジオに登録しておいた商品を、お客様が見るショッピングサイト側で読み込んで表示したいとします。ところが、そのサイトは人ではなくプログラムです。人のようにIDとパスワードでログインすることはできません。こうしたとき、人の代わりにサイトやプログラムがコンテンツへアクセスできるように発行する秘密の鍵がトークンです。

トークンは錠前を開ける一本の鍵だと考えてください。この鍵を持つ側は、ログインなしでも決められた範囲の中でコンテンツを扱えます。そのためトークンはパスワードとまったく同じように扱う必要があります。誰にでも見せてはならず、漏れてしまうと手にした人がその権限をそのまま使えてしまいます。

WEEGLOOには、用途の異なる三種類の鍵があります。アカウント全体の代わりを務める強力な鍵(Personal Access Token)、1つのSpaceの中でコンテンツを読み書きする鍵(Space Access Token)、公開サイトにコンテンツを読み出して届けるための読み取り専用の鍵(Delivery Access Token)です。このページでは、三つの鍵がそれぞれ何で、いつ使うのかを見たうえで、コンテンツスタジオで実際に発行してみます。

三つの鍵は用途が異なります

まず、三つの違いをひと目で整理すると次のとおりです。

要点はこうです。Personal Access Tokenはアカウントの一人をまるごと代わりに務める万能鍵に近く、Space Access Tokenは一つのSpaceの中だけでコンテンツを読み書きする鍵、Delivery Access Tokenは発行済みコンテンツを読み出すだけの読み取り専用の鍵です。やりたいことがアカウント全体にまたがるのか、一つのSpaceの中で書き込みまで行うのか、公開サイトで読み取るだけなのかに応じて、合う鍵を選べば大丈夫です。

アカウント全体の代わりを務める鍵: Personal Access Token

Personal Access Tokenは、発行したアカウント本人の権限をそのまま使う鍵です。この鍵を使うと、そのアカウントがコンテンツスタジオでできることを、ログインなしでそのまま行えます。商品を登録したり、修正したり、発行したりする管理作業まで可能です。

そのため、この鍵は強力です。人の代わりにコンテンツを自動でアップしたり直したりするプログラムに持たせると、そのプログラムはアカウントの持ち主のように働けます。複数のSpaceを行き来したり、Spaceの設定まで扱ったりする管理作業なら、この鍵が必要です。逆に、一つのSpaceの中でコンテンツを読み書きするだけで済む作業なら、アカウント全体の代わりを務めるこの鍵ではなく、後で説明するSpace Access Tokenで権限を狭めておくほうが安全です。

強力なぶん、扱いには注意が必要です。この鍵は、お客様に渡る公開クライアントに入れてはいけません。 公開された場所に入れると誰でも鍵を取り出して見られてしまい、その鍵を手に入れた人は発行したアカウントの権限をそのまま使えてしまうからです。公開サイトで商品を読み込んで表示するだけのときは、この強力な鍵ではなく、下記のDelivery Access Tokenを使います。

Personal Access Tokenは、発行するときに名前を決めるだけで済みます。権限の範囲は別途選びません。発行したアカウントが持つ権限をそのまま受け継ぐからです。

一つの Space の中で読み書きする鍵: Space Access Token

Space Access Tokenは、特定の一つのSpaceの中だけで使う鍵です。Delivery Access Tokenが読み取りだけなのとは違い、この鍵ではそのSpaceの中のコンテンツを読むのはもちろん、書き込むことまで行えます。商品を新しく登録したり直したりする作業を、人がログインしなくてもプログラムが代わりに行えます。

たとえば、お客様がログインしなくても服屋のサイトに問い合わせの投稿を残せるようにしたいと考えてみてください。お客様が使うクライアントがその投稿を服屋のSpaceに新しく書き込む必要がありますが、読み取り専用のDelivery Access Tokenでは書き込めません。かといって、アカウント全体の代わりを務めるPersonal Access Tokenをクライアントに置くと、その鍵が漏れたときに服屋だけでなくアカウントの届くすべての場所が危険になります。こうしたときに使うのが、一つのSpaceの中だけで書き込みまで行えるSpace Access Tokenです。お客様のクライアントからコンテンツを書き込ませるこうしたケースがこの鍵の代表的な使い方で、サーバーでコンテンツを自動で登録・修正するときにも使います。

Space Access Tokenは、一つのSpaceの中でだけ通用します。服屋のSpaceのコンテンツを読み書きできても、ほかのSpaceをのぞいたり、Spaceの設定を変えたり、組織やアカウントに手を出したりはできません。そのため、同じ書き込み作業でもPersonal Access Tokenより安全です。

この鍵をどこに置くかは、用途に応じて決めます。サーバーに置くこともできますし、お客様が使うクライアントに置くこともできます。安全は、鍵をどこかに隠すことではなく、結びつけるロールをその用途に合わせて狭めることで守ります。そこで次に、ロールをどう結びつけるかが大切になります。

ロールを結びつけて読み書きの範囲を定めてください

Space Access Tokenを発行するときも、この鍵がどこまでできるかをSpaceRole(ロール)で定めて一緒に結びつけます。Delivery Access Tokenのロールが「どこまで読めるか」を定めるのとは違い、Space Access Tokenのロールは「どこまで読み書きできるか」を定めます。

結びつけるロールは、その鍵がどこに置かれるかに合わせて狭めます。サーバーで商品を自動で登録・修正する鍵なら、商品(Content)に対して Read・Create・Edit だけを許可し、Delete・Publish は入れないロールを結びつけます。一方、お客様のクライアントに置いて問い合わせの投稿だけを受け取る鍵なら、「問い合わせの投稿」を新しく作ること(Create)だけを許可する、より狭いロールを結びつけます。そうすれば、この値が漏れたとしても、それぞれ許可したこと以外は何もできません。

すべてを扱えるAdministratorロールは結びつけないでください。 書き込みまで行える鍵ほど、とくにお客様が見られる場所に置く鍵ほど、漏れても許容できるくらい狭いロールを結びつけてこそ安全です。

書き込みを許可するロールを作る方法はロールと権限で扱います。そのページで作る「商品登録担当」ロールが、商品を登録・修正まで許可する書き込み用ロールの例です。

一つの Space の中で読み取りだけする鍵: Delivery Access Token

Delivery Access Tokenは、特定の一つのSpaceの中でだけ通用する読み取り専用の鍵です。この鍵では、そのSpaceの中でPublished(公開)状態のコンテンツを読み出すことだけができます。公開していないDraft状態のコンテンツはこの鍵では読み取れず、修正したり削除したりすることもできません。

お客様が見るショッピングサイトが商品を読み込んで表示するときに使う鍵が、まさにこれです。サイトは商品を表示するだけでよく、登録したり消したりする必要はないので、読み取りだけができる狭い鍵で十分です。この鍵が漏れたとしても、発行済みのコンテンツが読まれるだけで、コンテンツを壊すことはできません。

コンテンツを公開(Published)するとはどういうことか、そして公開して初めて外部に届けられる理由は状態と公開で扱います。

狭いロールを結びつけて読み取れる範囲を制限してください

Delivery Access Tokenを発行するときは、この鍵がどこまで読み取れるかをSpaceRole(ロール)で定めて一緒に結びつけます。ロールは「何を、どの操作までできるか」を定めておいた権限の束です。鍵にロールを結びつけると、その鍵は結びつけたロールが許す分だけ読み取れます。

ショッピングサイトなら「商品」だけ読めればよいので、商品(Content)に対して Read だけを許可する狭いロールを作って結びつけます。そうすれば、この鍵が漏れたとしても商品情報だけが読まれるだけで、ほかのコンテンツやメンバー情報まで漏れることはありません。

すべてを扱えるAdministratorロールは結びつけないでください。 AdministratorはそのSpaceの中のすべてを扱える最高権限のロールです。読み取りだけで済む公開サイト用の鍵にこれほど広い権限を結びつけると、鍵が漏れたときの危険が大きくなります。必要なものだけ読めるように狭めたロールを別に作って結びつけるのが安全です。

ロールを作って権限を狭める方法はロールと権限で扱います。公開サイト用の鍵に結びつける、商品の Read だけを許可するロールを、そのページを見てあらかじめ作っておいてください。

許可する Referrer で鍵を使えるサイトを定めてください

結びつけたロールがこの鍵で何を読み取れるかを定めるのに対して、許可する Referrerはこの鍵をどこから使えるかを定めます。発行画面の下のほうにあり、発行したあとでも変えられます。

最初の値は制限なしです。この状態では、どのサイトから読み込んでもコンテンツが届けられます。指定した referrer のみ許可を選ぶとアドレスを書く欄が現れ、そこからは、ここに書いておいたアドレスから来たリクエストだけが通過します。服屋のショッピングモールのアドレスがhttps://shop.example.comなら、そのアドレスを書いておきます。そうすれば、この鍵の値が他人の手に渡っても、服屋のサイトの外では通用しません。

アドレスは複数書けます。追加ボタンを押すと欄がもう一つ増え、欄の右側にある削除アイコンを押すとその行がなくなります。

shop.example.comの下に付くアドレスをまとめて許可したいときは、先頭に*.を付けてhttps://*.shop.example.comのように書きます。こう書くと、event.shop.example.comのように前に何かが付いたアドレスがすべて含まれます。ただし、このように書いても、https://shop.example.com 自身は含まれません。両方を許可したいなら、https://shop.example.comも別に一行入れてください。

このリストは、お客様がブラウザでサイトを開いてコンテンツを読み込む場合に合わせて動きます。サイトではなくサーバーで動くプログラムがこの鍵を使うなら、どのサイトから来たリクエストなのかがわからないので、そうした鍵には制限なしをそのままにしておいてください。

発行した秘密の値を扱う

三つの鍵はいずれも、発行を終えるとその鍵の詳細画面に移ります。基本情報のToken欄に秘密のトークン値が入っていて、欄の左にあるコピーボタンを押すと値の全体がコピーされます。欄より値が長いため、画面では後ろのほうが切れて見えますが、コピーされるのは値の全体です。この値こそが鍵そのもので、サーバーやサイトに入れるときにこの値を使います。発行した直後にコピーしておかなかったとしても、あとでこの詳細画面にもう一度入ってコピーできます。右側のパネルのToken項目にあるIDは、この鍵を指す識別子であり、秘密の値ではありません。

ただし、鍵ごとに置く場所が異なります。

• Personal Access Tokenはパスワードのように扱ってください。強力な鍵なのでサーバーの中だけに置き、お客様が見る公開クライアントや、他人が見られるコードには入れないでください。
• Space Access Tokenは、どこに置くかを、結びつけたロールで合わせます。サーバーに置く鍵には必要な分だけの書き込みロールを、お客様に渡るクライアントに置く鍵には、漏れても許容できるくらい狭いロール(例: 一種類の投稿だけを新しく作る)を結びつけてください。Administratorや広い書き込みロールは、公開された場所に置く鍵に結びつけないでください。
• Delivery Access Tokenは逆に、お客様が見る公開サイトに入れるのが本来の用途です。サイトを開く人は誰でもこの値を見られることになりますが、狭いロールを結びつけてあるので、誰がこの値を持っていっても、そのロールが許した読み取りの範囲の外では何もできません。だからサイトに入れておくこと自体は問題になりません。ここに許可する Referrerでショッピングサイトのアドレスまで書いておけば、値が他人の手に渡っても、そのサイトの外では使われません。ただし、使いたいサイトの外へむやみに広めないでください。

鍵をなくしたり、意図と違う使われ方をしているようであれば、その鍵を消して新しく発行し、差し替えればよいです。

Personal Access Token を発行する

毎晩、新商品を自動でアップしてくれるプログラムに渡すPersonal Access Tokenを発行してみます。

1. アカウント設定でPersonal Access Tokenの画面を開いてください。
2. 右上の作成ボタンを押してください。
3. 名前欄に夜間 新商品アップロードを入力してください。この名前は、後でどんな用途で作った鍵かを見分けるためのものです。
4. 保存ボタンを押して発行してください。

発行が終わると、その鍵の詳細画面に移ります。秘密のトークン値は発行した秘密の値を扱うで説明したとおりこの画面でコピーして、このプログラムが動くサーバーの安全な場所に保管してください。

Space Access Token を発行する

今度は、服屋のSpaceに商品を自動で登録してくれるサーバーが使うSpace Access Tokenを発行してみます。この鍵は服屋のSpaceで使われ、商品を登録・修正できるロールを一緒に結びつけます。

まず、この鍵に結びつけるロールがSpaceになければなりません。商品(Content)を Read・Create・Edit できるロールをロールと権限であらかじめ作っておいてください。以下では、そのロールを商品登録担当という名前で作っておいたものとします。

発行・管理の画面は、Delivery Access Tokenと同じSpaceの設定の中にあります。

1. 服屋のSpaceの設定でSpace Access Tokenの画面を開いてください。
2. 一覧の右上にある作成ボタンを押してください。Space Access Tokenの作成画面が開きます。
3. 名前欄に新商品 自動登録サーバーを入力してください。
4. SpaceRoleで商品登録担当を選んでください。Administratorは選ばないでください。
5. 許可する Referrerは制限なしをそのままにしておいてください。この鍵はサイトではなくサーバーで使うからです。
6. 画面右上の作成ボタンを押して発行してください。

発行が終わると、その鍵の詳細画面に移ります。秘密のトークン値は発行した秘密の値を扱うで説明したとおりこの画面でコピーして、安全な場所に保管してください。ここでは商品を登録・修正できるロールを結びつけたので、この鍵はそのロールが必要なサーバーで使います。お客様が使うクライアントに直接置く必要があるなら、漏れても許容できるくらい、より狭いロールを結びつけた鍵を別に発行して使ってください。そうしてお客様に渡る鍵には、許可する Referrerにそのサイトのアドレスまで書いておいてください。

Delivery Access Token を発行する

今度は、ショッピングサイトが商品を読み込んで表示するときに使うDelivery Access Tokenを発行してみます。この鍵は服屋のSpaceで使われ、商品を読めるように狭めたロールを一緒に結びつけます。

まず、この鍵に結びつけるロールがSpaceになければなりません。商品(Content)に対して Read だけを許可するロールをロールと権限であらかじめ作っておいてください。以下では、そのロールを商品 読み取り専用という名前で作っておいたものとします。

1. 服屋のSpaceの設定でDelivery Access Tokenの画面を開いてください。

2. 一覧の右上にある作成ボタンを押してください。Delivery Access Tokenの作成画面が開きます。

3. 名前欄にショッピングサイト 配信用を入力してください。

4. 説明欄には、この鍵をどこで使うのかを書いておけます。(任意です。)

5. SpaceRoleで商品 読み取り専用を選んでください。Administratorは選ばないでください。

   

6. 画面の下のほうにある許可する Referrerで指定した referrer のみ許可を選んでください。この鍵をショッピングサイトだけで使うように縛る設定です。

7. 現れた欄にhttps://shop.example.comを入力してください。

8. 追加ボタンを押してください。

9. 新しくできた欄にhttps://*.shop.example.comを入力してください。

   

10. 画面右上の作成ボタンを押して発行してください。

発行が終わると、その鍵の詳細画面に移ります。秘密のトークン値は発行した秘密の値を扱うで説明したとおりこの画面でコピーして、ショッピングサイトに入れて使ってください。

もう使わない鍵は消してください

使わなくなった鍵はそのままにせず、消すのが安全です。トークン一覧からもう使わない鍵を見つけて消してください。鍵を消すと、その鍵ではもうアクセスできなくなります。鍵が漏れたようなときも同じです。疑わしい鍵を消して新しく発行し、差し替えればよいです。

次にすること

• ロールと権限: Delivery Access Tokenに結びつける読み取り専用のロールと、Space Access Tokenに結びつける読み書きのロールを作ります。
• 状態と公開: Delivery Access Tokenで読まれるのはPublished状態のコンテンツだけです。公開とは何かを学びます。
• Space Access Token: プログラムからSpace Access Tokenを発行したり、この鍵でコンテンツを読み書きしたりするときに必要な、リクエスト形式のような技術仕様を扱います。
• Delivery Access Token: 許可する Referrer にアドレスを書くときの正確な表記ルールと、プログラムからこの鍵を扱うときに必要な、リクエスト形式のような技術仕様を扱います。
• API リファレンス: ほかのトークンを発行したり、コンテンツをプログラムから直接扱ったりするときに必要な、リクエスト形式のような技術仕様を扱います。