Migrate to Ory tutorial

This tutorial will guide you through the process of migrating your existing authentication system to Ory Identities, creating Ory Network projects, setting up identity schemas, and customizing the user interface to match your current interface.

note

This guide is an initial reference and may not cover all aspects of your use case. If you have any questions or need more help, don't hesitate to get in touch with Ory Support for help.

Pre-migration considerations

Before starting the actual migration you should choose a migration strategy.

Migration scenario

• Scenario 1 - Migrating from a self-rolled solution

  If you're coming from a custom-built authentication solution, consider using Ory Identities. This approach simplifies the migration by focusing solely on identity management without introducing the complexities of OAuth2. If you plan to move towards OAuth2 eventually, you can plan for that transition once the initial migration is complete. To get started, refer to the "Integrate Frontend & Backend" sections later in this guide.

info

If you are not sure whether or not you need OAuth2 for your use case, please read the When to use OAuth2 documentation.

• Scenario 2 - Migrating from Auth0 or another OAuth2-based solution

  If you're migrating from Auth0 or any other OAuth2-based login solution, you'll want to use Ory OAuth2 together with Ory Identities. This setup allows you to keep your existing OAuth2-based flow while integrating it with Ory's identity management. This approach is ideal if you want to keep your current implementation without making significant changes. To get started, refer to the Ory OAuth2 quickstart guide which provides instructions on setting up an OAuth2/OIDC flow with Ory.

• Scenario 3 - Other

  If your authentication system doesn't fall into the categories described above - such as hybrid systems, legacy protocols, or any other unique solution - you may need a different approach to migration. For such unique or complex migrations, we recommend consulting with Ory to get a recommendation. The Ory team can help you design a custom migration plan that aligns with your specific requirements.

Migration strategy

When migrating user data from an old system to a new one, the process involves two main steps: transferring existing data and "go-live" when users start authenticating with the new system. The choice of migration strategy depends on your specific use case, the shape of existing data, and the number of "go-lives" you need to manage.

• Big bang - Migrate everyone at once.
• Stepped - Migrate your applications or user segments individually. This is the most common choice.
• Graceful - Migrate when a user authenticates, running both solutions in parallel.

Each migration strategy has its strengths and challenges. The ideal choice depends on factors such as the complexity of your system, the number of users, and your organization's tolerance for risk and downtime.

Big bang migration

In a big bang migration, also known as "offline migration", all user data is transferred at once, and a single "go-live" event is scheduled, where all users start using the new system simultaneously.

Advantages of big bang migration

• Simplicity: Since there is only one "go-live", the migration process is easier to manage and plan.
• Time efficiency: The migration process happens in one go, reducing the time needed for the transition.
• Less complexity: There is no need to run two systems in parallel and you can retire the previous solution immediately.

Drawbacks of big bang migration

• High risk: If any issues occur during the cutover, the impact can be significant, affecting all users.
• Downtime: This approach may require planned system downtime to ensure data consistency, which can disrupt users.
• Increased preparation: Requires extensive planning and testing to mitigate risks, making it more resource-intensive during that phase.

A big bang migration is often not the best choice due to the risk and downtime, but it is recommended when

• the number of users is low / app is simple
• downtime isn't a problem
• you need to retire the current solution yesterday

Stepwise migration

Stepwise migration, also called "application-based migration", involves transferring user data in phases, focusing on specific applications, services, or user segments at a time. This approach results in multiple "go-lives", each affecting a defined group of users.

Advantages of stepwise migration

• Reduced risk: By migrating in phases, issues are isolated to specific apps or user segments.
• Flexibility: Allows for adjustments and optimizations between phases based on lessons learned.
• Minimized/no downtime: Since the migration occurs in stages, downtime can be limited to smaller user groups or avoided completely.

Drawbacks of stepwise migration

• Complex management: Multiple "go-lives" require more coordination and detailed planning, increasing operational complexity.
• Extended timeline: The migration process takes longer as it is broken down into phases.
• Resource demands: Running both systems in parallel during the transition can strain resources.

A stepwise migration is the best choice in most cases, especially when

• you manage multiple apps/segments of users with different underlying auth systems
• downtime should be mostly avoided
• you have some time to migrate

Graceful migration

Graceful migration - also called "slow migration", "rolling migration", or "online migration" - involves running both the old and new systems in parallel, gradually migrating users as they authenticate. This approach features two "go-lives": the initial application "go-live" and subsequent user-specific cutovers during login.

Advantages of graceful migration

• Low risk: The gradual transition reduces the risk of widespread issues, as only a few users are affected at any given time.
• No hashed credentials needed: Users are migrated during their "normal" authentication process, so you don't need to import credentials. Great if you don't have access to the hashed credentials.
• No downtime: Both systems operate simultaneously until the migration is completed.

Drawbacks of graceful migration

• Extended migration period: The process takes longer as users are migrated individually over time.
• Increased complexity: Maintaining synchronization between two systems adds complexity to the migration process.
• Potential for data inconsistencies: If not carefully managed, there may be discrepancies between the two systems during the transition period.

A graceful migration is a good choice when

• you don't have access to hashed credentials or they are hashed with a proprietary algorithm
• absolutely no downtime is acceptable
• running the current solution until the end of migration isn't a problem

Create Ory Network projects

Now that you have chosen your migration strategy, you can begin the actual migration process by setting up your Ory Network projects. This involves creating a new project environment where the migration will take place.

You can create a new Ory Network project using the Ory CLI. The command ory create project allows you to specify the environment of the project, the output format, the name of the project, and the workspace to use. More details about creating a project can be found here.

info

Before migrating your production environment, perform the migration in a development or staging environment. This allows you to test and refine the process without affecting your live data or users.

Define identity schema

To match identities from your current system with the new Ory system, you can customize the identity schema in Ory to meet your specific requirements. This schema defines the types of data that the system can store for users, including names, email addresses, phone numbers, and other authentication-related information. Additionally, you can specify extra metadata fields to be included in user profiles. Ory offers default presets to assist you in creating and managing identity schemas. More details about identity schemas can be found here.

• Do store profile data in your identity that is used across your system. This includes the usernames, email addresses, phone numbers, first names, and last names.
• Do not store business logic in your identity, store this information in other systems, such as your application database. This includes for example credit card information, shipping addresses, shopping cart items, or user preferences. See also the following section on backend integration.

Integrate frontend

To make authenticated API calls using Ory, start by properly configuring your domain and subdomains. By default the cookie domain is set to the root domain (e.g., example.org) when you add a custom domain. This ensures that cookies can be shared across all subdomains.

• Example subdomain structure:
  • Run Ory at auth.example.org.
  • Host your backend API at api.example.org.
  • Serve your frontend UI at www.example.org or another designated subdomain.

This setup allows both your front end and back end to access the authentication session cookies managed by Ory.

To begin integrating Ory into your frontend, it's helpful to start with the "protect a page with login" guides that cover the basics of developing with Ory for various programming languages and frameworks, including SDK usage and essential setup steps.

Ory Network has two types of user interfaces. We recommend starting with the built-in Account Experience, which offers a standard user interface, covering all self-service flows with the option to style branding to get you up and running. If you prefer a custom user interface that matches your current design 1:1, Ory allows you to create and style a custom UI that integrates seamlessly with your existing setup. You can do this using the API directly, the SDK for your language, or - if you are working in the React ecosystem - Ory Elements. Ory Elements is a component library designed to make building login, registration, and account pages for Ory easy. It is modular and customizable, allowing you to use only the components you need while tailoring them to fit your implementation's design. The UI created with Ory Elements changes dynamically to adapt to your Ory Network configuration. More details about customizing the user interface with Ory Elements can be found here.

Integrate backend

When the frontend makes an API call to your backend, it will include the necessary cookies. Your backend must then forward these cookies when calling the Ory API to validate the session. For example in a Go backend, you could use a middleware to intercept API requests and validate the session by calling Ory’s toSession() method. Ensure that the cookies received from the front end are forwarded in this call. Since backend calls to Ory’s API won’t automatically include cookies, you must manually attach the relevant cookies to these requests. This is important for the backend to be able to check the session.

When using Ory to manage identities, it is best practice to store business logic in your application database and keep only authentication-relevant data in Ory. Here’s a general approach:

1. Configure Ory Actions to send webhooks to your server after user registration or other identity-related events. The webhook payload will include the data of the newly created identity.
2. Upon receiving the webhook, your server can create a corresponding user record in your database. This allows your system to link Ory-managed identities with your business logic.
3. Establish a connection between the Ory identity and the user record in your database by storing the user.id in identity.metadata_public.id. This ensures that subsequent API calls can easily map the Ory identity to the correct internal user. More about metadata in the Identity metadata & traits documentation.
4. Now when the frontend makes API calls containing the Ory cookie or token, the backend should verify the session using the whoami API endpoint. This endpoint returns the session details, including the identity, allowing the backend to authenticate the request and link it to the internal user record.

Get user data and credentials

With authentication now set up on your front end and back end, the next step is to prepare your existing user identities for migration. If you're using a managed identity solution, it’s a good idea to start the export process early, especially if there's no straightforward way to export the identities and you might need to go through a support process.

Export user data from your existing authentication solution or database and find out the hashing algorithm used to hash their credentials. If your passwords are not hashed, you can bypass this step, as Ory will handle password hashing automatically during the import process. Ory supports a range of hashing algorithms; if yours is supported, use the create identity API to import your users. If the hashing algorithm isn't supported or if you can't get the hashed passwords from your current authentication system, you may want to do a "graceful" migration and use the password migration hook to migrate your existing users. You can find more details in the Import identities documentation.

Import identities

You can use the create identity API to bulk import identities into Ory. A maximum of 2000 identities can be created in a single request. If you need to import more identities, you need to split the import into multiple requests. The endpoint accepts a JSON array of identities, each of which must have a create property that holds the identity that should be created. You can find more details in the Import identities documentation.

Phased migration for active sessions

Ory does not support the direct import of active sessions from your existing system. To ensure that users with active sessions from the old system can continue accessing your services without needing to reauthenticate immediately, implement a transition period during which both the old and new systems operate concurrently. During this period, all user authentication flows—including login, registration, password recovery, and settings management—should be managed by Ory. However, your backend must be configured to recognize and accept sessions from both the old system and Ory.

As the transition progresses, gradually phase out the old system. Once most or all active sessions from the old system have expired or been replaced by new sessions in Ory, you can complete the migration to Ory exclusively. This gradual approach minimizes user disruption and provides your development team with the time needed to resolve any potential issues that may arise during the migration.

Go live

After successfully migrating your data and testing the integration in your development or staging environment, it's time to go live with Ory in your production environment.

1. Final testing: Before switching over to Ory in production, conduct thorough testing of all user authentication flows, identity management features, and access controls. This includes testing edge cases, error handling, and load testing to ensure the system can handle your user base.
2. Prepare a rollback plan: In case any issues arise during the go-live process, have a rollback plan in place. This may involve reverting to your previous authentication system or restoring data from backups.
3. Schedule the go-live: Choose a time for the go-live that minimizes the impact on your users, such as during low-traffic periods. Communicate the planned migration to your users in advance, including any expected downtime or changes they should be aware of.
4. Monitor the transition: As you switch over to Ory, closely monitor the system for any issues, such as failed authentications, performance bottlenecks, or user complaints. Use live events to monitor the system under Activity → Logs & Events in the Ory Console.
5. Optimize and refine: After the go-live, continue to monitor the system and gather user feedback.

Once your Ory integration is stable and users are successfully authenticating with the new system, your migration is complete.

info

Ory is here to help! To get support in your migration beyond this guide join the Ory Community Slack and get support from the community. Or contact us for a free consultation and get expert help from the Ory Team.