10-3 用途を絞った合鍵（API token）

この節を一言で

道具や外注先に渡すのは、全部開くマスターキーではなく、用途を絞った合鍵にします。

用途を絞った合鍵を配れば、渡す権限を小さくできます。

店の仕事を道具や人に任せるとき、毎回マスターキーを渡していては危険です。掃除を頼むだけの相手が、金庫も帳簿も開けられてしまいます。

必要なのは「この扉だけ・この操作だけ」と決めた合鍵です。落としても被害はその範囲で止まります。

いま読んでいるこのサイト（Cloudflare Lab）も、公開の作業を道具に任せています。ここでは、マスターキーと合鍵の違い、合鍵の切り方、名義の違い、許す範囲の決め方を見ます。

Learning goals

この節でできるようになること

• マスターキーにあたる仕組みの問題点を三つ挙げられる
• 合鍵を切るときに選ぶ二つのもの（許す操作・開ける場所）を言える
• 人の名義と店の名義の合鍵の違いを説明できる
• Edit と Read の違いを説明できる

1. マスターキーと合鍵

古い店では、鍵は一本しかなく、それで全部の扉が開きました。分かりやすい代わりに、渡した相手には何もかも任せることになります。

Cloudflare でこれにあたるのが Global API key です。公式はこれを以前の方式と位置づけ、可能なときは API token を使うよう勧めています。挙げられている問題点は、利用者のすべての資源にアクセスできること、権限が利用者本人とまったく同じであること、一人につき一本しか持てないこと、そして時間や接続元で使い方を絞れないことです。

API token は逆に、許す操作と開ける場所を選んでから発行します。公式によると、時間の窓を決めて期限切れにしたり、決まった接続元からだけ使えるようにしたりできます。

Global API key（マスターキー）

本人と同じ権限で、店じゅうのすべての扉が対象です。一人一本で、使い方の制限も付けられません。

API token（合鍵）

許した操作と開ける場所だけが対象です。期限や接続元の制限を付けられ、何本でも作れます。

マスターキーは全部を開け、合鍵は決めた場所だけを開けます。

全部を開けるマスターキーと、決めた扉だけを開ける合鍵が並んでいます。渡すのは右側です。

つまり、新しく作るものは API token で、Global API key は使わない方針にします。

2. 合鍵を切る

合鍵を作るときは、まず何のための鍵かを決め、次に許す操作、最後に開ける扉を選びます。この順で選ぶと、余計な権限が付きません。

公式の手順では、利用者名義の鍵は My Profile の API Tokens から Create Token を選びます。Edit zone DNS のようなテンプレートを選ぶか、自分で組み立てます。テンプレートには名前と権限があらかじめ入っています。

続いて権限を選びます。権限のまとまりは Account・User・Zone の三つです。そのうえで、その鍵が開けてよい場所（資源）を選びます。公式の例では、Zone DNS Read を一つの zone にだけ許すと、その zone の DNS レコードしか読めず、ほかの zone は失敗を返します。

My Profile›API Tokens›Create Token›Continue to summary

合鍵は、許す操作と開ける場所を選んでから切ります。

合鍵を切る台で、許す操作と開ける扉を選んでいます。選ばなかったものは開きません。

つまり、合鍵は「操作」と「場所」の二つを選んで初めて形になります。

3. 誰の名義の合鍵か

合鍵には、店主個人の名義で作るものと、店そのものの名義で作るものがあります。

公式によると、user token は特定の利用者の代わりに動き、その人の権限の一部を引き継ぎます。account API token は利用者に紐づかず、自分専用の権限を持つ service principals として動きます。

使い分けも書かれています。account API token は、設定した人が組織を離れた後も動き続ける必要がある自動化や外部連携に向き、user token はその場限りの作業に向きます。作成には Super Administrator の権限が要り、経路は Manage Account の Account API Tokens です。

店主名義の合鍵は人に紐づき、店名義の合鍵は店に残ります。

店主名義の合鍵と、店名義の合鍵が並んでいます。人が変わっても残るのは右側です。

つまり、長く動かす仕組みには店の名義、その場の作業には人の名義を使います。

4. 許す範囲の決め方

合鍵に「開ける」を許すか「見るだけ」を許すかで、事故のときの被害が変わります。ここは面倒でも一段細かく選びます。

公式は、多くの権限のまとまりに Edit と Read の二つがあると説明しています。Edit は CRUDL（作る・読む・更新する・消す・一覧する）の全部で、Read は読むことと、必要な場面での一覧だけです。

さらに Client IP Address Filtering で接続元を絞り、有効期間も決められます。切った合鍵がまだ使えるかは、次の命令で確かめられます。読めなくても大丈夫です。「この合鍵はまだ有効か」を尋ねる命令で、有効なら active が返ります。

curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \
--header "Authorization: Bearer <API_TOKEN>"

Cloudflare Lab での使われ方

ここで紹介した合鍵が、いま読んでいる Cloudflare Lab でどう使われるかを見ます。

Cloudflare Lab の公開作業は道具（Wrangler）が行うので、その道具に渡す合鍵を用意する予定です。渡す権限は、サイトを差し替えるのに要るもの（Workers Scripts Edit のような、公式の一覧にある権限）だけに絞ります。合鍵そのものは公開せず、.dev.vars と wrangler secret で扱います。実測は、この章の作業を終えたあとに追記します。

つまずきやすいところ

つまずきポイント

合鍵の中身は作成時に一度しか表示されません

公式は、この値は一度だけ表示されると警告しています。控えを取り損ねたら作り直します。

つまずきポイント

テンプレートをそのまま使うと、要らない権限まで付きます

テンプレートは出発点です。許す操作と開ける場所は、使う場面に合わせて削ります。

この節のまとめ

• 新しく作るのは API token で、Global API key は使いません。
• 合鍵は「許す操作」と「開ける場所」を選んで作ります。
• 長く動かす仕組みには account API token、その場の作業には user token を使います。

この節で出てきた言葉を、つながりの順に並べると次のようになります。

flowchart TD
  A["全部開く鍵<br/>Global API key"] --> B["用途を絞る<br/>API token"]
  B --> C["許す操作<br/>Edit / Read"]
  C --> D["開ける場所<br/>Zone / Account"]
  D --> E["名義を選ぶ<br/>user / account"]
  E --> F["接続元と期限<br/>Client IP / TTL"]

図のラベル: 全部開く鍵 Global API key / 用途を絞る API token / 許す操作 Edit / Read / 開ける場所 Zone / Account / 名義を選ぶ user / account / 接続元と期限 Client IP / TTL

次の節では、誰が何を変えたかを残す日誌を見ます。

この節のチェック

問 1Global API key について公式が挙げている制限はどれですか？

ひと月に決まった回数しか使えない有料のプランでしか作れない利用者本人とまったく同じ権限を持ち、すべての資源が対象になる読み取りの操作しかできない

問 2API token を作るときに選ぶものの組み合わせとして正しいものはどれですか？

許す操作（権限）と、開ける場所（資源）表示する色と、鍵の名前契約のプランと、支払いの通貨保存する期間と、保存する地域

問 3権限の Edit と Read の違いとして、公式の説明に沿うものはどれですか？

Edit は読むだけで、Read は書き換えもできるEdit は full CRUDL のアクセスで、Read は読み取りと必要な場面での一覧どちらもまったく同じ範囲Edit は無料で、Read は有料

問 4設定した人が組織を離れた後も動き続ける必要がある自動化に向くのはどれですか？

Global API keyuser tokenbackup codesaccount API token

問 5作成した API token の値について、公式が警告していることはどれですか？

毎月自動で書き換わる誰でも見られる場所に置いてよい作成のときに一度しか表示されない忘れてもメールで再送される

採点する