シークレットタブは、API キーや署名シークレット、サードパーティのトークンなど、Node.js アプリが必要とする機密性の高い設定値を暗号化して保管する場所で、環境ごとに分かれているため、本番用の認証情報とプレビュー用の認証情報が混ざることはありません。
シークレットの保管場所
ウェブサイト を開き、サイトをクリックして、サイトの左メニューにある Environment グループを開き、シークレット を選択します。タブの名称は シークレット です。
このタブは Node.js サイトでのみ表示されます。WordPress、PHP、静的サイトでは表示されません。これらのサイトの設定は、ディスク上のファイルに保存されているためです。WordPress の場合は wp-config.php、プレーンな PHP アプリの場合はそのフレームワークが読み込むファイルです。
値はどのように保護されるか
すべての値はデータベースに保存される前に暗号化されます。読み取り可能なテキストとして保存されることはなく、一覧表示でも完全な値が表示されることはありません。末尾の4文字のみを含むマスク表示になっており、どちらの値も漏らすことなく似たキーを区別できます。
各行には、そのことを思い出させる Encrypted のピルが表示されています。値を読み取ることは、ページを開くだけで起きることではなく、個別の明示的な操作です。
シークレットの設定、表示、削除には、いずれも sites:write 権限が必要です。読み取り専用のチームメンバーは、どのキーが存在するかとそのマスク表示を見ることはできますが、値そのものは見られません。
2つの環境
ページ上部のセグメントコントロールで、production と preview を切り替えます。これらは完全に別々のキーの集合です。production で STRIPE_SECRET_KEY を設定しても preview には作成されず、preview から削除しても production には影響しません。
この分離こそがこの機能の目的です。プレビュービルドは、リポジトリへのアクセス権を持つ誰もがトリガーできる使い捨ての環境であるため、本番用の認証情報ではなくテスト用の認証情報を持たせるべきです。プレビュー環境がどのように作成されるかについては、プルリクエストのプレビューデプロイを参照してください。
シークレットの追加または更新
- セグメントコントロールで環境を選択します。
- KEY_NAME フィールドに名前を入力します。入力中に自動的に大文字に変換されます。
- 2番目のフィールドに値を入力します。入力中はマスク表示されます。
- Set をクリックします。
既存のキーを設定すると、上書きされます。編集専用の操作はなく、上書き時の確認ステップもないため、Set をクリックする前に環境タブを確認してください。
キー名のルール
キーは大文字で始まる必要があり、その後は大文字、数字、アンダースコアを含むことができ、最大128文字までです。DATABASE_URL、API_KEY_V2、SENTRY_DSN はすべて有効です。それ以外は、Key は UPPER_SNAKE_CASE で、文字/数字/アンダースコアである必要があります というメッセージとともに拒否されます。
他にも知っておくべき制限が2つあります。
- 値を空にすることはできません。空の値を送信すると 値が必要です が返されます。
- 値は16KBを超えることはできません。トークンには十分な大きさですが、証明書チェーン全体のようなものには足りません。そのようなものはシークレットではなくファイルに置くべきです。
値を読み取る
行の Copy をクリックします。KPanel はサーバー側で値を復号し、値をクリップボードにコピーしました という確認とともに、クリップボードに直接コピーします。値は画面に表示されないため、画面共有や肩越しの覗き見によって漏れることはありません。
表示操作はすべてサイトの監査証跡に記録され、誰がどのキーに対して行ったかとともに記録され、サイトアクティビティログに表示されます。
値が正しいかどうかを、値を露出させずに確認したい場合は、代わりにマスク表示を比較してください。末尾の4文字だけで、目的のトークンであることを確認するには十分で、しかもすでに画面に表示されています。
アプリでシークレットを使用する
値をコピーして、サーバー上でアプリケーションが設定を読み込む場所に貼り付けます。Node.js アプリの場合、通常はプロセスマネージャーが設定する環境変数か、アプリのルートにある .env ファイルで、コード側が起動時に読み込みます。
そのファイルをリポジトリにコミットしないでください。作成する前に .gitignore に .env を追加してください。git のリモートにプッシュされてしまったシークレットは、漏洩したものとして扱い、プロバイダー側でローテーションする必要があります。ファイルを削除した後も、履歴にはそのまま残り続けるためです。
シークレットタブは、パスワードマネージャーのメモやメッセージのやり取りではなく、暗号化され監査された、値の正式な記録です。これを信頼できる唯一の情報源として保ってください。プロバイダー側でキーをローテーションしたら、同時にここも更新し、次にデプロイする人が常に最新の値を使えるようにしてください。
シークレットの削除
行の Delete をクリックします。KPanel は Delete API_TOKEN? という確認を求め、次回の再起動時にアプリがこの値へのアクセスを失うことを警告します。元に戻す操作はなく、控えのコピーも保存されないため、後で値が必要になる可能性がある場合は、先にコピーしておいてください。
認証情報の基になるものがプロバイダー側で失効した場合や、それを使っていたコードが削除された場合には、シークレットを削除してください。古いキーを放置しておくと、後になってどれが本当に重要なのかを判断しにくくなります。
認証情報を安全にローテーションする
安全な順序は常に次の通りです。プロバイダー側で新しい認証情報を作成し、ここで更新し、デプロイし、アプリが動作することを確認してから、プロバイダー側で古い認証情報を失効させます。
これを逆の順序、つまり先に失効させてしまうと、稼働中のアプリが無効な認証情報を保持したままになり、それを必要とするすべてのリクエストが失敗する時間帯が生じます。変更にリスクがある場合は、まずバックアップを取得して、既知の良好な状態に戻せるようにしてください。バックアップの取得を参照してください。
トラブルシューティング
Secrets タブがメニューにありません。 そのサイトは Node.js サイトではありません。ページ上部のサイト名の横にあるスタックのピルを確認してください。
Set ボタンを押しても何も起こりません。 両方のフィールドが必須です。どちらかが空の場合、ボタンは キーと値が必須です と表示します。
キーが拒否されました。 小文字、ハイフン、ドット、スペースは使用できません。api-key と Api_Key はどちらも失敗し、API_KEY は通ります。
コピーしてもクリップボードに何も入りません。 一部のブラウザは、非アクティブなタブでのクリップボードへの書き込みをブロックします。まずページ上をクリックしてから、もう一度 Copy をクリックしてください。
次に読むべき記事
- プルリクエストのプレビューデプロイ:production と preview の分離のもう一方の側面です。
- サイトの Git デプロイ:これらの値を読み込むコードをプッシュする方法です。
- サイトアクティビティログ:誰がシークレットを設定、表示、削除したかを確認できます。