← Blog

OpenID Connect SSO in Symfony: lessons from Campaign Studio

At Acquia I built the OpenID Connect login for Campaign Studio, Acquia's commercial distribution of Mautic, the open-source marketing-automation platform built on Symfony. I was part of a team, but the feature was mine, built end to end and reviewed by my teammates. Enterprise customers wanted their people signing in through Okta, Google Workspace and the like, with their identity provider's MFA in front of it, instead of another password.

The redirect to the provider and the token coming back took a fraction of the time. Almost all of the real work, and almost every decision that ended up in the product's documentation, was about something else: deciding which local account a provider's user is, and what happens at the edges of that answer.

The login flow is the smallest piece

Authorization code flow, a state parameter you actually verify, and strict validation of the ID token: signature, issuer, audience, expiry and nonce. Symfony's security component holds this comfortably, whether you write a custom authenticator or use a bundle. If you use a bundle, know which of those checks it is doing on your behalf.

The provider also has to know where to send people back. Campaign Studio's is a fixed path on the instance, /s/open_id/login_check, that admins register with their provider. Keep that URL stable: change it and every customer's configuration breaks at once.

Link on sub, and only on sub

You have local accounts. The provider has its own. Something has to decide when two of them are the same person, and getting it wrong in either direction hurts: link too eagerly and you have an account-takeover path, too reluctantly and every customer's first SSO login creates a duplicate.

Email is the obvious key, and it is the wrong one. Not every provider verifies addresses, and people change them. OpenID Connect gives you the right key: the sub claim, a stable identifier the provider guarantees is unique for that user.

In Campaign Studio this is the Identifier field, and it defaults to sub. The documentation carries a warning in bold, because changing it is the most destructive thing an admin can do in that screen: it deletes every existing link between local and provider accounts. Get the new value right and everyone has to relink. Get it wrong and nobody can log in until support steps in.

In code, the rule is short:

public function resolveUser(string $sub, ?string $email): User
{
    // The provider's stable ID is the only key we trust for an existing link.
    $user = $this->users->findOneBy(['oidcSubject' => $sub]);
    if (null !== $user) {
        return $user;
    }

    // Never link to an existing account by email: anyone who can claim that
    // address at the provider would be handed the account.
    if (!$this->settings->allowsRegistration()) {
        throw new CustomUserMessageAuthenticationException(
            'This account is not linked yet. Sign in with your password to link it, or ask an administrator.'
        );
    }

    return $this->provisioner->createFromOidc($sub, $email);
}

Linking existing users

So how does an existing user get linked if you will not match them by email? Campaign Studio offers two ways, and both are deliberate:

  • The user proves both identities. With SSO required, a user who is not yet linked signs in with their existing password and is sent straight on to the provider. Once they authenticate there, the two accounts are linked. They proved they own both, so nothing is guessed.
  • An admin links them by setting the user's Open ID identifier by hand.

The first one makes rolling SSO out to a customer with hundreds of existing users a non-event. Nobody's account is recreated, and nobody loses history.

Enforcement is a setting, not a state of the world

Enterprise buyers will ask you to require SSO. Campaign Studio has a toggle for it: Require users to authenticate with OpenID Connect, which stops users signing in any other way.

The lesson is to treat that as a setting with an escape hatch rather than an absolute. Identity providers get misconfigured, and a customer's whole team can end up locked out. The SAML integration, for example, redirects the login page to the provider by default but keeps a direct sign-in path at /s/login. Decide up front who can still get in when the provider is broken, and make that an explicit, documented exemption rather than an accident of the code.

Just-in-time provisioning, and its default role

Creating the local user on their first successful SSO login, instead of making an admin pre-create everyone, is a feature customers ask for by name. In Campaign Studio it is the Allow new user registration toggle, paired with a Role for new users setting.

That role is the decision to get right. In Campaign Studio, new users get a predetermined default role unless the admin picks one. Which default is right depends on who actually uses the feature. For most of our customers it was administrators setting up SSO for other administrators, so a generous default fit. For a product where every employee signs in, the least privileged role is the only safe one. Either way, document what happens when no role is chosen, because an admin who switches on registration without picking one is going to happen.

Unlinking is a security feature

Accounts get linked to the wrong provider identity, people leave, and customers change identity providers. You need unlinking, and you need to be honest about what it does not do:

  • Unlinking does not end a session. A user who is already signed in stays signed in. Revoking access means disabling or deleting the local account, not just clearing the link.
  • With registration on, unlinking alone is not enough. The user can sign in through the provider again and be provisioned a brand-new account. Disable them at the provider as well.

Both points are spelled out in Campaign Studio's documentation, and both are the kind of thing that only becomes obvious once a customer has had to remove someone in a hurry.

Two fixes that made it upstream

Two small fixes from this work went into open-source Mautic, and both are about identity resolution at the edges:

  • The SAML username fallback (mautic#12557). When an admin left the SAML username mapping blank, the documented behaviour was to fall back to the user's email. It did not, so the lookup failed, Mautic tried to create a new user, and that failed too, because the email was already taken. Lookup and creation have to agree on the same key, or a returning user looks like a stranger who cannot be let in.
  • Erasing credentials (mautic#12507). Symfony calls eraseCredentials() on the user after authentication, and it should clear any sensitive data held only for the login. Mautic's user kept the plain-text and current password around. It was a minor fix with a test, and exactly the kind of thing that never shows up in a demo.

What to test

Not the happy path; that one you will notice. Test the token that has expired, the token issued for a different audience, two concurrent first logins for the same new user, a link attempt against an email that already exists, a blank or changed identifier mapping, and the enforcement setting with a provider that is misconfigured. Those are the ones that become incidents.

Takeaway

SSO is not a login feature. It is an account-lifecycle feature: linking, enforcement, provisioning and unlinking. Budget for it that way, and make the identifier you link on the centre of the design rather than an afterthought.

This is the kind of work I do. See security and authentication.