feat: general migration guide

docs/migrate-to-ory/index.mdx

@@ -0,0 +1,283 @@
+---
+id: index
+title: Migrate to Ory tutorial
+sidebar_label: Migrate to Ory
+sidebar_position: 1
+---
+
+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](https://www.ory.sh/contact).
+
+:::
+
+## 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](https://www.ory.sh/docs/hydra/concepts/before-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](../getting-started/oauth2-openid/add-oauth2-openid-connect-nodejs-expressjs) 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](https://www.ory.sh/contact/) 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](../cli/ory-create-project).
+
+:::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](../kratos/manage-identities/identity-schema).
+
+- 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](https://www.ory.sh/docs/getting-started/overview) 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](../account-experience/index.mdx), 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](../kratos/bring-your-own-ui/custom-ui-ory-elements).
+
+## 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](https://www.ory.sh/docs/getting-started/integrate-auth/go#validate-and-login) 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](../kratos/hooks/configure-hooks) 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.
+1. 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.
+1. 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 ](../kratos/manage-identities/managing-users-identities-metadata)
+   documentation.
+1. 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](../reference/api#tag/identity/operation/createIdentity) 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 ](../kratos/manage-identities/25_import-user-accounts-identities.mdx) documentation.
+
+## Import identities
+
+You can use the [create identity API](../reference/api#tag/identity/operation/batchPatchIdentities) 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 ](../kratos/manage-identities/25_import-user-accounts-identities.mdx) 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.
+1. 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.
+1. 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.
+1. 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
+   <ConsoleLink route="project.activity.events" />.
+1. 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](https://slack.ory.sh/) and
+get support from the community. Or contact us for a [free consultation](https://ory.sh/contact) and get expert help from the Ory
+Team.
+
+:::

src/sidebar.js

@@ -320,6 +320,7 @@ module.exports = {
       type: "category",
       label: "Migrating to Ory",
       items: [
+        "migrate-to-ory/index",
         "hydra/self-hosted/migrating-from-mitreid",
         "migrate-to-ory/auth0",
       ],