The Challenge: A Rigid Authentication System

Cocoon initially relied on Passport.js with sub components of it like Passports OpenID Connect (OIDC) components for authentication. However, this setup presented several challenges:

• Limited SSO provider support: Each new SSO integration required code changes, creating friction in customer onboarding.
• Difficult debugging and maintenance: The rigid implementation made issue resolution complex, with low visibility into authentication failures.
• Increased complexity with larger customers: Enterprise clients required various SSO providers (e.g., Okta, Entra, Cloudflare Access), which Passport.js struggled to support.
• Authentication expertise requirement: Managing OIDC configurations internally demanded specialized knowledge, slowing down development.

With customer needs evolving and authorization changes on the horizon, Cocoon sought a more flexible, scalable authentication solution.

“No matter what vendor we picked, I think there's going to be some amount of work, and SuperTokens ended up being the best option.”

Conor CallahanThe engineering manager @ Cocoon

The Search for a Better Solution

Cocoon defined clear technical criteria for its new authentication system:

1. Support for password-based login and SSO (OIDC)
2. Custom auth flows that are not supported by most authentication providers out of the box
• Ability to log in with both work and personal email addresses
• Support for client certificates for specific partners
3. Strong documentation and ease of use to minimize onboarding time
4. Cost-effectiveness compared to alternatives

Evaluated Solutions

The team considered multiple options, including:

• Open-source: K******
• SaaS: S*****, O**, SuperTokens

Their evaluation process included setting up developer accounts and conducting proof-of-concept (PoC) tests. One key factor was how quickly they could get started with minimal external assistance.

After an initial PoC, Cocoon reached out to SuperTokens. The decision to proceed was driven by SuperTokens’ balance between customizability and ease of implementation.

“When compared to other vendors, SuperTokens just offered so much more flexibility. The ability to customize certain functions or endpoints to do what we need  has been super helpful.”

Michael NuellosAn Engineer @ Cocoon

Why Cocoon Chose SuperTokens

Several factors made SuperTokens the ideal choice:

• Flexibility and customization: SuperTokens offered deep customization options via overrides and hooks, eliminating the need for workarounds. This inherent flexibility allowed Cocoon to build out their custom authentication requirements, like allowing users to authenticate with both work and email accounts and client certificates.
• Bridging the build-vs-buy gap: Unlike rigid SaaS solutions, SuperTokens allowed for custom integrations without extensive in-house development.
• Open-source transparency: While not a strict requirement, having access to the GitHub repository was beneficial.
• Comparable pricing: Pricing was in line with other vendors, with good value for the time savings it provided.
• Ease of implementation: The ability to run a local setup quickly accelerated Cocoon’s integration process.

Implementation and Migration

Timeline

• July/August 2024: Development began.
• November 1, 2024: SuperTokens was fully deployed to all users.
• Total duration: 2.5 to 3 months with 1-1.5 engineers.

Challenges and Solutions

• Running both authentication systems in parallel: To ensure a smooth transition, Cocoon kept Passport.js running alongside SuperTokens as a fallback mechanism.
• User migration issues: Some users had multiple accounts due to email variations. Cocoon addressed this by refining its user identity-matching logic during the migration process.

“We feel confident that we can support whatever OIDC conforming SSO provider comes our way. We haven't had any unique ones come yet, but I think we've also had a much easier time debugging when things come up.”

Conor CallahanThe engineering manager @ Cocoon

Results and Impact

Since switching to SuperTokens, Cocoon has seen significant improvements in authentication management:

• Greater SSO provider support: Cocoon can now onboard enterprise customers with diverse identity provider requirements more easily.
• Simplified debugging: Authentication issues are more transparent, reducing resolution time.
• Expanded login options: Google Sign-In has been extended to all users, enhancing convenience.

Future-proofing authentication: Plans are in place to implement passwordless login and multi-factor authentication (MFA), leveraging SuperTokens’ flexible architecture.

Next Steps

Cocoon plans to:

• Complete migration of all users to SuperTokens by the end of February.
• Refine their authorization system to better handle complex role structures.
• Stay updated on SuperTokens’ new features via the monthly newsletter.

By leveraging SuperTokens, Cocoon has transformed its authentication experience, enhancing security, flexibility, and scalability for its growing customer base.

To watch the entire case study discussion video, please click here.