SSO Configuration That Scales with New Sites

Introduction

Once cross-site single sign-on (SSO) is running across three sites, one question always follows: "How much effort will it take to launch a fourth brand?"

If site information is baked directly into the SSO logic, this becomes a nightmare. Adding a new site means editing code all over the place and re-testing everything — and expansion becomes a chore. In this article I'll cover what we pushed out of the code and how we managed the configuration so that adding or removing a target site is "just a config change."

What to Put in Configuration

The Three Things SSO Needs

Boiled down, the information that all sites share or reference to make SSO work comes to three things. We push these out of the code and into configuration such as environment variables.

Of these, the signing secret is shared as the same value across all sites, while the valid-site list and callback URLs act as a roster showing "who's in the club and where to send things." The aim is a shape where the logic simply reads this roster.

Why Not Write It in Code

Hard-coding site domains or URLs into the code makes every addition a "code change." Code changes need review and deployment, so even a small addition tends to become a big deal.

Configuration, on the other hand, means just adding a line to the roster — without touching the logic at all. It's the design basic of separating "things that change often (the lineup of sites)" from "things that rarely change (the SSO mechanism)." This line makes operations far easier down the road.

Making Site Addition Config-Only

What You Do When Adding

When adding a new brand site to the SSO club, there's surprisingly little to do. Add that site to the valid-site list, register its callback URL, and distribute the shared secret. With these three, the new site can be both a sender and a receiver.

The Symmetric Design Pays Off

Because every site symmetrically carries the same SSO mechanism, a new site can "join the club just by distributing config." That uniformity — no site gets special treatment — is the source of the extensibility.

Automatic Cross-Site Link Conversion

The CrossSiteLink Device

Alongside configuration management, automatic cross-site link conversion is what supports operations. We built a mechanism where a developer just writes a normal link, and it automatically switches to an SSO link.

This prevents SSO gaps (an accident where a link that should carry over ends up a plain link). Rather than relying on human attention, correctness is guaranteed by the mechanism.

Configuration and Links in Lockstep

What this CrossSiteLink references is the same valid-site list from earlier. In other words, fix the config in one place and everything follows — not just token issuance and verification, but the link conversion behavior too.

By making the configuration the "single source of truth," you avoid inconsistencies like a new site being recognized in one place but unsupported in another. Configuration management and link conversion look at the same roster — that consistency is what gives peace of mind in operations.

Conclusion

The key to SSO that survives adding sites came down to "pushing the things that change often into configuration." To recap:

1. Three config items: externalize the signing secret, valid-site list, and callback URLs
2. Don't hard-code: separate the lineup of sites from the SSO mechanism
3. Symmetric design: every site carries the same mechanism and can join by distributing config
4. Links follow config: CrossSiteLink references the same roster, preventing gaps

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."