SSO Configuration That Scales with New Sites

Introduction

Once cross-site single sign-on (SSO) is running across three sites, the next question is fairly predictable: "How much work is it to launch a fourth brand?"

If site domains and entry-point URLs are written directly into the SSO logic, every addition means editing code on every site — and every edit means testing it all again. When the workload grows with each new site, expansion quietly gets postponed.

This article covers what we pushed out of the code, and how we managed it, so that adding or removing a participating site is only a configuration change. It's less about the SSO mechanism itself and more about keeping it maintainable.

What We Moved Into Configuration

SSO Only Needs Three Things

Boiled down, the information every site shares or reads to make SSO work comes to three items. All three live outside the code, as environment variables (settings passed in from outside on each server).

What the table shows is that SSO configuration comes down to one key plus two kinds of roster.

The key is the same value on every site. The other two record who counts as a participant and where to send things. The aim was a shape where the logic does nothing but read that roster.

What Changes When It Isn't in the Code

Write site domains and entry-point URLs directly into the code and adding a single site becomes a code change. Code changes bring review and deployment (publishing the built result to the live environment) with them, so even a small addition drags a full process along.

Held as configuration, it's one more line on the roster, with the logic untouched. It's the basic separation of things that change often — the lineup of sites — from things that rarely change, which is the SSO mechanism itself. That boundary is what pays off later.

Separating Secret Values from Public Ones

The three settings differ in nature, so they're handled differently. The signing key must never leave the system, so it isn't in the code or the repository — only in environment variables.

The permitted-site list and the entry-point URLs, by contrast, cause no immediate problem if someone reads them. Being rewritten is the real risk: slip an unapproved site onto the list and login state gets handed straight to it. So we limit who can change them.

Things that are dangerous to leak and things that are dangerous to alter need different kinds of protection. Separating the two up front means never having to guess how carefully a given setting should be treated.

Making Site Addition Configuration-Only

What Adding a Site Involves

What the comparison shows is a single difference: whether you touch code, or just append to a configuration file.

Bringing a new brand site into the SSO comes down to three steps. Add it to the permitted-site list, register its entry-point URL, and give it the shared key. That's all it takes for the new site to act as both sender and receiver.

Why Every Site Carries the Same Mechanism

What the diagram shows is that the existing sites need a line added too, not just the new one.

Because every site carries the same mechanism symmetrically, a new site joins simply by receiving the configuration. That uniformity — no site getting special treatment — is where the extensibility comes from. Had we designed one site as the hub, it would have grown more complicated with every addition.

Removal and Maintenance Work the Same Way

Removal follows the same path. If a brand closes, or SSO needs pausing for a while, deleting that line from the permitted-site list stops the handovers from then on.

Since the logic stays untouched, reversing the decision means adding the line back. Being able to switch participation on and off through configuration makes changes of mind cheap. Leaving room to decide things while operating is worth quite a lot.

The same approach covers temporary isolation. If one site develops a fault, dropping just that site from the list lets you investigate without affecting the login experience on the others. Having the option to detach one part instead of stopping everything was another benefit of leaning on configuration.

Link Conversion Reads the Same Configuration

The Author Doesn't Have to Think About It

Alongside configuration management, automatic conversion of cross-site links is the other thing holding operations together. We built a shared component so that writing an ordinary link produces a handover-enabled link automatically.

That removes a specific failure: a link that should have carried the login over quietly staying a plain link. Correctness comes from the mechanism rather than from someone remembering. The more sites there are, the bigger that difference gets.

One Roster, Read by Everything

The link component reads the same permitted-site list described above. Fix the configuration in one place and everything follows — token issuing and verification, and link conversion behaviour along with it.

Making the configuration the single source of truth avoids the mismatch where a new site is recognised in one place and unsupported in another. Whether everything reads the same roster is what decides how stable things stay as the number of sites grows.

Catching Configuration Mistakes Early

The more you move into configuration, the more a typo in that configuration becomes the main source of faults. So each site checks at startup that its configuration is complete, and makes any gap obvious right away.

If a site starts with an empty key or an unregistered entry-point URL, the failure only surfaces when a real user follows a link. That's far too late to find out. Stopping early and reporting the problem was something an AI agent flagged as missing while reviewing the setup, and we added it afterwards.

Summary

Making SSO survive new sites came down to pushing the parts that change often into configuration. To recap:

1. Three settings: externalise the signing key, the permitted-site list, and the entry-point URLs
2. Nothing in the code: keep the lineup of sites separate from the SSO mechanism
3. Every site is symmetric: no special cases, so a site joins by receiving configuration
4. Links read the same roster: the shared component uses the same list, preventing gaps
5. Report configuration mistakes early: check at startup so missing values surface immediately

Where SSO fits overall is in "Single Sign-On Across Multiple EC Sites", the token design itself is in "How Signed Handoff Tokens Work", and the receiving side's processing is in "SSO Callback and Session Establishment Flow".