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/index.mdx b/docs/migrate-to-ory/index.mdx deleted file mode 100644 index ff0e8e77d..000000000 --- a/docs/migrate-to-ory/index.mdx +++ /dev/null @@ -1,277 +0,0 @@ ---- -id: index -title: Migrate to Ory tutorial -sidebar_label: Migrate to Ory -sidebar_position: 1 ---- - -This tutorial will guide you through the process of migrating your existing authentication system to Ory Identities, creating Ory -Network projects, setting up identity schemas, and customizing the user interface to match your current interface. - -:::note - -This guide is an initial reference and may not cover all aspects of your use case. If you have any questions or need more help, -don't hesitate to get in [touch with Ory Support for help](https://www.ory.sh/contact). - -::: - -## Pre-migration considerations - -Before starting the actual migration you should choose a migration strategy. - -### Migration scenario - -- **Scenario 1** - Migrating from a self-rolled solution - - If you're coming from a custom-built authentication solution, consider using Ory Identities. This approach simplifies the - migration by focusing solely on identity management without introducing the complexities of OAuth2. If you plan to move towards - OAuth2 eventually, you can plan for that transition once the initial migration is complete. To get started, refer to the - "Integrate Frontend & Backend" sections later in this guide. - -:::info - -If you are not sure whether or not you need OAuth2 for your use case, please read the -[When to use OAuth2](../hydra/concepts/before-oauth2) documentation. - -::: - -- **Scenario 2** - Migrating from Auth0 or another OAuth2-based solution - - If you're migrating from Auth0 or any other OAuth2-based login solution, you'll want to use Ory OAuth2 together with Ory - Identities. This setup allows you to keep your existing OAuth2-based flow while integrating it with Ory's identity management. - This approach is ideal if you want to keep your current implementation without making significant changes. To get started, refer - to the [Ory OAuth2 quickstart guide](../getting-started/oauth2-openid/add-oauth2-openid-connect-nodejs-expressjs) which provides - instructions on setting up an OAuth2/OIDC flow with Ory. - -- **Scenario 3** - Other - - If your authentication system doesn't fall into the categories described above - such as hybrid systems, legacy protocols, or - any other unique solution - you may need a different approach to migration. For such unique or complex migrations, we recommend - [consulting with Ory](https://www.ory.sh/contact/) to get a recommendation. The Ory team can help you design a custom migration - plan that aligns with your specific requirements. - -### Migration strategy - -When migrating user data from an old system to a new one, the process involves two main steps: transferring existing data and -"go-live" when users start authenticating with the new system. The choice of migration strategy depends on your specific use case, -the shape of existing data, and the number of "go-lives" you need to manage. - -- **Big bang** - Migrate everyone at once. -- **Stepped** - Migrate your applications or user segments individually. _This is the most common choice_. -- **Graceful** - Migrate when a user authenticates, running both solutions in parallel. - -Each migration strategy has its strengths and challenges. The ideal choice depends on factors such as the complexity of your -system, the number of users, and your organization's tolerance for risk and downtime. - -#### Big bang migration - -In a big bang migration, also known as "offline migration", all user data is transferred at once, and a single "go-live" event is -scheduled, where all users start using the new system simultaneously. - -##### Advantages of big bang migration - -- Simplicity: Since there is only one "go-live", the migration process is easier to manage and plan. -- Time efficiency: The migration process happens in one go, reducing the time needed for the transition. -- Less complexity: There is no need to run two systems in parallel and you can retire the previous solution immediately. - -##### Drawbacks of big bang migration - -- High risk: If any issues occur during the cutover, the impact can be significant, affecting all users. -- Downtime: This approach may require planned system downtime to ensure data consistency, which can disrupt users. -- Increased preparation: Requires extensive planning and testing to mitigate risks, making it more resource-intensive during that - phase. - -A big bang migration is often not the best choice due to the risk and downtime, but it is recommended when - -- the number of users is low / app is simple -- downtime isn't a problem -- you need to retire the current solution yesterday - -#### Stepwise migration - -Stepwise migration, also called "application-based migration", involves transferring user data in phases, focusing on specific -applications, services, or user segments at a time. This approach results in multiple "go-lives", each affecting a defined group -of users. - -##### Advantages of stepwise migration - -- Reduced risk: By migrating in phases, issues are isolated to specific apps or user segments. -- Flexibility: Allows for adjustments and optimizations between phases based on lessons learned. -- Minimized/no downtime: Since the migration occurs in stages, downtime can be limited to smaller user groups or avoided - completely. - -##### Drawbacks of stepwise migration - -- Complex management: Multiple "go-lives" require more coordination and detailed planning, increasing operational complexity. -- Extended timeline: The migration process takes longer as it is broken down into phases. -- Resource demands: Running both systems in parallel during the transition can strain resources. - -A stepwise migration is the best choice in most cases, especially when - -- you manage multiple apps/segments of users with different underlying auth systems -- downtime should be mostly avoided -- you have some time to migrate - -#### Graceful migration - -Graceful migration - also called "slow migration", "rolling migration", or "online migration" - involves running both the old and -new systems in parallel, gradually migrating users as they authenticate. This approach features two "go-lives": the initial -application "go-live" and subsequent user-specific cutovers during login. - -##### Advantages of graceful migration - -- Low risk: The gradual transition reduces the risk of widespread issues, as only a few users are affected at any given time. -- No hashed credentials needed: Users are migrated during their "normal" authentication process, so you don't need to import - credentials. Great if you don't have access to the hashed credentials. -- No downtime: Both systems operate simultaneously until the migration is completed. - -##### Drawbacks of graceful migration - -- Extended migration period: The process takes longer as users are migrated individually over time. -- Increased complexity: Maintaining synchronization between two systems adds complexity to the migration process. -- Potential for data inconsistencies: If not carefully managed, there may be discrepancies between the two systems during the - transition period. - -A graceful migration is a good choice when - -- you don't have access to hashed credentials or they are hashed with a proprietary algorithm -- absolutely no downtime is acceptable -- running the current solution until the end of migration isn't a problem - -## Create Ory Network projects - -Now that you have chosen your migration strategy, you can begin the actual migration process by setting up your Ory Network -projects. This involves creating a new project environment where the migration will take place. - -You can create a new Ory Network project using the Ory CLI. The command ory create project allows you to specify the environment -of the project, the output format, the name of the project, and the workspace to use. More details about creating a project can be -found [here](../cli/ory-create-project). - -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. - -```mdx-code-block -import Help from '@site/docs/_common/need-help.mdx' - - -``` diff --git a/docs/migrate-to-ory/migrate/create-project.mdx b/docs/migrate-to-ory/migrate/create-project.mdx new file mode 100644 index 000000000..3b8debde3 --- /dev/null +++ b/docs/migrate-to-ory/migrate/create-project.mdx @@ -0,0 +1,16 @@ +--- +id: create-project +title: Create an Ory Network project +sidebar_label: Create an Ory Network project +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 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 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/design-id-schema.mdx b/docs/migrate-to-ory/migrate/design-id-schema.mdx new file mode 100644 index 000000000..9000ecbf1 --- /dev/null +++ b/docs/migrate-to-ory/migrate/design-id-schema.mdx @@ -0,0 +1,37 @@ +--- +id: design-id-schema +title: Design your identity schema +sidebar_label: Design your identity schema +sidebar_position: 3 +--- + +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/faq-migrate.mdx b/docs/migrate-to-ory/migrate/faq-migrate.mdx new file mode 100644 index 000000000..e85dd4587 --- /dev/null +++ b/docs/migrate-to-ory/migrate/faq-migrate.mdx @@ -0,0 +1,8 @@ +--- +id: faq-migrate +title: Migration FAQ +sidebar_label: Migration 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.mdx b/docs/migrate-to-ory/migrate/go-live.mdx new file mode 100644 index 000000000..77bb34b05 --- /dev/null +++ b/docs/migrate-to-ory/migrate/go-live.mdx @@ -0,0 +1,24 @@ +--- +id: go-live +title: Go live +sidebar_label: Go live +sidebar_position: 2 +--- + +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/migrate/index.mdx b/docs/migrate-to-ory/migrate/index.mdx new file mode 100644 index 000000000..62e49fd96 --- /dev/null +++ b/docs/migrate-to-ory/migrate/index.mdx @@ -0,0 +1,111 @@ +--- +id: index +title: Understand your current IAM system +sidebar_label: Understand your current IAM system +sidebar_position: 1 +--- +# 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 +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. With Ory Network, you +gain full control, and with it, the ability to shape your system’s flows exactly to your needs. + +::: + +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' + + +``` \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/integrate-backend.mdx b/docs/migrate-to-ory/migrate/integrate-backend.mdx new file mode 100644 index 000000000..a29698aa9 --- /dev/null +++ b/docs/migrate-to-ory/migrate/integrate-backend.mdx @@ -0,0 +1,28 @@ +--- +id: integrate-backend +title: Integrate your backend +sidebar_label: Integrate your backend +sidebar_position: 1 +--- + +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.mdx b/docs/migrate-to-ory/migrate/integrate-frontend.mdx new file mode 100644 index 000000000..41a44ce6d --- /dev/null +++ b/docs/migrate-to-ory/migrate/integrate-frontend.mdx @@ -0,0 +1,31 @@ +--- +id: integrate-frontend +title: Integrate your frontend +sidebar_label: Integrate your frontend +sidebar_position: 1 +--- + +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/map-to-orycap.mdx b/docs/migrate-to-ory/migrate/map-to-orycap.mdx new file mode 100644 index 000000000..f8bf736d0 --- /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-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: + +- 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/migrate-identities.mdx b/docs/migrate-to-ory/migrate/migrate-identities.mdx new file mode 100644 index 000000000..5119be06e --- /dev/null +++ b/docs/migrate-to-ory/migrate/migrate-identities.mdx @@ -0,0 +1,37 @@ +--- +id: migrate-identities +title: Migrate your existing identities +sidebar_label: Migrate your existing identities +sidebar_position: 3 +--- +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. + +## Bulk import of identities + +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. + +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. + +- For Auth0 migrations, see the dedicated [Migrate user identities from Auth0 to Ory](../migrate-from-auth0) guide. + +## 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, 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 +during the migration. \ No newline at end of file diff --git a/docs/migrate-to-ory/migrate/migrate-strategies.mdx b/docs/migrate-to-ory/migrate/migrate-strategies.mdx new file mode 100644 index 000000000..3ba8719a7 --- /dev/null +++ b/docs/migrate-to-ory/migrate/migrate-strategies.mdx @@ -0,0 +1,116 @@ +--- +id: migrate-strategies +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. + +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. + +## Choosing your user identity migration strategy + +Ory supports two primary identity migration strategies: + +- **Bulk migration** - Migrate all users at once. +- **Graceful migration** - Migrate when a user authenticates, running old and new solutions in parallel. + +By carefully understanding these methods and planning accordingly, you can ensure a smooth and secure transition for your users to +Ory Network. + +### 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. + +#### When to use bulk identity migration +A bulk identity migration can involve some risk and downtime, but it is recommended when: + +- 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). + +##### Advantages of bulk identity migration + +- 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. + +##### Drawbacks of bulk identitiy migration + +- 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. + +### Graceful identity migration + +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. + +#### When to use graceful identity migration +A graceful identity migration is a good choice when: + +- 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 graceful identity migration + +- 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 graceful identity 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. (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. + +## Choosing your IAM system rollout strategy + +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. + +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. + +### When to use a stepwise rollout approach +A stepwise approach is the best choice in most cases, especially when: + +- 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. + +### 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 stepwise rollout approach + +- 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 new file mode 100644 index 000000000..d05884a97 --- /dev/null +++ b/docs/migrate-to-ory/migrate/migrate-to-ory.mdx @@ -0,0 +1,94 @@ +--- +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 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 +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. 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..db33da9b0 --- /dev/null +++ b/docs/migrate-to-ory/migrate/test-validate.mdx @@ -0,0 +1,29 @@ +--- +id: test-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: + +- 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 804bae1d8..b6560b2e9 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,7 +196,60 @@ const quickstart: SidebarItemsConfig = [ label: "Migrate to Ory", collapsed: false, collapsible: false, - items: ["migrate-to-ory/index", "migrate-to-ory/auth0"], + items: [ + { + type: "category", + label: "Migrate to Ory Network", + collapsed: true, + collapsible: true, + items: [ + { + 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", + ], }, ]