サイト追加に耐えるSSO設定管理

はじめに

サイト間シングルサインオン（SSO）を3サイトで動かし始めると、次に来る質問はだいたい決まっています。「4つ目のブランドを立ち上げるとき、どれくらい手間がかかりますか？」というものです。

ここで、SSOの処理の中にサイトのドメインや窓口URLが直接書き込まれていると、追加のたびに全サイトのコードを直すことになります。直せば当然テストもやり直し。数を増やすほど作業量が増える構造だと、拡張そのものが後回しになってしまいます。

この記事では、対象サイトの追加・削除を「設定を変えるだけ」で終わらせるために、何をコードから追い出し、どう管理したのかを説明します。SSOの仕組みそのものより、運用を続けるための整理の話が中心です。

設定として外に出したもの

SSOに必要な情報は3つだけ

SSOを成立させるために全サイトが共有・参照する情報は、突き詰めると3つでした。これらをコードではなく環境変数（サーバーごとに外から渡す設定値）として持たせます。

表が示しているのは、SSOの設定が「鍵が1つ」と「仲間の名簿が2種類」でできている、ということです。

鍵は全サイトで同じ値を共有します。残る2つは「誰が仲間で、どこへ送ればいいか」を示す名簿の役割。処理側はこの名簿を読むだけ、という形にするのが狙いでした。

コードに書かないと何が変わるのか

サイトのドメインや窓口URLをコードに直接書くと、サイトを1つ増やすだけでもコード変更になります。コード変更には確認とデプロイ（作ったものを公開環境へ反映する作業）が必要で、小さな追加でも工程が一式ついてきます。

設定として持たせておけば、名簿に1行足すだけ。処理には一切手を触れずに済みます。変わりやすいもの（サイトの顔ぶれ）と、変わりにくいもの（SSOの仕組み）を分けておく、という基本ですね。この線引きが、あとから効いてきます。

秘密の値と公開してよい値を分ける

3つの設定は性質が違うので、扱いも分けています。署名に使う鍵は絶対に外へ出せない値なので、コードにもリポジトリにも残さず、環境変数としてだけ渡します。

一方、許可サイトの一覧と窓口URLは、知られても直ちに問題になるものではありません。ただし書き換えられると困ります。許可していないサイトが一覧に紛れ込めば、そのサイトへログイン状態を渡してしまうからです。だから変更できる人を限る、という管理をしています。

「漏れると困るもの」と「書き換えられると困るもの」では、守り方が違う。この2種類を最初に分けておくと、どこまで慎重に扱うかで迷わなくなります。

サイト追加を設定だけで終わらせる

追加時にやること

図が示しているのは、コードを触るか、設定を書き足すだけで済むか、という違いです。

新しいブランドサイトをSSOの仲間に加えるとき、やることは3つだけになりました。許可サイトの一覧に追加し、窓口URLを登録し、共通の鍵を渡す。これだけで、その新サイトは送り出す側にも受け取る側にもなれます。

全サイトが同じ仕組みを持つ意味

図が示しているのは、新サイト側だけでなく既存サイト側の設定にも1行足す必要がある、ということです。

すべてのサイトが同じ仕組みを対称に備えているので、新サイトも設定を配れば仲間に入れます。特別扱いのサイトが存在しない、というこの均質さが拡張しやすさの理由です。逆に、1つだけ中心となるサイトを置く設計にしていたら、そのサイトが増えるたびに複雑になっていたはずです。

削除やメンテナンスも同じ手順で

追加だけでなく、外すときも同じです。ブランドを閉じる、あるいは一時的にSSOを止めたい場合は、許可サイトの一覧からその行を消せば、それ以降は引き継ぎが行われなくなります。

処理に手を入れないので、戻したくなったら書き足すだけで復帰できます。設定で入れたり外したりできる状態にしておくと、判断のやり直しが軽くなる。運用しながら決めていける余地を残しておくのは、けっこう大事なことなんですよね。

同じ考え方は、一時的な切り離しにも使えます。片方のサイトで不具合が出たとき、そのサイトだけを一覧から外せば、他のサイトのログイン体験には影響を出さずに調査できます。全体を止めずに一部だけ切り離せる、という選択肢が持てるのも、設定に寄せた効果の1つでした。

リンクの変換も同じ設定を見る

書く側が意識しなくていい仕組み

設定管理と並んで運用を支えているのが、サイト間リンクの自動変換です。普通のリンクを書くだけで、それが引き継ぎ付きのリンクに自動で切り替わる共通部品を用意しました。

これで、本来引き継ぐべきリンクなのに素のリンクのままだった、という適用漏れを防げます。人の注意力に頼らず、仕組みのほうで正しさを担保する。サイトが3つ、4つと増えるほど、この差は大きくなります。

名簿を1か所にまとめる

このリンク用の共通部品が参照するのも、先ほどの許可サイトの一覧です。つまり設定を1か所直せば、トークンの発行・検証だけでなく、リンクの変換挙動までまとめて追従します。

設定を唯一の参照元にしておくと、ある場所では新サイトが認識されているのに別の場所では未対応、といった食い違いが起きません。同じ名簿を全員が見ている、という状態を作れるかどうかが、サイト数が増えたときの安定性を決めます。

設定ミスに早く気づく工夫

設定に寄せるほど、設定の書き間違いが不具合の主な原因になります。そこで、起動時に設定が揃っているかを確認し、足りなければその場で分かるようにしました。

鍵が空のまま、窓口URLが未登録のまま動き始めると、ユーザーが実際にリンクを踏んだときに初めて失敗が分かります。それでは気づくのが遅い。早い段階で止めて知らせる、という作り方は、AIエージェントに構成をレビューしてもらう中で足りていないと指摘され、後から加えた部分です。

まとめ

サイト追加に耐えるSSOのカギは、変わりやすいものを設定へ追い出すことに尽きました。振り返ると次のとおりです。

1. 設定は3つ：署名に使う鍵・許可サイトの一覧・受け入れ窓口URLを外に出す
2. コードに書かない：サイトの顔ぶれとSSOの仕組みを分けて管理する
3. 全サイトが対称：特別扱いのサイトを作らず、設定を配れば仲間に入れる
4. リンクも同じ名簿を見る：共通部品が同じ設定を参照し、適用漏れを防ぐ
5. 設定ミスは早く知らせる：起動時に確認し、抜けがあればその場で分かるようにする

SSO全体の位置づけは「複数ECサイト間のシングルサインオン設計」に、トークンそのものの設計は「署名付きハンドオフトークンの仕組み」に、受け取った側の処理は「SSOコールバックとセッション確立のフロー」にまとめています。