Merge Remix-SSO and Platform-SSO-Services
Date: 2025-12-02
Status: proposed
Context
Our team currently maintains a handful of applications. One is the remix-sso app, which is a Remix-based frontend for SSO services.
The other apps are dedicated lambdas that live in the platform-sso-services repository.
Maintaining multiple applications increases the overhead for developers, as they need to switch contexts, manage different deployment pipelines, handle separate configurations and duplicate work (updating dependencies).
If we focus on just moving the functionality (without refactoring) the migration should hopefully be able to be done within a week.
Decision
We are going to work towards consolidation the platform-sso-services lambdas into the remix-sso application.
Ultimately the goal is to have a single repository and application for all SSO-related functionality.
We are not going to do a big-bang migration, but rather incrementally move functionality over time.
Lambdas that become obsolete with the phase-out of IP-based SSO access will be retired instead of migrated.
Consequences
The two repos/projects were orignially separated to account for the different audiences.
The remix-sso app serves (both internal and external) users. While the lambdas in platform-sso-services are primarily used to serve endpoints or other
services we need to provide our services (e.g. endpoints to be called by Auth0).
Risks and Mitigations
- Codebase size: The
remix-ssoapp may become too large and complex, making it harder to maintain.- Currently we have less than 10K lines of code in both repositories combined. Even after consolidation we expect the codebase to remain manageable.
- Service interruptions: Migrating services may lead to temporary outages or disruptions.
- We can run both the lambdas and the new endpoints in parallel during the migration phase, allowing us to switch over gradually. Most of the endpoints are called from Auth0 actions and are already called based on a BASE_URL that's loaded at runtime. So we can use this lookup to switch between the old and new endpoints without changing the Auth0 configuration.
- Effort: The migration may require significant effort and resources.
- Because of how different the two codebases are (e.g. plain JS vs TS, different frameworks) it is hard to estimate the effort required upfront.
- We will start with migrating smaller services first to get a better understanding of the effort involved.
- We should also aggressively descope refactorings (e.g. migrating JS to TS) to focus on just moving the functionality over first.
- Since this is a rather "mechanical" task, we should evaluate how much of the work can be handed off to AI agents
Positive Consequences
- The development workflow will be simplified, as developers will only need to work with a single application.
- Deployment processes will be streamlined, reducing the complexity of managing multiple pipelines.
- Solutions like the feature environments for testing in Remix can be leveraged for all SSO-related features.
- Renovate PRs will only have to be handled in one repository, reducing maintenance overhead.
Negative Consequences
- There will be an initial migration effort required to move functionality from the lambdas to the Remix app.
- The
remix-ssoapplication will grow in size and complexity, which may impact build times and deployment processes.
Implementation Details
To better assess the migration effort we'll give a brief overview of the existing services in platform-sso-services:
- id-based-auth-service: This is used to login users based on their ID from the monolith (e.g. after registration). This is in plain JS and must be migrated to TS during the consolidation.
- permissions-service: Those endpoints are called from Auth0 in our post login actions to update permissions/roles in our legacy system (maybe we don't need this since permissions are updated on every login/refresh)
- sso-service: This service is used to create users in our legacy system from Auth0, for example by this post login action.
These services won't be needed once the IP-based SSO access is fully phased out.
The repository also contains a dedicated NPM package for shared code. Once all our services are consolidated into the Remix app we can share code directly via imports.
Further consolidation opportunities
We have more repositories that could be consolidated into the remix-sso app in the future:
- sso-docs: With all our important code in one place, we could also move our SSO documentation into the Remix app. This would allow us to update documentation alongside code changes, ensuring that our docs are always up-to-date.
- infrastructure: Since we shared our infrastructure from apps in different repositories, we had to maintain a separate repository for our CDK code.
Once everything is in one place, we could consider moving the infrastructure code into the
remix-ssorepository as well. This would simplify infrastructure management and allow for tighter integration between application code and infrastructure definitions. - login-e2e-tests-playwright: Our end-to-end tests for the login flow could also be integrated into the
remix-ssoapp. This would allow us to run tests as part of the application's CI/CD pipeline instead of having to rely on triggering tests from a separate repository. - cpe-internal: Our current approach of maintaining a separate repo with a test app has clearly failed. This app is
always out of date and nobody uses it. We could consider integrating this test app into the
remix-ssorepository as well, to integrate CI/CD that update automatically to use the changes made in the remix-sso library
What not to consolidate
The auth0-terraform-provider repository should remain separate, as it serves a different purpose (infrastructure as code for Auth0). While we also do have JS in there this runs in an entirely different environment (Auth0 Actions) and has different deployment requirements.