From a350ae8452a627a326384df97a67ca8eb86b816d Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Tue, 7 Oct 2025 21:37:17 -0700 Subject: [PATCH 1/5] chore: migration guide updates --- docs/migrate-to-ory/migrate/create-project | 18 ++ docs/migrate-to-ory/migrate/define-id-schema | 21 +++ docs/migrate-to-ory/migrate/go-live | 27 +++ docs/migrate-to-ory/{ => migrate}/index.mdx | 170 +++++++++++++----- docs/migrate-to-ory/migrate/integrate-backend | 30 ++++ .../migrate-to-ory/migrate/integrate-frontend | 33 ++++ .../migrate-to-ory/migrate/migrate-strategies | 106 +++++++++++ docs/migrate-to-ory/migrate/user-identities | 40 +++++ src/sidebar.ts | 16 +- 9 files changed, 419 insertions(+), 42 deletions(-) create mode 100644 docs/migrate-to-ory/migrate/create-project create mode 100644 docs/migrate-to-ory/migrate/define-id-schema create mode 100644 docs/migrate-to-ory/migrate/go-live rename docs/migrate-to-ory/{ => migrate}/index.mdx (68%) create mode 100644 docs/migrate-to-ory/migrate/integrate-backend create mode 100644 docs/migrate-to-ory/migrate/integrate-frontend create mode 100644 docs/migrate-to-ory/migrate/migrate-strategies create mode 100644 docs/migrate-to-ory/migrate/user-identities diff --git a/docs/migrate-to-ory/migrate/create-project b/docs/migrate-to-ory/migrate/create-project new file mode 100644 index 000000000..a0643ee97 --- /dev/null +++ b/docs/migrate-to-ory/migrate/create-project @@ -0,0 +1,18 @@ +--- +id: create-project +title: Create project +sidebar_label: Create project +sidebar_position: 3 +--- + +## 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). + +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. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/define-id-schema b/docs/migrate-to-ory/migrate/define-id-schema new file mode 100644 index 000000000..3e92a070b --- /dev/null +++ b/docs/migrate-to-ory/migrate/define-id-schema @@ -0,0 +1,21 @@ +--- +id: define-id-schema +title: Define identity schema +sidebar_label: Define identity schema +sidebar_position: 3 +--- + + +## 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. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/go-live b/docs/migrate-to-ory/migrate/go-live new file mode 100644 index 000000000..8ccc24868 --- /dev/null +++ b/docs/migrate-to-ory/migrate/go-live @@ -0,0 +1,27 @@ +--- +id: go-live +title: Go live +sidebar_label: Go live +sidebar_position: 2 +--- + + +# 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 + . +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. \ No newline at end of file diff --git a/docs/migrate-to-ory/index.mdx b/docs/migrate-to-ory/migrate/index.mdx similarity index 68% rename from docs/migrate-to-ory/index.mdx rename to docs/migrate-to-ory/migrate/index.mdx index ff0e8e77d..3ff5bce2d 100644 --- a/docs/migrate-to-ory/index.mdx +++ b/docs/migrate-to-ory/migrate/index.mdx @@ -1,56 +1,144 @@ --- id: index -title: Migrate to Ory tutorial -sidebar_label: Migrate to Ory +title: Migrate to Ory Network +sidebar_label: Migrate to Ory Network 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. +# Migrate to Ory Network -:::note +Before you can migrate smoothly, you need a complete picture of how your identity management system works today. This step ensures +nothing gets missed — from everyday login flows to rare edge cases — and sets the foundation for mapping existing features to +Ory Network's equivalent features. -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). +Why it matters: Not understanding your existing system’s behavior is the #1 cause of unexpected regressions during cutover. With +Ory Network, you gain full control, and with it, the ability to shape your system’s flows exactly to your needs. -::: +# Understand your current identity management system -## Pre-migration considerations +Below are example IAM scenarios supported by Ory Network. Use them to identify which scenario best fits your specific needs and +understand the unique requirements of each approach. Each scenario differs in complexity and implementation needs. Use these IAM +scenarios to help identify and map the authentication flows for your application. -Before starting the actual migration you should choose a migration strategy. +## Identify your IAM scenario +- CIAM +- B2B +- Workforce +- Agentic AI -### Migration scenario +### CIAM (Customer Identity and Access Management) -- **Scenario 1** - Migrating from a self-rolled solution +Your company sells products or services directly to individual consumers. - 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. +#### Key IAM requirements +- Self-service registration, login, and profile management for end users +- Social login, multi-factor passwordless options, and robust account recovery +- Privacy compliance (GDPR, CCPA) +- High-scale performance for millions of users -:::info +#### Ory Network features +- Identity management & authenitication (based on Ory Kratos) +- Authorization (based on Ory Hydra, optional for OAuth2/OIDC) -If you are not sure whether or not you need OAuth2 for your use case, please read the -[When to use OAuth2](../hydra/concepts/before-oauth2) documentation. +### B2B (Business-to-Business) -::: +Your company sells products or services directly to other businesses rather than individual consumers. Your customers are organizations +that use these products or services to run their own operations. -- **Scenario 2** - Migrating from Auth0 or another OAuth2-based solution +#### Key IAM requirements - 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. +- Multi-organization user management +- SSO with SAML/OIDC providers +- Self-service partner onboarding +- Role-based permissions and API controls -- **Scenario 3** - Other +#### Ory Network features - 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. +- Identity management & authenitication (based on Ory Kratos) +- Authorization and single sign-on (based on Ory Hydra/Ory Polis) +- Permissions (based on Ory Ketos) +- Zero-trust access proxy (based on Ory Oathkeeper) -### Migration strategy +### Workforce (Business-to-Enterprise) + +Your company provides products or services. Your company wants to manage access for a single organization's extended workforce. You want to +consolidate employee user accounts and identities across multi-tenant brands, applications and systems. You need to seamlessly connect with +existing enterprise identity providers and other 3rd party systems and streamline user onboarding, offboarding, and permission management. + +#### Key IAM requirements +- Streamline onboarding/offboarding of employee, contractor, and temporary workers +- Role-based access aligned with organizational hierarchy +- HR system integration with flexible identity schemas +- Integrate with enterprise identity providers and third-party systems +- Time-bound permissions and role assignments +- Zero-trust security, MFA, and SSO for enterprise applications + +#### Ory Network features +- Identity management & authenitication (based on Ory Kratos) +- Authorization and single sign-on (based on Ory Hydra/Ory Polis) +- Permissions (based on Ory Ketos) +- Zero-trust access proxy (based on Ory Oathkeeper) +- Webhooks + +### Agentic AI + +Your company wants to enable AI applications to securely connect to data sources and tools. For example, servers that host resources and +clients (AI applications) to discover and use those resources. + +#### Key IAM requirements +- Standardized protocol that works across many tools and data sources +- Built-in authentication and access control + +#### Ory Network features +- Identity management & authenitication (based on Ory Kratos) +- Authorization (based on Ory Hydra) +- Permissions (based on Ory Ketos) +- Zero-trust access proxy (based on Ory Oathkeeper) + +## Map all authentication and identity flows in your application + +Build a complete picture of every authentication-related process in your system. Use your IAM scenario’s Key IAM requirements to help identify +authentication and identity flows. This ensures you don’t miss critical flows during migration. + +1. Identify all entry points where authentication occurs (e.g., web app login, mobile app sign-in, API tokens, social or enterprise sign-ins). +1. Create a comprehensive inventory of flows, for example: + - Registration / Sign-up + - Sign-in/Sign-out + - Multi-Factor Authentication (MFA) + - Password reset and account recovery + - Account linking (social, enterprise logins) + - User profile management + - Token refresh and session handling + - Recovery flows, consent screens, or partner-specific integrations +1. Visualize flows with diagrams (sequence diagrams or flow charts) to surface dependencies and hidden complexity. +1. Note where authentication interacts with other systems (databases, CRMs, partner apps, or external APIs). + + +### Map your existing IAM functionality to Ory Network’s equivalent capabilities +Using your list of authentication and identity flows, create a side-by-side table to map out existing functionality and Ory Network’s equivalent +capabilities. While the majority of the time you'll find your existing functionality neatly maps to Ory's capabilities, now is the best time to +identify when it does not. Some examples: + +- Not all vendors strickly comply with standards, whereas Ory does, so you might discover you need to +change how you implement functionality to be compliant. +- You might have a unique use case to solve that requires additional help from our support. + +Table 1: An example of mapping functionality + +| Existing Functionality | Ory Capabilities | +|---|---| +| JSON Web Tokens | [Ory Session cookies/tokens](https://www.ory.sh/docs/identities/session-to-jwt-cors)| + +At the end of this process you should have a living document with diagrams that capture: + +- All authentication and identity flows +- Your system's existing functionality and Ory Network's equivalent capabilites +- Any existing dependencies on external systems +- Edge cases requiring special handling + +This will serve as your blueprint for planning, designing, testing, and validating your migration. + +## 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, @@ -63,18 +151,18 @@ the shape of existing data, and the number of "go-lives" you need to manage. 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 +### 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 +#### 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 +#### 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. @@ -87,20 +175,20 @@ A big bang migration is often not the best choice due to the risk and downtime, - downtime isn't a problem - you need to retire the current solution yesterday -#### Stepwise migration +### 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 +#### 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 +#### 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. @@ -112,20 +200,20 @@ A stepwise migration is the best choice in most cases, especially when - downtime should be mostly avoided - you have some time to migrate -#### Graceful migration +### 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 +#### 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 +#### 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. diff --git a/docs/migrate-to-ory/migrate/integrate-backend b/docs/migrate-to-ory/migrate/integrate-backend new file mode 100644 index 000000000..d870a8c20 --- /dev/null +++ b/docs/migrate-to-ory/migrate/integrate-backend @@ -0,0 +1,30 @@ +--- +id: integrate-backend +title: Integrate backend +sidebar_label: Integrate backend +sidebar_position: 1 +--- + +# 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](../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. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/integrate-frontend b/docs/migrate-to-ory/migrate/integrate-frontend new file mode 100644 index 000000000..29abd4091 --- /dev/null +++ b/docs/migrate-to-ory/migrate/integrate-frontend @@ -0,0 +1,33 @@ +--- +id: integrate-frontend +title: Integrate frontend +sidebar_label: Integrate frontend +sidebar_position: 1 +--- + +# 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](../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](../elements/index.mdx). \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/migrate-strategies b/docs/migrate-to-ory/migrate/migrate-strategies new file mode 100644 index 000000000..364e5363a --- /dev/null +++ b/docs/migrate-to-ory/migrate/migrate-strategies @@ -0,0 +1,106 @@ +--- +id: migrate-strategies +title: Migration strategies +sidebar_label: Migration strategies +sidebar_position: 2 +--- + +## 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). + +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. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/user-identities b/docs/migrate-to-ory/migrate/user-identities new file mode 100644 index 000000000..dbc8801c6 --- /dev/null +++ b/docs/migrate-to-ory/migrate/user-identities @@ -0,0 +1,40 @@ +--- +id: user-identities +title: Migrate user identities +sidebar_label: Migrate user identities +sidebar_position: 3 +--- + +## Get existing user identities ready for migration +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 user 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. \ No newline at end of file diff --git a/src/sidebar.ts b/src/sidebar.ts index 804bae1d8..5ebf07998 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -197,7 +197,21 @@ const quickstart: SidebarItemsConfig = [ label: "Migrate to Ory", collapsed: false, collapsible: false, - items: ["migrate-to-ory/index", "migrate-to-ory/auth0"], + link: { + type: "doc", + id: "migrate-to-ory/migrate/index", + }, + items: [ + "migrate-to-ory/migrate/index", + "migrate-to-ory/migrate/migrate-strategies", + "migrate-to-ory/migrate/create-project", + "migrate-to-ory/migrate/define-id-schema", + "migrate-to-ory/migrate/integrate-frontend", + "migrate-to-ory/migrate/integrate-backend", + "migrate-to-ory/migrate/user-identities", + "migrate-to-ory/migrate/go-live", + "migrate-to-ory/auth0", + ], }, ] From c1cc94d04d729098bd494d6a27c4d8154bf25c42 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Thu, 9 Oct 2025 07:40:56 -0700 Subject: [PATCH 2/5] chore: migration guide updates --- docs/migrate-to-ory/auth0.mdx | 8 +- .../{create-project => create-project.mdx} | 8 +- ...{define-id-schema => define-id-schema.mdx} | 11 +- docs/migrate-to-ory/migrate/faq-migrate.mdx | 8 + .../migrate/{go-live => go-live.mdx} | 3 - docs/migrate-to-ory/migrate/index.mdx | 354 +----------------- ...ntegrate-backend => integrate-backend.mdx} | 12 +- ...egrate-frontend => integrate-frontend.mdx} | 12 +- ...rate-strategies => migrate-strategies.mdx} | 4 +- .../migrate-to-ory/migrate/migrate-to-ory.mdx | 130 +++++++ docs/migrate-to-ory/migrate/test-validate.mdx | 9 + .../{user-identities => user-identities.mdx} | 19 +- src/sidebar.ts | 33 +- 13 files changed, 209 insertions(+), 402 deletions(-) rename docs/migrate-to-ory/migrate/{create-project => create-project.mdx} (85%) rename docs/migrate-to-ory/migrate/{define-id-schema => define-id-schema.mdx} (83%) create mode 100644 docs/migrate-to-ory/migrate/faq-migrate.mdx rename docs/migrate-to-ory/migrate/{go-live => go-live.mdx} (99%) rename docs/migrate-to-ory/migrate/{integrate-backend => integrate-backend.mdx} (81%) rename docs/migrate-to-ory/migrate/{integrate-frontend => integrate-frontend.mdx} (79%) rename docs/migrate-to-ory/migrate/{migrate-strategies => migrate-strategies.mdx} (98%) create mode 100644 docs/migrate-to-ory/migrate/migrate-to-ory.mdx create mode 100644 docs/migrate-to-ory/migrate/test-validate.mdx rename docs/migrate-to-ory/migrate/{user-identities => user-identities.mdx} (76%) diff --git a/docs/migrate-to-ory/auth0.mdx b/docs/migrate-to-ory/auth0.mdx index 5d8a3bd91..792adbb40 100644 --- a/docs/migrate-to-ory/auth0.mdx +++ b/docs/migrate-to-ory/auth0.mdx @@ -1,12 +1,10 @@ --- id: auth0 -title: Migrate users from Auth0 to Ory -sidebar_label: Migrate from Auth0 +title: Migrate user identities from Auth0 to Ory +sidebar_label: Migrate user identities from Auth0 to Ory slug: migrate-from-auth0 --- -# Migrate from Auth0 - This guide shows you how to migrate user accounts from Auth0 to Ory. The instructions in this document assume that your Auth0 setup includes a database connection and that the users whose accounts you migrate use emails and passwords as their login credentials. @@ -148,3 +146,5 @@ Follow these steps to import Auth0 users to Ory: ```shell ory list identities --project --workspace ``` +# FAQ +TODO: Living section for specific questions/answers that Sales get asked but which don't neatly fit within the Auth0 migration process. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/create-project b/docs/migrate-to-ory/migrate/create-project.mdx similarity index 85% rename from docs/migrate-to-ory/migrate/create-project rename to docs/migrate-to-ory/migrate/create-project.mdx index a0643ee97..218de1b76 100644 --- a/docs/migrate-to-ory/migrate/create-project +++ b/docs/migrate-to-ory/migrate/create-project.mdx @@ -1,18 +1,16 @@ --- id: create-project -title: Create project -sidebar_label: Create project +title: Create Ory Network project +sidebar_label: Create Ory Network project sidebar_position: 3 --- -## 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). +found [here](../../cli/ory-create-project). 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. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/define-id-schema b/docs/migrate-to-ory/migrate/define-id-schema.mdx similarity index 83% rename from docs/migrate-to-ory/migrate/define-id-schema rename to docs/migrate-to-ory/migrate/define-id-schema.mdx index 3e92a070b..a39c25131 100644 --- a/docs/migrate-to-ory/migrate/define-id-schema +++ b/docs/migrate-to-ory/migrate/define-id-schema.mdx @@ -1,18 +1,15 @@ --- -id: define-id-schema -title: Define identity schema -sidebar_label: Define identity schema +id: design-id-schema +title: Design identity schema +sidebar_label: Design identity schema sidebar_position: 3 --- - -## 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). +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. diff --git a/docs/migrate-to-ory/migrate/faq-migrate.mdx b/docs/migrate-to-ory/migrate/faq-migrate.mdx new file mode 100644 index 000000000..8c863e60c --- /dev/null +++ b/docs/migrate-to-ory/migrate/faq-migrate.mdx @@ -0,0 +1,8 @@ +--- +id: faq-migrate +title: Migrate FAQ +sidebar_label: Migrate FAQ +sidebar_position: 1 +--- + +TODO: Living section for specific questions/answers that Sales get asked but which don't neatly fit within the migration process. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/go-live b/docs/migrate-to-ory/migrate/go-live.mdx similarity index 99% rename from docs/migrate-to-ory/migrate/go-live rename to docs/migrate-to-ory/migrate/go-live.mdx index 8ccc24868..77bb34b05 100644 --- a/docs/migrate-to-ory/migrate/go-live +++ b/docs/migrate-to-ory/migrate/go-live.mdx @@ -5,9 +5,6 @@ sidebar_label: Go live sidebar_position: 2 --- - -# 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. diff --git a/docs/migrate-to-ory/migrate/index.mdx b/docs/migrate-to-ory/migrate/index.mdx index 3ff5bce2d..c3bb39af6 100644 --- a/docs/migrate-to-ory/migrate/index.mdx +++ b/docs/migrate-to-ory/migrate/index.mdx @@ -14,352 +14,18 @@ Ory Network's equivalent features. Why it matters: Not understanding your existing system’s behavior is the #1 cause of unexpected regressions during cutover. With Ory Network, you gain full control, and with it, the ability to shape your system’s flows exactly to your needs. -# Understand your current identity management system - -Below are example IAM scenarios supported by Ory Network. Use them to identify which scenario best fits your specific needs and -understand the unique requirements of each approach. Each scenario differs in complexity and implementation needs. Use these IAM -scenarios to help identify and map the authentication flows for your application. - -## Identify your IAM scenario -- CIAM -- B2B -- Workforce -- Agentic AI - -### CIAM (Customer Identity and Access Management) - -Your company sells products or services directly to individual consumers. - -#### Key IAM requirements -- Self-service registration, login, and profile management for end users -- Social login, multi-factor passwordless options, and robust account recovery -- Privacy compliance (GDPR, CCPA) -- High-scale performance for millions of users - -#### Ory Network features -- Identity management & authenitication (based on Ory Kratos) -- Authorization (based on Ory Hydra, optional for OAuth2/OIDC) - -### B2B (Business-to-Business) - -Your company sells products or services directly to other businesses rather than individual consumers. Your customers are organizations -that use these products or services to run their own operations. - -#### Key IAM requirements - -- Multi-organization user management -- SSO with SAML/OIDC providers -- Self-service partner onboarding -- Role-based permissions and API controls - -#### Ory Network features - -- Identity management & authenitication (based on Ory Kratos) -- Authorization and single sign-on (based on Ory Hydra/Ory Polis) -- Permissions (based on Ory Ketos) -- Zero-trust access proxy (based on Ory Oathkeeper) - -### Workforce (Business-to-Enterprise) - -Your company provides products or services. Your company wants to manage access for a single organization's extended workforce. You want to -consolidate employee user accounts and identities across multi-tenant brands, applications and systems. You need to seamlessly connect with -existing enterprise identity providers and other 3rd party systems and streamline user onboarding, offboarding, and permission management. - -#### Key IAM requirements -- Streamline onboarding/offboarding of employee, contractor, and temporary workers -- Role-based access aligned with organizational hierarchy -- HR system integration with flexible identity schemas -- Integrate with enterprise identity providers and third-party systems -- Time-bound permissions and role assignments -- Zero-trust security, MFA, and SSO for enterprise applications - -#### Ory Network features -- Identity management & authenitication (based on Ory Kratos) -- Authorization and single sign-on (based on Ory Hydra/Ory Polis) -- Permissions (based on Ory Ketos) -- Zero-trust access proxy (based on Ory Oathkeeper) -- Webhooks - -### Agentic AI - -Your company wants to enable AI applications to securely connect to data sources and tools. For example, servers that host resources and -clients (AI applications) to discover and use those resources. - -#### Key IAM requirements -- Standardized protocol that works across many tools and data sources -- Built-in authentication and access control - -#### Ory Network features -- Identity management & authenitication (based on Ory Kratos) -- Authorization (based on Ory Hydra) -- Permissions (based on Ory Ketos) -- Zero-trust access proxy (based on Ory Oathkeeper) - -## Map all authentication and identity flows in your application - -Build a complete picture of every authentication-related process in your system. Use your IAM scenario’s Key IAM requirements to help identify -authentication and identity flows. This ensures you don’t miss critical flows during migration. - -1. Identify all entry points where authentication occurs (e.g., web app login, mobile app sign-in, API tokens, social or enterprise sign-ins). -1. Create a comprehensive inventory of flows, for example: - - Registration / Sign-up - - Sign-in/Sign-out - - Multi-Factor Authentication (MFA) - - Password reset and account recovery - - Account linking (social, enterprise logins) - - User profile management - - Token refresh and session handling - - Recovery flows, consent screens, or partner-specific integrations -1. Visualize flows with diagrams (sequence diagrams or flow charts) to surface dependencies and hidden complexity. -1. Note where authentication interacts with other systems (databases, CRMs, partner apps, or external APIs). - - -### Map your existing IAM functionality to Ory Network’s equivalent capabilities -Using your list of authentication and identity flows, create a side-by-side table to map out existing functionality and Ory Network’s equivalent -capabilities. While the majority of the time you'll find your existing functionality neatly maps to Ory's capabilities, now is the best time to -identify when it does not. Some examples: - -- Not all vendors strickly comply with standards, whereas Ory does, so you might discover you need to -change how you implement functionality to be compliant. -- You might have a unique use case to solve that requires additional help from our support. - -Table 1: An example of mapping functionality - -| Existing Functionality | Ory Capabilities | -|---|---| -| JSON Web Tokens | [Ory Session cookies/tokens](https://www.ory.sh/docs/identities/session-to-jwt-cors)| - -At the end of this process you should have a living document with diagrams that capture: - -- All authentication and identity flows -- Your system's existing functionality and Ory Network's equivalent capabilites -- Any existing dependencies on external systems -- Edge cases requiring special handling - -This will serve as your blueprint for planning, designing, testing, and validating your migration. - -## 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). - -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](../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](../elements/index.mdx). - -## 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](../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 - . -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. +1. [Understand your current identity management system](migrate-to-ory) +1. [Migration strategies](migrate-strategies) +1. [Create Ory Network project](create-project) +1. [Design identity schema](design-id-schema) +1. [Frontend integration and UI migration](integrate-frontend) +1. [Backend integration](integrate-backend) +1. [Data migration strategies](migrate-identities) +1. [Test and validate](test-validate) +1. [Go live](go-live) ```mdx-code-block import Help from '@site/docs/_common/need-help.mdx' -``` +``` \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/integrate-backend b/docs/migrate-to-ory/migrate/integrate-backend.mdx similarity index 81% rename from docs/migrate-to-ory/migrate/integrate-backend rename to docs/migrate-to-ory/migrate/integrate-backend.mdx index d870a8c20..7e6364329 100644 --- a/docs/migrate-to-ory/migrate/integrate-backend +++ b/docs/migrate-to-ory/migrate/integrate-backend.mdx @@ -1,15 +1,13 @@ --- id: integrate-backend -title: Integrate backend -sidebar_label: Integrate backend +title: Backend integration +sidebar_label: Backend integration sidebar_position: 1 --- -# 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](../getting-started/integrate-auth/go#validate-and-login) to intercept API requests and validate the session by +[middleware](../../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. @@ -17,13 +15,13 @@ 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 +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) + 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 diff --git a/docs/migrate-to-ory/migrate/integrate-frontend b/docs/migrate-to-ory/migrate/integrate-frontend.mdx similarity index 79% rename from docs/migrate-to-ory/migrate/integrate-frontend rename to docs/migrate-to-ory/migrate/integrate-frontend.mdx index 29abd4091..cadc97678 100644 --- a/docs/migrate-to-ory/migrate/integrate-frontend +++ b/docs/migrate-to-ory/migrate/integrate-frontend.mdx @@ -1,12 +1,10 @@ --- id: integrate-frontend -title: Integrate frontend -sidebar_label: Integrate frontend +title: Frontend integration and UI migration +sidebar_label: Frontend integration and UI migration sidebar_position: 1 --- -# 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. @@ -19,15 +17,15 @@ subdomains. 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](../getting-started/overview) that cover the basics of developing with Ory for various +["protect a page with login" guides](../../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 +[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](../elements/index.mdx). \ No newline at end of file +Ory Elements can be found [here](../../elements/index.mdx). \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/migrate-strategies b/docs/migrate-to-ory/migrate/migrate-strategies.mdx similarity index 98% rename from docs/migrate-to-ory/migrate/migrate-strategies rename to docs/migrate-to-ory/migrate/migrate-strategies.mdx index 364e5363a..14aa1521e 100644 --- a/docs/migrate-to-ory/migrate/migrate-strategies +++ b/docs/migrate-to-ory/migrate/migrate-strategies.mdx @@ -5,8 +5,6 @@ sidebar_label: Migration strategies sidebar_position: 2 --- -## 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. @@ -100,7 +98,7 @@ projects. This involves creating a new project environment where the migration w 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). +found [here](../../cli/ory-create-project). 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. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/migrate-to-ory.mdx b/docs/migrate-to-ory/migrate/migrate-to-ory.mdx new file mode 100644 index 000000000..184bf94ae --- /dev/null +++ b/docs/migrate-to-ory/migrate/migrate-to-ory.mdx @@ -0,0 +1,130 @@ +--- +id: migrate-to-ory +title: Understand your current identity management system +sidebar_label: Understand your current identity management system +sidebar_position: 1 +--- +# Understand your current identity management system + +Below are example IAM scenarios supported by Ory Network. Use them to identify which scenario best fits your specific needs and +understand the unique requirements of each approach. Each scenario differs in complexity and implementation needs. Use these IAM +scenarios to help identify and map the authentication flows for your application. + +## Identify your IAM scenario +- [CIAM](#ciam-customer-identity-and-access-management) +- [B2B](#b2b-business-to-business) +- [Workforce](#workforce-business-to-enterprise) +- [Agentic AI](#agentic-ai) + + +### CIAM (Customer Identity and Access Management) + +Your company sells products or services directly to individual consumers. + +#### Key IAM requirements +- Self-service registration, login, and profile management for end users +- Social login, multi-factor passwordless options, and robust account recovery +- Privacy compliance (GDPR, CCPA) +- High-scale performance for millions of users + +#### Ory Network features +- Identity management & authenitication (based on Ory Kratos) +- Authorization (based on Ory Hydra, optional for OAuth2/OIDC) + +### B2B (Business-to-Business) + +Your company sells products or services directly to other businesses rather than individual consumers. Your customers are organizations +that use these products or services to run their own operations. + +#### Key IAM requirements + +- Multi-organization user management +- SSO with SAML/OIDC providers +- Self-service partner onboarding +- Role-based permissions and API controls + +#### Ory Network features + +- Identity management & authenitication (based on Ory Kratos) +- Authorization and single sign-on (based on Ory Hydra/Ory Polis) +- Permissions (based on Ory Ketos) +- Zero-trust access proxy (based on Ory Oathkeeper) + +### Workforce (Business-to-Enterprise) + +Your company provides products or services. Your company wants to manage access for a single organization's extended workforce. You want to +consolidate employee user accounts and identities across multi-tenant brands, applications and systems. You need to seamlessly connect with +existing enterprise identity providers and other 3rd party systems and streamline user onboarding, offboarding, and permission management. + +#### Key IAM requirements +- Streamline onboarding/offboarding of employee, contractor, and temporary workers +- Role-based access aligned with organizational hierarchy +- HR system integration with flexible identity schemas +- Integrate with enterprise identity providers and third-party systems +- Time-bound permissions and role assignments +- Zero-trust security, MFA, and SSO for enterprise applications + +#### Ory Network features +- Identity management & authenitication (based on Ory Kratos) +- Authorization and single sign-on (based on Ory Hydra/Ory Polis) +- Permissions (based on Ory Ketos) +- Zero-trust access proxy (based on Ory Oathkeeper) +- Webhooks + +### Agentic AI + +Your company wants to enable AI applications to securely connect to data sources and tools. For example, servers that host resources and +clients (AI applications) to discover and use those resources. + +#### Key IAM requirements +- Standardized protocol that works across many tools and data sources +- Built-in authentication and access control + +#### Ory Network features +- Identity management & authenitication (based on Ory Kratos) +- Authorization (based on Ory Hydra) +- Permissions (based on Ory Ketos) +- Zero-trust access proxy (based on Ory Oathkeeper) + +## Map all authentication and identity flows in your application + +Build a complete picture of every authentication-related process in your system. Use your IAM scenario’s Key IAM requirements to help identify +authentication and identity flows. This ensures you don’t miss critical flows during migration. + +1. Identify all entry points where authentication occurs (e.g., web app login, mobile app sign-in, API tokens, social or enterprise sign-ins). +1. Create a comprehensive inventory of flows, for example: + - Registration / Sign-up + - Sign-in/Sign-out + - Multi-Factor Authentication (MFA) + - Password reset and account recovery + - Account linking (social, enterprise logins) + - User profile management + - Token refresh and session handling + - Recovery flows, consent screens, or partner-specific integrations +1. Visualize flows with diagrams (sequence diagrams or flow charts) to surface dependencies and hidden complexity. +1. Note where authentication interacts with other systems (databases, CRMs, partner apps, or external APIs). + + +## Map existing IAM functionality to Ory Network’s equivalent capabilities +Using your list of authentication and identity flows, create a side-by-side table to map out existing functionality and Ory Network’s equivalent +capabilities. While the majority of the time you'll find your existing functionality neatly maps to Ory's capabilities, now is the best time to +identify when it does not. Some examples: + +- Not all vendors strickly comply with standards, whereas Ory does, so you might discover you need to +change how you implement functionality to be compliant. +- You might have a unique use case to solve that requires additional help from our support. + +Table 1: An example of mapping functionality + +| Existing Functionality | Ory Capabilities | +|---|---| +| JSON Web Tokens | [Ory Session cookies/tokens](https://www.ory.sh/docs/identities/session-to-jwt-cors)| + +At the end of this process you should have a living document with diagrams that capture: + +- All authentication and identity flows +- Your system's existing functionality and Ory Network's equivalent capabilites +- Any existing dependencies on external systems +- Edge cases requiring special handling + +This will serve as your blueprint for planning, designing, testing, and validating your migration. diff --git a/docs/migrate-to-ory/migrate/test-validate.mdx b/docs/migrate-to-ory/migrate/test-validate.mdx new file mode 100644 index 000000000..6f6d1298e --- /dev/null +++ b/docs/migrate-to-ory/migrate/test-validate.mdx @@ -0,0 +1,9 @@ +--- +id: test-validate +title: Test and validate +sidebar_label: Test and validate +sidebar_position: 1 +--- + + +TBD \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/user-identities b/docs/migrate-to-ory/migrate/user-identities.mdx similarity index 76% rename from docs/migrate-to-ory/migrate/user-identities rename to docs/migrate-to-ory/migrate/user-identities.mdx index dbc8801c6..a35ea1f4b 100644 --- a/docs/migrate-to-ory/migrate/user-identities +++ b/docs/migrate-to-ory/migrate/user-identities.mdx @@ -1,30 +1,31 @@ --- -id: user-identities -title: Migrate user identities -sidebar_label: Migrate user identities +id: migrate-identities +title: Data migration strategies +sidebar_label: Data migration strategies sidebar_position: 3 --- +With authentication now set up on your front end and back end, the next step is to prepare your existing user identities for +migration. ## Get existing user identities ready for migration -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 +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 +[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 ](../../kratos/manage-identities/25_import-user-accounts-identities.mdx) documentation. ## Import user identities -You can use the [create identity API](../reference/api#tag/identity/operation/batchPatchIdentities) to bulk import identities into +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. +[Import identities ](../../kratos/manage-identities/25_import-user-accounts-identities.mdx) documentation. ### Phased migration for active sessions diff --git a/src/sidebar.ts b/src/sidebar.ts index 5ebf07998..cd83fa0ea 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -184,7 +184,6 @@ const quickstart: SidebarItemsConfig = [ type: "doc", id: "getting-started/overview", }, - items: [ { type: "autogenerated", @@ -197,19 +196,27 @@ const quickstart: SidebarItemsConfig = [ label: "Migrate to Ory", collapsed: false, collapsible: false, - link: { - type: "doc", - id: "migrate-to-ory/migrate/index", - }, items: [ - "migrate-to-ory/migrate/index", - "migrate-to-ory/migrate/migrate-strategies", - "migrate-to-ory/migrate/create-project", - "migrate-to-ory/migrate/define-id-schema", - "migrate-to-ory/migrate/integrate-frontend", - "migrate-to-ory/migrate/integrate-backend", - "migrate-to-ory/migrate/user-identities", - "migrate-to-ory/migrate/go-live", + { + type: "category", + label: "Migrate to Ory Network", + link: { + type: "doc", + id: "migrate-to-ory/migrate/index", + }, + items: [ + "migrate-to-ory/migrate/migrate-to-ory", + "migrate-to-ory/migrate/migrate-strategies", + "migrate-to-ory/migrate/create-project", + "migrate-to-ory/migrate/design-id-schema", + "migrate-to-ory/migrate/integrate-frontend", + "migrate-to-ory/migrate/integrate-backend", + "migrate-to-ory/migrate/migrate-identities", + "migrate-to-ory/migrate/test-validate", + "migrate-to-ory/migrate/go-live", + "migrate-to-ory/migrate/faq-migrate", + ], + }, "migrate-to-ory/auth0", ], }, From 67f2ad3dacad4edc8b562962a1d2fd4074ec268c Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Thu, 9 Oct 2025 21:52:28 -0700 Subject: [PATCH 3/5] chore: migration guide updates --- .../migrate-to-ory/migrate/create-project.mdx | 4 +- ...ine-id-schema.mdx => design-id-schema.mdx} | 4 +- docs/migrate-to-ory/migrate/faq-migrate.mdx | 4 +- docs/migrate-to-ory/migrate/index.mdx | 14 ++--- .../migrate/integrate-backend.mdx | 4 +- .../migrate/integrate-frontend.mdx | 4 +- docs/migrate-to-ory/migrate/map-to-orycap.mdx | 20 ++++++ ...-identities.mdx => migrate-identities.mdx} | 6 +- .../migrate/migrate-strategies.mdx | 16 +---- .../migrate-to-ory/migrate/migrate-to-ory.mdx | 62 ++++--------------- docs/migrate-to-ory/migrate/test-validate.mdx | 26 +++++++- src/sidebar.ts | 1 + 12 files changed, 78 insertions(+), 87 deletions(-) rename docs/migrate-to-ory/migrate/{define-id-schema.mdx => design-id-schema.mdx} (93%) create mode 100644 docs/migrate-to-ory/migrate/map-to-orycap.mdx rename docs/migrate-to-ory/migrate/{user-identities.mdx => migrate-identities.mdx} (93%) diff --git a/docs/migrate-to-ory/migrate/create-project.mdx b/docs/migrate-to-ory/migrate/create-project.mdx index 218de1b76..81b5708f3 100644 --- a/docs/migrate-to-ory/migrate/create-project.mdx +++ b/docs/migrate-to-ory/migrate/create-project.mdx @@ -1,7 +1,7 @@ --- id: create-project -title: Create Ory Network project -sidebar_label: Create Ory Network project +title: Create an Ory Network project +sidebar_label: Create an Ory Network project sidebar_position: 3 --- diff --git a/docs/migrate-to-ory/migrate/define-id-schema.mdx b/docs/migrate-to-ory/migrate/design-id-schema.mdx similarity index 93% rename from docs/migrate-to-ory/migrate/define-id-schema.mdx rename to docs/migrate-to-ory/migrate/design-id-schema.mdx index a39c25131..9f898b3b0 100644 --- a/docs/migrate-to-ory/migrate/define-id-schema.mdx +++ b/docs/migrate-to-ory/migrate/design-id-schema.mdx @@ -1,7 +1,7 @@ --- id: design-id-schema -title: Design identity schema -sidebar_label: Design identity schema +title: Design your identity schema +sidebar_label: Design your identity schema sidebar_position: 3 --- diff --git a/docs/migrate-to-ory/migrate/faq-migrate.mdx b/docs/migrate-to-ory/migrate/faq-migrate.mdx index 8c863e60c..e85dd4587 100644 --- a/docs/migrate-to-ory/migrate/faq-migrate.mdx +++ b/docs/migrate-to-ory/migrate/faq-migrate.mdx @@ -1,7 +1,7 @@ --- id: faq-migrate -title: Migrate FAQ -sidebar_label: Migrate FAQ +title: Migration FAQ +sidebar_label: Migration FAQ sidebar_position: 1 --- diff --git a/docs/migrate-to-ory/migrate/index.mdx b/docs/migrate-to-ory/migrate/index.mdx index c3bb39af6..8b72b41e7 100644 --- a/docs/migrate-to-ory/migrate/index.mdx +++ b/docs/migrate-to-ory/migrate/index.mdx @@ -15,13 +15,13 @@ Why it matters: Not understanding your existing system’s behavior is the #1 ca Ory Network, you gain full control, and with it, the ability to shape your system’s flows exactly to your needs. 1. [Understand your current identity management system](migrate-to-ory) -1. [Migration strategies](migrate-strategies) -1. [Create Ory Network project](create-project) -1. [Design identity schema](design-id-schema) -1. [Frontend integration and UI migration](integrate-frontend) -1. [Backend integration](integrate-backend) -1. [Data migration strategies](migrate-identities) -1. [Test and validate](test-validate) +1. [Choose your migration strategy](migrate-strategies) +1. [Create an Ory Network project](create-project) +1. [Design your identity schema](design-id-schema) +1. [Integrate your frontend and UI](integrate-frontend) +1. [Integrate your backend](integrate-backend) +1. [Migrate your existing identities](migrate-identities) +1. [Test and validate your integration](test-validate) 1. [Go live](go-live) ```mdx-code-block diff --git a/docs/migrate-to-ory/migrate/integrate-backend.mdx b/docs/migrate-to-ory/migrate/integrate-backend.mdx index 7e6364329..a29698aa9 100644 --- a/docs/migrate-to-ory/migrate/integrate-backend.mdx +++ b/docs/migrate-to-ory/migrate/integrate-backend.mdx @@ -1,7 +1,7 @@ --- id: integrate-backend -title: Backend integration -sidebar_label: Backend integration +title: Integrate your backend +sidebar_label: Integrate your backend sidebar_position: 1 --- diff --git a/docs/migrate-to-ory/migrate/integrate-frontend.mdx b/docs/migrate-to-ory/migrate/integrate-frontend.mdx index cadc97678..bbac68ac0 100644 --- a/docs/migrate-to-ory/migrate/integrate-frontend.mdx +++ b/docs/migrate-to-ory/migrate/integrate-frontend.mdx @@ -1,7 +1,7 @@ --- id: integrate-frontend -title: Frontend integration and UI migration -sidebar_label: Frontend integration and UI migration +title: Integrate your frontend and UI +sidebar_label: Integrate your frontend and UI sidebar_position: 1 --- diff --git a/docs/migrate-to-ory/migrate/map-to-orycap.mdx b/docs/migrate-to-ory/migrate/map-to-orycap.mdx new file mode 100644 index 000000000..5130e6c13 --- /dev/null +++ b/docs/migrate-to-ory/migrate/map-to-orycap.mdx @@ -0,0 +1,20 @@ +--- +id: map-to-orycap +title: Map your existing functionality to Ory Network capabilities +sidebar_label: Map your existing functionality to Ory Network capabilities +sidebar_position: 1 +--- + +Using your list of identity flows, create a side-by-side table to map existing functionality to Ory Network’s equivalent +capabilities. While the majority of the time you'll find your existing functionality neatly maps to Ory's capabilities, now is the best time to +identify when it does not. Some examples: + +- Not all vendors strickly comply with standards, whereas Ory does, so you might discover you need to +change how you implement functionality to be compliant. +- You might have a unique use case to solve that requires additional help from our support. + +Table 1: An example of mapping functionality + +| Existing Functionality | Ory Capabilities | +|---|---| +| JSON Web Tokens | [Ory Session cookies/tokens](https://www.ory.sh/docs/identities/session-to-jwt-cors)| diff --git a/docs/migrate-to-ory/migrate/user-identities.mdx b/docs/migrate-to-ory/migrate/migrate-identities.mdx similarity index 93% rename from docs/migrate-to-ory/migrate/user-identities.mdx rename to docs/migrate-to-ory/migrate/migrate-identities.mdx index a35ea1f4b..1efd93298 100644 --- a/docs/migrate-to-ory/migrate/user-identities.mdx +++ b/docs/migrate-to-ory/migrate/migrate-identities.mdx @@ -1,7 +1,7 @@ --- id: migrate-identities -title: Data migration strategies -sidebar_label: Data migration strategies +title: Migrate your existing identities +sidebar_label: Migrate your existing identities sidebar_position: 3 --- With authentication now set up on your front end and back end, the next step is to prepare your existing user identities for @@ -19,6 +19,8 @@ supported or if you can't get the hashed passwords from your current authenticat 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. +- For migrating from Auth0s, see [Migrate user identities from Auth0 to Ory](../migrate-from-auth0) + ## Import user identities You can use the [create identity API] (../../reference/api#tag/identity/operation/batchPatchIdentities) to bulk import identities into diff --git a/docs/migrate-to-ory/migrate/migrate-strategies.mdx b/docs/migrate-to-ory/migrate/migrate-strategies.mdx index 14aa1521e..ad7c113f1 100644 --- a/docs/migrate-to-ory/migrate/migrate-strategies.mdx +++ b/docs/migrate-to-ory/migrate/migrate-strategies.mdx @@ -1,7 +1,7 @@ --- id: migrate-strategies -title: Migration strategies -sidebar_label: Migration strategies +title: Choose your migration strategy +sidebar_label: Choose your migration strategy sidebar_position: 2 --- @@ -90,15 +90,3 @@ 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). - -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. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/migrate-to-ory.mdx b/docs/migrate-to-ory/migrate/migrate-to-ory.mdx index 184bf94ae..9ca9aff59 100644 --- a/docs/migrate-to-ory/migrate/migrate-to-ory.mdx +++ b/docs/migrate-to-ory/migrate/migrate-to-ory.mdx @@ -8,7 +8,7 @@ sidebar_position: 1 Below are example IAM scenarios supported by Ory Network. Use them to identify which scenario best fits your specific needs and understand the unique requirements of each approach. Each scenario differs in complexity and implementation needs. Use these IAM -scenarios to help identify and map the authentication flows for your application. +scenarios to map the identity flows for your application. ## Identify your IAM scenario - [CIAM](#ciam-customer-identity-and-access-management) @@ -27,10 +27,6 @@ Your company sells products or services directly to individual consumers. - Privacy compliance (GDPR, CCPA) - High-scale performance for millions of users -#### Ory Network features -- Identity management & authenitication (based on Ory Kratos) -- Authorization (based on Ory Hydra, optional for OAuth2/OIDC) - ### B2B (Business-to-Business) Your company sells products or services directly to other businesses rather than individual consumers. Your customers are organizations @@ -43,13 +39,6 @@ that use these products or services to run their own operations. - Self-service partner onboarding - Role-based permissions and API controls -#### Ory Network features - -- Identity management & authenitication (based on Ory Kratos) -- Authorization and single sign-on (based on Ory Hydra/Ory Polis) -- Permissions (based on Ory Ketos) -- Zero-trust access proxy (based on Ory Oathkeeper) - ### Workforce (Business-to-Enterprise) Your company provides products or services. Your company wants to manage access for a single organization's extended workforce. You want to @@ -64,13 +53,6 @@ existing enterprise identity providers and other 3rd party systems and streamlin - Time-bound permissions and role assignments - Zero-trust security, MFA, and SSO for enterprise applications -#### Ory Network features -- Identity management & authenitication (based on Ory Kratos) -- Authorization and single sign-on (based on Ory Hydra/Ory Polis) -- Permissions (based on Ory Ketos) -- Zero-trust access proxy (based on Ory Oathkeeper) -- Webhooks - ### Agentic AI Your company wants to enable AI applications to securely connect to data sources and tools. For example, servers that host resources and @@ -80,50 +62,28 @@ clients (AI applications) to discover and use those resources. - Standardized protocol that works across many tools and data sources - Built-in authentication and access control -#### Ory Network features -- Identity management & authenitication (based on Ory Kratos) -- Authorization (based on Ory Hydra) -- Permissions (based on Ory Ketos) -- Zero-trust access proxy (based on Ory Oathkeeper) - -## Map all authentication and identity flows in your application +## Map all identity flows in your application -Build a complete picture of every authentication-related process in your system. Use your IAM scenario’s Key IAM requirements to help identify -authentication and identity flows. This ensures you don’t miss critical flows during migration. +Build a complete picture of every identity-related process in your system. Use your IAM scenario’s Key IAM requirements to identify +these flows. This ensures you don’t miss critical flows during migration. -1. Identify all entry points where authentication occurs (e.g., web app login, mobile app sign-in, API tokens, social or enterprise sign-ins). +1. Identify all entry points where an identity-related process occurs (e.g., web app login, mobile app sign-in, API tokens, social or enterprise sign-ins). 1. Create a comprehensive inventory of flows, for example: - - Registration / Sign-up - - Sign-in/Sign-out + - Registration/sign-up + - Sign-in/sign-out - Multi-Factor Authentication (MFA) - Password reset and account recovery - Account linking (social, enterprise logins) - User profile management - Token refresh and session handling - Recovery flows, consent screens, or partner-specific integrations -1. Visualize flows with diagrams (sequence diagrams or flow charts) to surface dependencies and hidden complexity. -1. Note where authentication interacts with other systems (databases, CRMs, partner apps, or external APIs). - - -## Map existing IAM functionality to Ory Network’s equivalent capabilities -Using your list of authentication and identity flows, create a side-by-side table to map out existing functionality and Ory Network’s equivalent -capabilities. While the majority of the time you'll find your existing functionality neatly maps to Ory's capabilities, now is the best time to -identify when it does not. Some examples: - -- Not all vendors strickly comply with standards, whereas Ory does, so you might discover you need to -change how you implement functionality to be compliant. -- You might have a unique use case to solve that requires additional help from our support. - -Table 1: An example of mapping functionality - -| Existing Functionality | Ory Capabilities | -|---|---| -| JSON Web Tokens | [Ory Session cookies/tokens](https://www.ory.sh/docs/identities/session-to-jwt-cors)| +1. Create flow diagrams (sequence diagrams or flow charts) to surface dependencies and hidden complexity. +1. Note where identity (authentication and authorization) interacts with other systems (databases, CRMs, partner apps, or external APIs). At the end of this process you should have a living document with diagrams that capture: -- All authentication and identity flows -- Your system's existing functionality and Ory Network's equivalent capabilites +- All identity (authentication and authorization) flows +- Your system's existing functionality - Any existing dependencies on external systems - Edge cases requiring special handling diff --git a/docs/migrate-to-ory/migrate/test-validate.mdx b/docs/migrate-to-ory/migrate/test-validate.mdx index 6f6d1298e..db33da9b0 100644 --- a/docs/migrate-to-ory/migrate/test-validate.mdx +++ b/docs/migrate-to-ory/migrate/test-validate.mdx @@ -1,9 +1,29 @@ --- id: test-validate -title: Test and validate -sidebar_label: Test and validate +title: Test and validate your integration +sidebar_label: Test and validate your integration sidebar_position: 1 --- +Before going live with your Ory Network integration, thorough testing across multiple environments is essential +to ensure your authentication system works securely and reliably. You should test progressively through development, +staging, and production environments, validating that configurations, custom domains, and integrations work correctly +at each stage. +Create a comprehensive list of testing requirements. For example: -TBD \ No newline at end of file +- Authentication Flows: Login, registration, password reset, account recovery +- Session Management: Creation, validation, expiration, security +- Data Integrity: User profiles, metadata synchronization, permissions +- API Functionality: All protected routes, authorization checks +- User Interface: Forms, redirects, error handling, responsive design +- Performance: Response times, concurrent user handling, load capacity +- Security: CSRF protection, session security, data encryption + +## Migration Validation Process +Implement systematic validation to ensure migration completeness, data accuracy, and functional parity with existing systems. +Compare user counts between systems, validate authentication flows for sample users, and verify all business logic continues +to function correctly. + +## User Acceptance Testing +Conduct thorough user acceptance testing with representative user groups to ensure the migrated system meets usability +requirements and maintains expected functionality. \ No newline at end of file diff --git a/src/sidebar.ts b/src/sidebar.ts index cd83fa0ea..c0d0f6899 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -206,6 +206,7 @@ const quickstart: SidebarItemsConfig = [ }, items: [ "migrate-to-ory/migrate/migrate-to-ory", + "migrate-to-ory/migrate/map-to-orycap", "migrate-to-ory/migrate/migrate-strategies", "migrate-to-ory/migrate/create-project", "migrate-to-ory/migrate/design-id-schema", From 0ecca7d98c78232c6b4249290ed8a8f8557f3c30 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Tue, 14 Oct 2025 08:04:39 -0700 Subject: [PATCH 4/5] chore: edits to migration guide --- .../migrate-to-ory/migrate/create-project.mdx | 4 +- docs/migrate-to-ory/migrate/index.mdx | 15 +++-- .../migrate/integrate-frontend.mdx | 4 +- docs/migrate-to-ory/migrate/map-to-orycap.mdx | 2 +- .../migrate/migrate-strategies.mdx | 62 ++++++++++++------- .../migrate-to-ory/migrate/migrate-to-ory.mdx | 10 +-- 6 files changed, 58 insertions(+), 39 deletions(-) diff --git a/docs/migrate-to-ory/migrate/create-project.mdx b/docs/migrate-to-ory/migrate/create-project.mdx index 81b5708f3..7d8853f87 100644 --- a/docs/migrate-to-ory/migrate/create-project.mdx +++ b/docs/migrate-to-ory/migrate/create-project.mdx @@ -6,11 +6,11 @@ sidebar_position: 3 --- 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. +projects in a development, staging, and production environment. 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). -Before migrating your production environment, perform the migration in a development or staging environment. This allows you to +Before migrating to 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. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/index.mdx b/docs/migrate-to-ory/migrate/index.mdx index 8b72b41e7..3712f9eac 100644 --- a/docs/migrate-to-ory/migrate/index.mdx +++ b/docs/migrate-to-ory/migrate/index.mdx @@ -8,17 +8,22 @@ sidebar_position: 1 # Migrate to Ory Network Before you can migrate smoothly, you need a complete picture of how your identity management system works today. This step ensures -nothing gets missed — from everyday login flows to rare edge cases — and sets the foundation for mapping existing features to -Ory Network's equivalent features. +nothing gets missed — from everyday login flows to rare edge cases — and sets the foundation for mapping existing functionality to +Ory Network's equivalent capabilities. -Why it matters: Not understanding your existing system’s behavior is the #1 cause of unexpected regressions during cutover. With -Ory Network, you gain full control, and with it, the ability to shape your system’s flows exactly to your needs. +:::info Why it matters + +Not understanding your existing system’s behavior is the #1 cause of unexpected regressions during cutover. + +::: + +With Ory Network, you gain full control, and with it, the ability to shape your system’s flows exactly to your needs. 1. [Understand your current identity management system](migrate-to-ory) 1. [Choose your migration strategy](migrate-strategies) 1. [Create an Ory Network project](create-project) 1. [Design your identity schema](design-id-schema) -1. [Integrate your frontend and UI](integrate-frontend) +1. [Integrate your frontend](integrate-frontend) 1. [Integrate your backend](integrate-backend) 1. [Migrate your existing identities](migrate-identities) 1. [Test and validate your integration](test-validate) diff --git a/docs/migrate-to-ory/migrate/integrate-frontend.mdx b/docs/migrate-to-ory/migrate/integrate-frontend.mdx index bbac68ac0..41a44ce6d 100644 --- a/docs/migrate-to-ory/migrate/integrate-frontend.mdx +++ b/docs/migrate-to-ory/migrate/integrate-frontend.mdx @@ -1,7 +1,7 @@ --- id: integrate-frontend -title: Integrate your frontend and UI -sidebar_label: Integrate your frontend and UI +title: Integrate your frontend +sidebar_label: Integrate your frontend sidebar_position: 1 --- diff --git a/docs/migrate-to-ory/migrate/map-to-orycap.mdx b/docs/migrate-to-ory/migrate/map-to-orycap.mdx index 5130e6c13..f8bf736d0 100644 --- a/docs/migrate-to-ory/migrate/map-to-orycap.mdx +++ b/docs/migrate-to-ory/migrate/map-to-orycap.mdx @@ -5,7 +5,7 @@ sidebar_label: Map your existing functionality to Ory Network capabilities sidebar_position: 1 --- -Using your list of identity flows, create a side-by-side table to map existing functionality to Ory Network’s equivalent +Using your list of identity-related flows, create a side-by-side table to map existing functionality to Ory Network’s equivalent capabilities. While the majority of the time you'll find your existing functionality neatly maps to Ory's capabilities, now is the best time to identify when it does not. Some examples: diff --git a/docs/migrate-to-ory/migrate/migrate-strategies.mdx b/docs/migrate-to-ory/migrate/migrate-strategies.mdx index ad7c113f1..ead96cb7e 100644 --- a/docs/migrate-to-ory/migrate/migrate-strategies.mdx +++ b/docs/migrate-to-ory/migrate/migrate-strategies.mdx @@ -5,22 +5,39 @@ sidebar_label: Choose your migration strategy sidebar_position: 2 --- -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. +When migrating user data, there are two main steps in the migration process; the first is a backfill, in which existing data +is transferred from the old system to the new system, and the second is a cutover or "go-live event", in which users authenticate with the new +system for the first time. There are three main migration strategies that consider these steps as well as when you turn-off your old system. -- **Big bang** - Migrate everyone at once. +The three main migration strategies are: + +- **Big bang** - Migrate all users 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. +Each migration strategy has its strengths and challenges. Which migration strategy you choose depends on factors such as the +complexity of your system, the number of users, and your organization's tolerance for risk and downtime. + +:::info + +While your choice of migration strategy is mostly influenced by user data, if you have a complex system or are risk adverse, you might +choose your migration strategy based on its ability to breakdown the migration into a series of migrations. This lets you test your +processes in production by migrating less critical, sets of users or applications first and learning lessons to improve the migration process. + +::: ### 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. +#### Recommendation +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 + #### Advantages of big bang migration - Simplicity: Since there is only one "go-live", the migration process is easier to manage and plan. @@ -34,18 +51,20 @@ scheduled, where all users start using the new system simultaneously. - 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. +#### Recommendation +A stepwise migration is the best choice in most cases, especially when: + +- You manage multiple apps/segments of users with different underlying auth systems +- You need to keep active sessions live during the migration +- Downtime should be mostly avoided +- You have some time to migrate + #### Advantages of stepwise migration - Reduced risk: By migrating in phases, issues are isolated to specific apps or user segments. @@ -59,18 +78,19 @@ of users. - 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. +#### Recommendation +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 + #### 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. @@ -84,9 +104,3 @@ application "go-live" and subsequent user-specific cutovers during login. - 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 diff --git a/docs/migrate-to-ory/migrate/migrate-to-ory.mdx b/docs/migrate-to-ory/migrate/migrate-to-ory.mdx index 9ca9aff59..4b62ba809 100644 --- a/docs/migrate-to-ory/migrate/migrate-to-ory.mdx +++ b/docs/migrate-to-ory/migrate/migrate-to-ory.mdx @@ -6,7 +6,7 @@ sidebar_position: 1 --- # Understand your current identity management system -Below are example IAM scenarios supported by Ory Network. Use them to identify which scenario best fits your specific needs and +Below are example IAM scenarios supported by Ory Network. Use them to identify which scenario best fits your specific IAM needs and understand the unique requirements of each approach. Each scenario differs in complexity and implementation needs. Use these IAM scenarios to map the identity flows for your application. @@ -43,7 +43,7 @@ that use these products or services to run their own operations. Your company provides products or services. Your company wants to manage access for a single organization's extended workforce. You want to consolidate employee user accounts and identities across multi-tenant brands, applications and systems. You need to seamlessly connect with -existing enterprise identity providers and other 3rd party systems and streamline user onboarding, offboarding, and permission management. +existing enterprise identity providers and other 3rd party systems, and streamline user onboarding, offboarding, and permission management. #### Key IAM requirements - Streamline onboarding/offboarding of employee, contractor, and temporary workers @@ -56,7 +56,7 @@ existing enterprise identity providers and other 3rd party systems and streamlin ### Agentic AI Your company wants to enable AI applications to securely connect to data sources and tools. For example, servers that host resources and -clients (AI applications) to discover and use those resources. +clients (AI applications) that discover and use those resources. #### Key IAM requirements - Standardized protocol that works across many tools and data sources @@ -78,11 +78,11 @@ these flows. This ensures you don’t miss critical flows during migration. - Token refresh and session handling - Recovery flows, consent screens, or partner-specific integrations 1. Create flow diagrams (sequence diagrams or flow charts) to surface dependencies and hidden complexity. -1. Note where identity (authentication and authorization) interacts with other systems (databases, CRMs, partner apps, or external APIs). +1. Note where identity-related (authentication and authorization) processes interact with other systems (databases, CRMs, partner apps, or external APIs). At the end of this process you should have a living document with diagrams that capture: -- All identity (authentication and authorization) flows +- All identity-related (authentication and authorization) flows - Your system's existing functionality - Any existing dependencies on external systems - Edge cases requiring special handling From a0ef5d132b70dcb22b38b5ed5cbc170afa20cfe3 Mon Sep 17 00:00:00 2001 From: unatasha8 Date: Thu, 23 Oct 2025 22:37:56 -0700 Subject: [PATCH 5/5] docs: updated migration strategies and identity schema content --- .../migrate/design-id-schema.mdx | 41 +++-- docs/migrate-to-ory/migrate/index.mdx | 107 +++++++++++-- .../migrate/migrate-identities.mdx | 44 +++-- .../migrate/migrate-strategies.mdx | 150 ++++++++++-------- .../migrate-to-ory/migrate/migrate-to-ory.mdx | 6 +- src/sidebar.ts | 60 +++++-- 6 files changed, 270 insertions(+), 138 deletions(-) diff --git a/docs/migrate-to-ory/migrate/design-id-schema.mdx b/docs/migrate-to-ory/migrate/design-id-schema.mdx index 9f898b3b0..9000ecbf1 100644 --- a/docs/migrate-to-ory/migrate/design-id-schema.mdx +++ b/docs/migrate-to-ory/migrate/design-id-schema.mdx @@ -5,14 +5,33 @@ sidebar_label: Design your identity schema sidebar_position: 3 --- -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. \ No newline at end of file +To align identities from your current system with Ory, you can customize the identity schema to meet your specific requirements. +This ability to customize the identity schema means you can enhance and improve your old identity schema during the migration process. + +The identity schema, which implements the JSON Schema standard, defines the types of data the system can store for users—such as +names, email addresses, phone numbers, or birthdays—and controls business logic by specifying which fields serve as login +identifiers and which are used for verification or recovery. + +Identities have two main data types: traits (attributes that users can modify themselves, such as username or email address) +and metadata (attributes defined by system admins that can only be updated through admin APIs. Metadata is useful for storing +information like subscription status, legacy user IDs, or basic roles). Metadata comes in two forms: public (visible to +users via session endpoints) and admin (only accessible through admin APIs). + +## Best practices for identity schema design: + +### Do: + +- Use the identity schema for basic profile information that's used across your system, including usernames, email addresses, +phone numbers, first names, and last names +- Store authentication-related data like login identifiers and verification addresses in traits +- Use metadata fields for system-managed information like legacy user IDs, subscription status, or basic roles + +### Don't: + +- Store sensitive internal data or information that should be obfuscated from users in the identity schema, since users can +see traits and other data (except credentials) using the `/sessions/whoami` endpoint +- Store business logic or application-specific data like credit card information, shipping addresses, shopping cart items, or +detailed user preferences—keep this in your application database instead + +Ory provides preset schemas to help you get started quickly. For detailed guidance on customizing schemas, see the +[identity schemas](../../kratos/manage-identities/identity-schema) documentation. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/index.mdx b/docs/migrate-to-ory/migrate/index.mdx index 3712f9eac..62e49fd96 100644 --- a/docs/migrate-to-ory/migrate/index.mdx +++ b/docs/migrate-to-ory/migrate/index.mdx @@ -1,11 +1,10 @@ --- id: index -title: Migrate to Ory Network -sidebar_label: Migrate to Ory Network +title: Understand your current IAM system +sidebar_label: Understand your current IAM system sidebar_position: 1 --- - -# Migrate to Ory Network +# Understand your current IAM system Before you can migrate smoothly, you need a complete picture of how your identity management system works today. This step ensures nothing gets missed — from everyday login flows to rare edge cases — and sets the foundation for mapping existing functionality to @@ -13,21 +12,97 @@ Ory Network's equivalent capabilities. :::info Why it matters -Not understanding your existing system’s behavior is the #1 cause of unexpected regressions during cutover. +Not understanding your existing system’s behavior is the #1 cause of unexpected regressions during cutover. With Ory Network, you +gain full control, and with it, the ability to shape your system’s flows exactly to your needs. ::: -With Ory Network, you gain full control, and with it, the ability to shape your system’s flows exactly to your needs. - -1. [Understand your current identity management system](migrate-to-ory) -1. [Choose your migration strategy](migrate-strategies) -1. [Create an Ory Network project](create-project) -1. [Design your identity schema](design-id-schema) -1. [Integrate your frontend](integrate-frontend) -1. [Integrate your backend](integrate-backend) -1. [Migrate your existing identities](migrate-identities) -1. [Test and validate your integration](test-validate) -1. [Go live](go-live) +Below are example IAM scenarios supported by Ory Network. Use them to identify which scenario best fits your specific IAM needs and +understand the unique requirements of each approach. Each scenario differs in complexity and implementation needs. Use these IAM +scenarios to map the identity flows for your application. + +## Identify your IAM scenario +- [CIAM](#ciam-customer-identity-and-access-management) +- [B2B](#b2b-business-to-business) +- [Workforce](#workforce-business-to-enterprise) +- [Agentic AI](#agentic-ai) + + +### CIAM (Customer Identity and Access Management) + +Your company sells products or services directly to individual consumers. + +#### Key IAM requirements +- Self-service registration, login, and profile management for end users +- Social login, multi-factor passwordless options, and robust account recovery +- Privacy compliance (GDPR, CCPA) +- High-scale performance for millions of users + +### B2B (Business-to-Business) + +Your company sells products or services directly to other businesses rather than individual consumers. Your customers are organizations +that use these products or services to run their own operations. + +#### Key IAM requirements + +- Multi-organization user management +- SSO with SAML/OIDC providers +- Self-service partner onboarding +- Role-based permissions and API controls +- Privacy compliance (GDPR, CCPA) +- High-scale performance for millions of users + +### Workforce (Business-to-Enterprise) + +Your company provides products or services. Your company wants to manage access for a single organization's extended workforce. You want to +consolidate employee user accounts and identities across multi-tenant brands, applications and systems. You need to seamlessly connect with +existing enterprise identity providers and other 3rd party systems, and streamline user onboarding, offboarding, and permission management. + +#### Key IAM requirements +- Streamline onboarding/offboarding of employee, contractor, and temporary workers +- Role-based access aligned with organizational hierarchy +- HR system integration with flexible identity schemas +- Integrate with enterprise identity providers and third-party systems +- Time-bound permissions and role assignments +- Zero-trust security, MFA, and SSO for enterprise applications +- Privacy compliance (GDPR, CCPA) +- High-scale performance for millions of users + +### Agentic AI + +Your company wants to enable AI applications to securely connect to data sources and tools. For example, servers that host resources and +clients (AI applications) that discover and use those resources. + +#### Key IAM requirements +- Standardized protocol that works across many tools and data sources +- Built-in authentication and access control + +## Map all identity flows in your application + +Build a complete picture of every identity-related process in your system. Use your IAM scenario’s Key IAM requirements to identify +these flows. This ensures you don’t miss critical flows during migration. + +1. Identify all entry points where an identity-related process occurs (e.g., web app login, mobile app sign-in, API tokens, social or enterprise sign-ins). +1. Create a comprehensive inventory of flows, for example: + - Registration/sign-up + - Sign-in/sign-out + - Multi-Factor Authentication (MFA) + - Password reset and account recovery + - Account linking (social, enterprise logins) + - User profile management + - Token refresh and session handling + - Recovery flows, consent screens, or partner-specific integrations +1. Create flow diagrams (sequence diagrams or flow charts) to surface dependencies and hidden complexity. +1. Note where identity-related (authentication and authorization) processes interact with other systems (databases, CRMs, partner apps, or external APIs). + +At the end of this process you should have a living document with diagrams that capture: + +- All identity-related (authentication and authorization) flows +- Your system's existing functionality +- Any existing dependencies on external systems +- Edge cases requiring special handling + +This will serve as your blueprint for planning, designing, testing, and validating your migration. ```mdx-code-block import Help from '@site/docs/_common/need-help.mdx' diff --git a/docs/migrate-to-ory/migrate/migrate-identities.mdx b/docs/migrate-to-ory/migrate/migrate-identities.mdx index 1efd93298..5119be06e 100644 --- a/docs/migrate-to-ory/migrate/migrate-identities.mdx +++ b/docs/migrate-to-ory/migrate/migrate-identities.mdx @@ -4,39 +4,33 @@ title: Migrate your existing identities sidebar_label: Migrate your existing identities sidebar_position: 3 --- -With authentication now set up on your front end and back end, the next step is to prepare your existing user identities for -migration. +With authentication now set up on your frontend and backend, the next step is to prepare your existing user identities for +migration. You should have already chosen your identity migration strategy in [Phase 1: Plan and prepare](http://localhost:3002/docs/migrate-to-ory/migrate/migrate-strategies); +"bulk" or "graceful" migration. You will now implement your chosen identity migration strategy. -## Get existing user identities ready 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. +## Bulk import of identities -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. +If you're using a managed identity solution, it’s a good idea to start the export of existing identities early, especially +if there's no straightforward way to export the identities and you might need to go through a support process. Identify the +hashing algorithm used for credentials—if your passwords aren't hashed, Ory handles hashing automatically during import. +If Ory supports your hashing algorithm, use the [create identity API](../../reference/api#tag/identity/operation/createIdentity) +to import 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. -- For migrating from Auth0s, see [Migrate user identities from Auth0 to Ory](../migrate-from-auth0) +The create identity API supports bulk imports with a maximum of 1000 identities per request—larger imports require 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. See the [Import identities ](../../kratos/manage-identities/25_import-user-accounts-identities.mdx) +documentation for complete details. -## Import user identities +- For Auth0 migrations, see the dedicated [Migrate user identities from Auth0 to Ory](../migrate-from-auth0) guide. -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 +## Graceful import of identities 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. - +period during which both the old and new systems operate concurrently. During this period, use the [password migration hook](https://www.ory.com/docs/kratos/manage-identities/import-user-accounts-identities#password-migration-using-a-web-hook) +to migrate your existing users. 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 diff --git a/docs/migrate-to-ory/migrate/migrate-strategies.mdx b/docs/migrate-to-ory/migrate/migrate-strategies.mdx index ead96cb7e..3ba8719a7 100644 --- a/docs/migrate-to-ory/migrate/migrate-strategies.mdx +++ b/docs/migrate-to-ory/migrate/migrate-strategies.mdx @@ -1,106 +1,116 @@ --- id: migrate-strategies -title: Choose your migration strategy -sidebar_label: Choose your migration strategy +title: Choose your IAM migration strategy +sidebar_label: Choose your IAM migration strategy sidebar_position: 2 --- +This section covers both the strategies for migrating user identities to Ory and the broader considerations for +rolling out the Ory IAM system across all your applications. While user identity migration focuses on transferring user +accounts, credentials, and profile data, the IAM rollout determines how and when each application transitions to using Ory +for authentication and authorization. Understanding both dimensions is essential for planning a successful transition—the +strategy you choose for migrating user identities may differ for each phase in which you roll out the Ory IAM functionality across your +application portfolio. -When migrating user data, there are two main steps in the migration process; the first is a backfill, in which existing data -is transferred from the old system to the new system, and the second is a cutover or "go-live event", in which users authenticate with the new -system for the first time. There are three main migration strategies that consider these steps as well as when you turn-off your old system. +Your choice of migration strategy depends on your specific requirements, technical constraints, and tolerance for user impact. +It should be driven by several key factors: the complexity of your system, the size of your user base, and your organization's +risk tolerance and downtime constraints. -The three main migration strategies are: +## Choosing your user identity migration strategy -- **Big bang** - Migrate all users 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. +Ory supports two primary identity migration strategies: -Each migration strategy has its strengths and challenges. Which migration strategy you choose depends on factors such as the -complexity of your system, the number of users, and your organization's tolerance for risk and downtime. +- **Bulk migration** - Migrate all users at once. +- **Graceful migration** - Migrate when a user authenticates, running old and new solutions in parallel. -:::info +By carefully understanding these methods and planning accordingly, you can ensure a smooth and secure transition for your users to +Ory Network. -While your choice of migration strategy is mostly influenced by user data, if you have a complex system or are risk adverse, you might -choose your migration strategy based on its ability to breakdown the migration into a series of migrations. This lets you test your -processes in production by migrating less critical, sets of users or applications first and learning lessons to improve the migration process. +### Bulk identity migration -::: +In a bulk identity migration, also known as "big bang" or "offline" migration, all user data is migrated at once, and a single +"go-live" event is scheduled, where all users start using the new system simultaneously. -### Big bang migration +#### When to use bulk identity migration +A bulk identity migration can involve some risk and downtime, but it is recommended when: -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. +- The number of users is low and applications or services are simple +- Planned system downtime due to the "go-live" event isn't a problem +- You need to retire the current solution soon +- Your legacy IAM vendor restricts your ability to use a graceful identity migration strategy (for example, Auth0). -#### Recommendation -A big bang migration is often not the best choice due to the risk and downtime, but it is recommended when: +##### Advantages of bulk identity migration -- The number of users is low / app is simple -- Downtime isn't a problem -- You need to retire the current solution yesterday +- Simplicity: Since there is only one "go-live", the identity migration process is easier to manage and plan. +- Time efficiency: The identity migration process happens in one go, reducing the transition time. +- Less complexity: There is no need to run two systems in parallel and you can retire the previous solution immediately after +testing and validating the migration. -#### Advantages of big bang migration +##### Drawbacks of bulk identitiy 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. +- High risk: If any issues occur during the cutover, the impact can be significant, affecting all users. If might be difficult +to perform a rollback. - 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. -### Stepwise migration +### Graceful identity 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. +Graceful identity migration - also called "automatic", "trickle", "just-in-time", or "online" migration - involves running both the old and +new systems in parallel, gradually migrating user identities as the user authenticates. This approach features two "go-lives": the initial +application "go-live" and subsequent user-specific cutovers during login. -#### Recommendation -A stepwise migration is the best choice in most cases, especially when: +#### When to use graceful identity migration +A graceful identity migration is a good choice when: -- You manage multiple apps/segments of users with different underlying auth systems -- You need to keep active sessions live during the migration -- Downtime should be mostly avoided -- You have some time to migrate +- You don't have access to hashed credentials or they are hashed with a proprietary algorithm +- Authentication system downtime is not acceptable +- Running the current solution until the end of migration isn't a problem +- You need a smooth user experience, so your users will not notice the migration -#### Advantages of stepwise migration +##### Advantages of graceful identity 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. +- Low risk: The gradual identity migration 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 authentication systems operate simultaneously until the identity migration is completed. -#### Drawbacks of stepwise migration +##### Drawbacks of graceful identity 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. +- 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. (You need to +ensure identites are synchronized in both systems in case a rollback is required.) In addition, a graceful migration requires +additional coding effort to implement Ory's [password migration using a web hook](https://www.ory.com/docs/kratos/manage-identities/import-user-accounts-identities#password-migration-using-a-web-hook). +- Potential for data inconsistencies: If not carefully managed, there may be discrepancies between the old and new systems during the + transition period. -### Graceful migration +## Choosing your IAM system rollout strategy -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. +Simpler systems with homogenous segments of users and only one legacy authenication system to migrate from can be migrated in +one IAM system rollout. However, complex systems or risk-averse organizations may benefit from a "stepwise", "application-based", +or a "phased" rollout approach. This allows you to test processes in production by migrating less critical user segments or +applications first, learning valuable lessons to refine your approach before a broader rollout. -#### Recommendation -A graceful migration is a good choice when: +A stepwise approach involves migrating both user identities and applications/services in phases, focusing on specific applications, +services, or user segments. This approach results in multiple "go-lives", each affecting a defined group of users or applications/services. +A stepwise approach can employ bulk migration or graceful migration strategies, or a hybrid of both. The key difference is that a +specific segment of users or authenication for a specific application or service is migrated separately, each in its own specific phase. -- 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 +### When to use a stepwise rollout approach +A stepwise approach is the best choice in most cases, especially when: -#### Advantages of graceful migration +- You manage multiple enterpise-level applications with different underlying authentication systems +- You manage diverse segments of users with different underlying authentication systems +- You have a complex system, and you want to reduce the risk of unknown consequences and improve the process iteratively. -- 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. +### Advantages of stepwise rollout approach + +- 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 graceful migration +### Drawbacks of stepwise rollout approach -- 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. +- Complex management: Multiple "go-lives" require more coordination and detailed planning, increasing operational complexity. +- Extended timeline: The time to migrate the whole system takes longer as it is broken down into phases. +- Resource demands: Running both systems in parallel during the transition can strain resources. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/migrate-to-ory.mdx b/docs/migrate-to-ory/migrate/migrate-to-ory.mdx index 4b62ba809..d05884a97 100644 --- a/docs/migrate-to-ory/migrate/migrate-to-ory.mdx +++ b/docs/migrate-to-ory/migrate/migrate-to-ory.mdx @@ -4,7 +4,7 @@ title: Understand your current identity management system sidebar_label: Understand your current identity management system sidebar_position: 1 --- -# Understand your current identity management system +# Understand your current IAM system Below are example IAM scenarios supported by Ory Network. Use them to identify which scenario best fits your specific IAM needs and understand the unique requirements of each approach. Each scenario differs in complexity and implementation needs. Use these IAM @@ -38,6 +38,8 @@ that use these products or services to run their own operations. - SSO with SAML/OIDC providers - Self-service partner onboarding - Role-based permissions and API controls +- Privacy compliance (GDPR, CCPA) +- High-scale performance for millions of users ### Workforce (Business-to-Enterprise) @@ -52,6 +54,8 @@ existing enterprise identity providers and other 3rd party systems, and streamli - Integrate with enterprise identity providers and third-party systems - Time-bound permissions and role assignments - Zero-trust security, MFA, and SSO for enterprise applications +- Privacy compliance (GDPR, CCPA) +- High-scale performance for millions of users ### Agentic AI diff --git a/src/sidebar.ts b/src/sidebar.ts index c0d0f6899..b6560b2e9 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -200,22 +200,52 @@ const quickstart: SidebarItemsConfig = [ { type: "category", label: "Migrate to Ory Network", - link: { - type: "doc", - id: "migrate-to-ory/migrate/index", - }, + collapsed: true, + collapsible: true, items: [ - "migrate-to-ory/migrate/migrate-to-ory", - "migrate-to-ory/migrate/map-to-orycap", - "migrate-to-ory/migrate/migrate-strategies", - "migrate-to-ory/migrate/create-project", - "migrate-to-ory/migrate/design-id-schema", - "migrate-to-ory/migrate/integrate-frontend", - "migrate-to-ory/migrate/integrate-backend", - "migrate-to-ory/migrate/migrate-identities", - "migrate-to-ory/migrate/test-validate", - "migrate-to-ory/migrate/go-live", - "migrate-to-ory/migrate/faq-migrate", + { + type: "category", + label: "Phase 1: Plan & prepare", + collapsed: true, + collapsible: true, + items: [ + "migrate-to-ory/migrate/index", + "migrate-to-ory/migrate/map-to-orycap", + "migrate-to-ory/migrate/migrate-strategies", + "migrate-to-ory/migrate/faq-migrate", + ] + }, + { + type: "category", + label: "Phase 2: Migrate", + collapsed: true, + collapsible: true, + items: [ + "migrate-to-ory/migrate/create-project", + "migrate-to-ory/migrate/design-id-schema", + "migrate-to-ory/migrate/integrate-frontend", + "migrate-to-ory/migrate/integrate-backend", + "migrate-to-ory/migrate/migrate-identities", + ] + }, + { + type: "category", + label: "Phase 3: Test & validate", + collapsed: true, + collapsible: true, + items: [ + "migrate-to-ory/migrate/test-validate", + ] + }, + { + type: "category", + label: "Phase 4: Go live", + collapsed: true, + collapsible: true, + items: [ + "migrate-to-ory/migrate/go-live", + ] + }, ], }, "migrate-to-ory/auth0",