APIキーの権限: リンクツールでの最小権限

APIキーの権限によって、キーが漏れたときに何を壊せるかが決まります。リンクツールで安全なデフォルトにするなら、1つのワークスペースだけに紐づけ、用途を満たす最低限のロールに制限し、ペッパー付きハッシュとして保存し、キー単位でレート制限をかけ、有効期限を設定します。リンクを作成するだけのキーがwebhook、メンバー、請求情報に触れる理由はありませんし、adminエンドポイントを開くこともあってはなりません。これが最小権限であり、その大部分はキーを作成する30秒間の選択で決まります。

この1年、さまざまな自動化の構成を見てきましたが、同じパターンが繰り返されています。誰かが金曜の午後に、自分の全権限キーをn8nへ貼り付け、動くことを確認し、その人が退職するか、ワークフローのエクスポートが共有ドライブに置かれるまで、誰も気にしません。この投稿では、短縮リンク製品でAPIキーのスコープとロールがどう機能するか、それぞれのロールで実際に何ができるか、そしてワークスペースそのものを渡さずに自動化ツールへキーを引き渡す方法を説明します。

これは、プラットフォーム全体のスキャン、webhook署名、監査ログを扱う、より広範なURL短縮サービスのセキュリティチェックリストと並ぶ内容です。今回はキーそのものに焦点を当てます。

リンクツールにおけるAPIキーの権限とは

リンクツールのAPIが扱うのはリンクだけではありません。go.example.com/spring-saleを作成する同じトークンで、権限によってはクリック分析を読み取り、カスタムドメインを追加し、メンバーを招待し、すべてのイベントを外部サーバーへ送るwebhookを登録できます。最後のものは特に危険です。webhookは、作成者が好きなサーバーを送信先に指定できる継続的なデータフィードであり、チームの誰も何週間も気づかない可能性があります。

つまり、権限には3つの軸があります。キーはどこで機能するのか（どのアカウントまたはワークスペースか）、そこで何ができるのか（読み取り、書き込み、管理）、そしてどのくらいの期間、どの速さで使えるのか、です。NISTの最小権限の定義は、タスクに必要なアクセスだけを与えるという考え方に集約できます。この3つの軸すべてがその一部です。読み取り専用でも、有効期限がなくレート制限もないキーは、時間の面では過剰な権限を持っています。

ワークスペーススコープのAPIキー: 1つのキー、1つのワークスペース

Elidoでは、すべてのキーがワークスペース内で発行され、その中に留まります。別のワークスペースのエンドポイントを呼び出すと、存在しないワークスペースと同じ404が返るため、キーを使って他のワークスペースの存在を確認することさえできません。

これは思っている以上に重要です。代理店や大規模チームは、5〜10個のワークスペースに所属することがよくあります。個人キーが作成者のアクセス範囲をすべて継承していたら、1つのクライアントプロジェクトから漏れたトークンで、すべてのクライアントにアクセスできてしまいます。ワークスペーススコープのAPIキーなら、被害範囲を1つのワークスペースに縮小できます。

キーには作成時に選んだロールの上限もあり、作成者の現在のロールを超えることはありません。実効アクセス権は、2つのうち低い方です。キーを作成したadminをeditorに降格すると、キーもそれに合わせて下がります。そのメンバーに付いていたカスタム権限も、キーのロールの方が低い場合は削除されます。それらは人に対する権限であり、キーに対する権限ではないためです。

ロールベースのAPIキー: 各ロールでできること

Elidoのキーは、人と同じ4つのロール、viewer、editor、admin、ownerを使います。キーの作成時に1つ選びます。省略するとeditorがデフォルトになり、リンクの作成や分析の読み取りという通常の自動化には対応しつつ、管理者権限は持ちません。

一般的に連携で触れる対象について、実際には次のようになります。

クリック数をBIツールに取り込むレポートダッシュボードにはviewerが必要です。キャンペーンリンクを発行するGoogle Sheetsの処理にはeditorが必要です。日常の自動化でadminが必要になることはほぼなく、ownerキーは避けるべき兆候だと考えます。ownerはワークスペースを運営する人のためのロールで、それを必要とする自動化処理は思いつきません。

知っておくべき制限が2つあります。キーを作成、一覧表示、失効できるのはadminとownerだけなので、viewerやeditorのキーが自分より強い権限のキーを発行することはできません。また、どのロールのキーもプラットフォームのadmin APIには到達できません。このAPIはAPIキー認証を403と「admin access requires an interactive session」というメッセージで拒否します。キーで開けるのはワークスペース連携だけです。

webhook管理にadminキーが必要な理由

ここは意外に思われる点です。webhookエンドポイントの一覧を読むことは、viewerキーを含むすべてのメンバーに許可されています。しかし、エンドポイントの作成、送信先の変更、配信の再送信にはworkspace.edit権限が必要で、これを持つのはadminとownerだけです。

理由は先ほどの継続的なデータフィードの問題です。editorがリンクを1,000個作成すれば、すぐに気づきます。ところがeditorが自分のサーバーを送信先にした包括的なwebhookを追加できれば、それ以降のすべてのリンクイベントをひそかに受け取れてしまいます。そのため、webhookの変更はワークスペース設定を変更できる人と同じ範囲に置かれています。

実際には、ダッシュボードでadminとして手動で一度webhookを設定します。その後、webhookを消費する自動化には、API呼び出し用のeditorまたはviewerキーを渡します。リンクイベント用のwebhookをSlackやCRMに接続する場合、受信側にはElidoキーは必要ありません。ペイロードを検証する署名シークレットが必要です。

接続する前に確認したいですか？無料のワークスペースを作成し、viewerキーとeditorキーを発行して、それぞれで同じ書き込みリクエストを試してください。viewerキーで403になることは、どの表よりも多くを教えてくれます。

キーの保存方法: ペッパー、ハッシュ、プレフィックス

トークンはelido_に続くbase32の52文字で、32バイトの乱数から生成されます。作成呼び出しへのレスポンスで、全体を一度だけ確認できます。その後、Elido側からは完全に消えます。

保存するのはトークンのHMAC-SHA256で、アプリケーション設定にあるサーバー側のペッパーを鍵にします。ペッパーはデータベースには保存されません。各リクエストで、受信したBearerトークン（RFC 6750で定義されたスキーム）を同じ方法でハッシュ化し、ハッシュで検索します。盗まれたデータベースダンプは、ペッパーなしでは照合できないハッシュの一覧です。ペッパーが設定されていない場合、本番サービスは起動しません。

自分で記録できるよう、elido_の後の最初の8文字を表示用プレフィックスとして保存します。APIキーのページには、キーの名前、ロール、作成日、有効期限、最終使用時刻、最終使用IP、合計リクエスト数、失敗リクエスト数とともに、このプレフィックスが表示されます。どこかのログにキーが現れたとき、完全なシークレットを見なくても、プレフィックスからどのキーか分かります。

レート制限、有効期限、APIキーのローテーション

各キーには、ワークスペース単位の制限とは別に、専用のトークンバケットが割り当てられます。そのため、暴走したワークフローが他の処理の予算を使い切ることはありません。adminは、1秒あたり1から10,000リクエストまでキー単位のレートを上書きし、バーストを1から20,000まで設定できます。上書きを解除すればデフォルトに戻せます。制限を超えると、キーにはRetry-After: 1とX-RateLimit-Scope: api_keyを含む429が返るため、リトライ処理でキーの上限とワークスペースの上限を区別できます。レート制限と冪等性のガイドでは、適切なバックオフを説明しています。

有効期限は任意で、作成時にRFC 3339タイムスタンプとして設定します。期限を過ぎると、キーは単純に受け付けられなくなります。失効はDELETEを1回実行するだけです。これも冪等です。

「ローテーション」ボタンは1つにまとめられておらず、私はそれで困りません。ローテーションは3つの手順で行います。

1. 同じロールと新しい有効期限でキーを作成します。
2. ツールの認証情報ストアに差し替え、呼び出しが成功することを確認します。
3. 古いキーを失効させ、一覧で最終使用時刻が更新されなくなったことを確認します。

すべての手順がワークスペース監査ログに記録されます。api_key.createdには名前とロール、api_key.revoked、上書きにはapi_key.rate_limit_setが記録されます。バックグラウンドスキャンも5分ごとに実行され、1,000を超えるリクエストがあり、その30%超が失敗しているキーにフラグを付けます。フラグは監査ログとキーに記録されます。自動失効はありません。404が急増した場合、攻撃者ではなく壊れたワークフローであることも多いため、キーを停止するかは人が判断します。

n8n、Make、Zapierに最小権限のAPIキーを渡す

自動化プラットフォームでは、キーが忘れられたままになりがちです。認証情報ストアに置かれ、エクスポートしたワークフローJSONにコピーされ、設定した人が退職しても残ります。役立つ習慣は2つあります。

• ツールごと、ワークフロー群ごとに1つのキーを使い、名前を用途にします（「n8n: campaign sheets」）。失効させたときにちょうど1つの処理だけが壊れ、監査ログからどのツールが何をしたか分かります。
• リンクを作成する処理にはeditor、読み取るだけの処理にはviewerを使い、どちらにも有効期限を設定します。

一覧としてはこれで十分です。あとは判断の問題です。自動化キーが漏れる場所はログやエクスポートであることが多いため、トークンをそこから守る方法として、OWASPのSecrets Management Cheat Sheetが参考になります。

ツールごとの設定については、n8n URL短縮サービスガイドでキーをHeader Auth認証情報に設定する方法を説明しています。MakeとIFTTTとn8nとZapierの比較では、各プラットフォームでの保存場所を扱っています。Zapierは、Zapier自動化の手順にあるとおり、同じトークンで接続します。CIや、担当者の退職後も動かす必要があるものには、マシンユーザーの方が適しています。人のキーとは分離した、専用ロールのサービスアカウントです。

そして、キーがadminエンドポイントを決して開いてはならない理由は、この引き渡しにあります。トークンをサードパーティツールに置くと、そのツールのワークフローを編集できる人なら誰でも使えます。信頼する相手は自分の側だけでなく、相手側の全員です。

スコープ単位のトークンは計画中で、まだ提供されていません

ロールは意図的に大まかに設計されており、ときには大まかすぎます。リンクの作成だけに使うeditorキーでも、削除がeditorロールの一部であるため、リンクを削除できます。解決策は、links:writeやanalytics:readのようにキーへ直接付与するスコープ単位のトークンを、ロールの上に重ねることです。

これはロードマップにあり、まだリリースされていません。現在、キーの権限はワークスペースとロールで決まり、それ以上細かくはできません。今すぐ制御を厳しくしたい場合は、低いロールと短い有効期限を使い、処理ごとにキーを分けて各キーの被害範囲を小さくしてください。APIクイックスタートとAPIおよびSDKリファレンスでは、現在のキーのモデルを動作するコードで確認できます。ID単位の制御も必要なチームは、マーケティングツール向けSCIMとSSOも参照してください。

基幹記事として、URL短縮サービスのセキュリティチェックリストもお読みください。URLスキャンからIP許可リストまで、キーを取り巻く制御を扱っています。

ブログ内の関連記事

• URL短縮サービスAPI: 5言語で学ぶ30分クイックスタート
• n8n URL短縮サービス: HTTP RequestノードまたはElidoコミュニティノード
• 短縮リンクの自動化: MakeとIFTTTとn8nとZapierの比較
• リンクイベント用のwebhook
• GitHub ActionsのURL短縮サービス: CIから短縮リンクを作成