Skip to content

Commit 032c91a

Browse files
unatasha8jonas-jonasadamwalachvinckrnsklikas
authored
feat: migration guide updates (#2315)
* chore: migration guide updates * chore: migration guide updates * chore: migration guide updates * chore: edits to migration guide * docs: updated migration strategies and identity schema content * Update docs/migrate-to-ory/migrate/create-project.mdx Co-authored-by: Jonas Hungershausen <jonas.hungershausen@ory.sh> * docs: final review comments * chore: format * chore: formatting fixes * chore: fixed tabs again * chore: formatting fixes * chore: fix formating * chore: fix formatting * chore: fix formating again * Update docs/migrate-to-ory/migrate/migrate-strategies.mdx Co-authored-by: Jonas Hungershausen <jonas.hungershausen@ory.sh> * docs: switch to calendar-based unified versioning (#2326) * docs: switch to calendar-based unified versioning * Update docs/ecosystem/upgrading.mdx * Update docs/ecosystem/upgrading.mdx * Update docs/ecosystem/upgrading.mdx * Update docs/ecosystem/upgrading.mdx * Update docs/ecosystem/upgrading.mdx * Update docs/ecosystem/upgrading.mdx * chore: format --------- Co-authored-by: unatasha8 <una.cogavin@ory.sh> Co-authored-by: vinckr <vincent@ory.sh> * docs: add device flow documentation (#2026) * docs: add device flow documentation * chore: Refine device verification UI section wording * chore: Update user code entropy configuration details Clarified the description of user code entropy options and their implications for user entry. * chore: Revise Device Authorization Grant documentation Updated the description and steps for the Device Authorization Grant to clarify the process and correct terminology. * chore: Update device authorization flow steps and formatting * chore: Added image for device authorization flow Added an image to illustrate the device authorization flow. * chore: Fix image path for device authorization flow * chore: Integrate Mermaid diagram for device authorization flow Added a sequence diagram to illustrate the device authorization flow using Mermaid. * Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik <zepatrik@users.noreply.github.com> * Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik <zepatrik@users.noreply.github.com> * Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik <zepatrik@users.noreply.github.com> * Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik <zepatrik@users.noreply.github.com> * Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik <zepatrik@users.noreply.github.com> * Update docs/oauth2-oidc/device-authorization.mdx Co-authored-by: Patrik <zepatrik@users.noreply.github.com> * chore: address review comments and format * chore: add to sidebar * chore: fix grammar and typos --------- Co-authored-by: unatasha8 <una.cogavin@ory.sh> Co-authored-by: Patrik <zepatrik@users.noreply.github.com> Co-authored-by: vinckr <vincent@ory.sh> * fix: high-perf pooling doc (#2332) * fix: high-perf pooling doc * chore: apply suggestion from code review Co-authored-by: hackerman <3372410+aeneasr@users.noreply.github.com> * chore: apply suggestion from code review Co-authored-by: hackerman <3372410+aeneasr@users.noreply.github.com> * chore: apply suggestions from code review Co-authored-by: Arne Luenser <arne.luenser@ory.sh> * chore: omit slop --------- Co-authored-by: hackerman <3372410+aeneasr@users.noreply.github.com> Co-authored-by: Arne Luenser <arne.luenser@ory.sh> * chore(docs): update of OEL images (#2337) chore(docs): update OEL image tag * autogen(docs): generate cli docs * autogen(docs): generate cli docs * autogen(docs): generate cli docs * chore: added oel configuration schemas (#2279) * WIP * temp hack for oathkeeper schema id * temp hack for oathkeeper schema id * revert schema urls * - added new config pages for OEL - updated dep - resolve internal refs in ory resolvers correctly * docs: bump to 99e1d24edde1c46372cb61a1839961fde59dba8b * chore: clarify webhook config update (#2339) * fix: organizations docs (#2334) * feat: flutter quickstart (#2241) * flutter quickstart update * updating docs to handle the .env misnaming in the pubspec and the port mismatch * resolving default import issue with mdx for .env ref * doc change for flutter quickstart * fix: format * update: pubspec.lock * update: pubspec * update: pubspec to higher version * update: packages * debug: test * debug: test * upgrade: flutter to latest version| * remove: web renderer option for flutter * feat: add kratos webhook header allowlist config details (#2100) * feat: add kratos webhook header allowlist config details Signed-off-by: Mia <m@yarn.network> * fix: wording Signed-off-by: Mia <m@yarn.network> --------- Signed-off-by: Mia <m@yarn.network> * chore: migration guide updates * chore: migration updates * chore: migration guide updates * chore: update migration guide --------- Signed-off-by: Mia <m@yarn.network> Co-authored-by: Jonas Hungershausen <jonas.hungershausen@ory.sh> Co-authored-by: Adam Wałach <adam.walach@gmail.com> Co-authored-by: vinckr <vincent@ory.sh> Co-authored-by: Nikos Sklikas <nikos.sklikas@canonical.com> Co-authored-by: Patrik <zepatrik@users.noreply.github.com> Co-authored-by: hackerman <3372410+aeneasr@users.noreply.github.com> Co-authored-by: Arne Luenser <arne.luenser@ory.sh> Co-authored-by: ory-bot <60093411+ory-bot@users.noreply.github.com> Co-authored-by: Deepak Prabhakara <deepak.prabhakara@ory.sh> Co-authored-by: Parth <46842784+pi1814@users.noreply.github.com> Co-authored-by: Mia <m@yarn.network>
1 parent 1a925a0 commit 032c91a

22 files changed

+1012
-289
lines changed

docs/migrate-to-ory/auth0.mdx

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,10 @@
11
---
22
id: auth0
3-
title: Migrate users from Auth0 to Ory
4-
sidebar_label: Migrate from Auth0
3+
title: Migrate user identities from Auth0 to Ory
4+
sidebar_label: Migrate user identities from Auth0 to Ory
55
slug: migrate-from-auth0
66
---
77

8-
# Migrate from Auth0
9-
108
This guide shows you how to migrate user accounts from Auth0 to Ory. The instructions in this document assume that your Auth0
119
setup includes a database connection and that the users whose accounts you migrate use emails and passwords as their login
1210
credentials.

docs/migrate-to-ory/index.mdx

Lines changed: 0 additions & 283 deletions
This file was deleted.
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
id: create-project
3+
title: Create project
4+
sidebar_label: Create project
5+
sidebar_position: 3
6+
---
7+
8+
## Create Ory Network projects
9+
10+
Now that you have chosen your migration strategy, you can begin the actual migration process by setting up your Ory Network
11+
projects. This involves creating a new project environment where the migration will take place.
12+
13+
You can create a new Ory Network project using the Ory CLI. The command ory create project allows you to specify the environment
14+
of the project, the output format, the name of the project, and the workspace to use. More details about creating a project can be
15+
found [here](../cli/ory-create-project).
16+
17+
Before migrating your production environment, perform the migration in a development or staging environment. This allows you to
18+
test and refine the process without affecting your live data or users.
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
id: create-project
3+
title: Create an Ory Network project
4+
sidebar_label: Create an Ory Network project
5+
sidebar_position: 3
6+
---
7+
8+
Now that you have chosen your migration strategy, you can begin the actual migration process. Perform the migration in a
9+
development or staging environment before migrating to your production environment. This allows you to test and refine the process
10+
without affecting your live data or users.
11+
12+
1. Get an [Ory Network account](https://console.ory.sh/login?flow=c59cbae0-ea41-44e4-b46a-f9e1857be3a2).
13+
1. Install Ory CLI and [set up your local environment](https://www.ory.com/docs/getting-started/local-development) to start
14+
developing with Ory.
15+
1. Create an Ory project and get your Ory project ID.
16+
1. [Set up the necessary dependencies and configurations](https://www.ory.com/docs/identities/get-started/setup) to integrate
17+
Ory's features into your application.
18+
1. Review a [quick start](https://www.ory.com/docs/welcome) for your framework.
19+
20+
You can use the Ory CLI to specify the environment of the project, the output format, the name of the project, and the workspace
21+
to use. See the [Ory CLI Reference](../../cli/ory-create-project) for the `ory create project` command and additional options.
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
id: define-id-schema
3+
title: Define identity schema
4+
sidebar_label: Define identity schema
5+
sidebar_position: 3
6+
---
7+
8+
9+
## Define identity schema
10+
11+
To match identities from your current system with the new Ory system, you can customize the identity schema in Ory to meet your
12+
specific requirements. This schema defines the types of data that the system can store for users, including names, email
13+
addresses, phone numbers, and other authentication-related information. Additionally, you can specify extra metadata fields to be
14+
included in user profiles. Ory offers default presets to assist you in creating and managing identity schemas. More details about
15+
identity schemas can be found [here](../kratos/manage-identities/identity-schema).
16+
17+
- Do store profile data in your identity that is used across your system. This includes the usernames, email addresses, phone
18+
numbers, first names, and last names.
19+
- Do not store business logic in your identity, store this information in other systems, such as your application database. This
20+
includes for example credit card information, shipping addresses, shopping cart items, or user preferences. See also the
21+
following section on backend integration.
Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
id: design-id-schema
3+
title: Design your identity schema
4+
sidebar_label: Design your identity schema
5+
sidebar_position: 3
6+
---
7+
8+
To align identities from your current system with Ory, you can customize the identity schema to meet your specific requirements.
9+
This ability to customize the identity schema means you can enhance and improve your old identity schema during the migration
10+
process.
11+
12+
The identity schema, which implements the JSON Schema standard, defines the types of data the system can store for users—such as
13+
names, email addresses, phone numbers, or birthdays. It also controls business logic by specifying which fields serve as login
14+
identifiers and which are used for verification or recovery.
15+
16+
Identities have two main data types: traits (attributes that users can modify themselves, such as username or email address) and
17+
metadata (attributes defined by system admins that can only be updated through admin APIs. Metadata is useful for storing
18+
information like subscription status, legacy user IDs, or basic roles). Metadata comes in two forms: public (visible to users via
19+
session endpoints) and admin (only accessible through admin APIs).
20+
21+
## Best practices for identity schema design:
22+
23+
### Do:
24+
25+
- Use the identity schema for basic profile information that's used across your system, including usernames, email addresses,
26+
phone numbers, first names, and last names
27+
- Store authentication-related data like login identifiers and verification addresses in traits
28+
- Use metadata fields for system-managed information like legacy user IDs, subscription status, or basic roles
29+
30+
### Don't:
31+
32+
- Store sensitive internal data or information that should be obfuscated from users in the identity schema, since users can see
33+
traits and other data (except credentials) using the `/sessions/whoami` endpoint
34+
- Store business logic or application-specific data like credit card information, shipping addresses, shopping cart items, or
35+
detailed user preferences—keep this in your application database instead
36+
37+
Ory provides preset schemas to help you get started quickly. For detailed guidance on customizing schemas, see the
38+
[identity schemas](../../kratos/manage-identities/identity-schema) documentation.
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
id: faq-migrate
3+
title: Migration FAQ
4+
sidebar_label: Migration FAQ
5+
sidebar_position: 1
6+
---
7+
8+
TODO: Living section for specific questions/answers that Sales get asked but which don't neatly fit within the migration process.
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
id: go-live
3+
title: Go live
4+
sidebar_label: Go live
5+
sidebar_position: 2
6+
---
7+
8+
9+
# Go live
10+
11+
After successfully migrating your data and testing the integration in your development or staging environment, it's time to go
12+
live with Ory in your production environment.
13+
14+
1. Final testing: Before switching over to Ory in production, conduct thorough testing of all user authentication flows, identity
15+
management features, and access controls. This includes testing edge cases, error handling, and load testing to ensure the
16+
system can handle your user base.
17+
1. Prepare a rollback plan: In case any issues arise during the go-live process, have a rollback plan in place. This may involve
18+
reverting to your previous authentication system or restoring data from backups.
19+
1. Schedule the go-live: Choose a time for the go-live that minimizes the impact on your users, such as during low-traffic
20+
periods. Communicate the planned migration to your users in advance, including any expected downtime or changes they should be
21+
aware of.
22+
1. Monitor the transition: As you switch over to Ory, closely monitor the system for any issues, such as failed authentications,
23+
performance bottlenecks, or user complaints. Use live events to monitor the system under
24+
<ConsoleLink route="project.activity.events" />.
25+
1. Optimize and refine: After the go-live, continue to monitor the system and gather user feedback.
26+
27+
Once your Ory integration is stable and users are successfully authenticating with the new system, your migration is complete.
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
id: go-live
3+
title: Go live
4+
sidebar_label: Go live
5+
sidebar_position: 2
6+
---
7+
8+
After successfully migrating your data and testing the integration in your development or staging environment, it's time to go
9+
live with Ory in your production environment.
10+
11+
1. Final testing: Before switching over to Ory in production, conduct thorough testing of all user authentication flows, identity
12+
management features, and access controls. This includes testing edge cases, error handling, and load testing to ensure the
13+
system can handle your user base.
14+
1. Prepare a rollback plan: In case any issues arise during the go-live process, have a rollback plan in place. This may involve
15+
reverting to your previous authentication system or restoring data from backups.
16+
1. Schedule the go-live: Choose a time for the go-live that minimizes the impact on your users, such as during low-traffic
17+
periods. Communicate the planned migration to your users in advance, including any expected downtime or changes they should be
18+
aware of.
19+
1. Monitor the transition: As you switch over to Ory, closely monitor the system for any issues, such as failed authentications,
20+
performance bottlenecks, or user complaints. To monitor the system, view live events at
21+
<ConsoleLink route="project.activity.events" />.
22+
1. Optimize and refine: After the go-live, continue to monitor the system, gather user feedback, and make adjustments as needed to
23+
improve performance and user experience.
24+
25+
Once your Ory integration is stable and users are successfully authenticating with the new system, your migration is complete.
26+
Continue to leverage Ory's features to enhance your authentication and identity management over time.
Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
---
2+
id: index
3+
title: Understand your current IAM system
4+
sidebar_label: Understand your current IAM system
5+
sidebar_position: 1
6+
---
7+
8+
# Understand your current IAM system
9+
10+
Before you can migrate smoothly, you need a complete picture of how your identity management system works today. This step ensures
11+
nothing gets missed—from everyday login flows to rare edge cases—and sets the foundation for mapping existing functionality to Ory
12+
Network's equivalent capabilities.
13+
14+
:::info Why it matters
15+
16+
Mapping your full login lifecycle is the best way to de-risk migration. Your current IAM system may be abstracting away key
17+
functionality without you realizing it. With Ory Network, you gain full control to shape and optimize every flow to your needs.
18+
:::
19+
20+
## Identify your IAM scenario
21+
22+
Below are example IAM scenarios supported by Ory Network. Use them to identify which scenario best fits your specific IAM needs
23+
and understand the unique requirements of each approach. Each scenario differs in complexity and implementation needs. Use these
24+
IAM scenarios to map the identity flows for your application.
25+
26+
<Tabs
27+
defaultValue="CIAM"
28+
values={[
29+
{label: 'CIAM', value: 'CIAM'},
30+
{label: 'B2B', value: 'B2B'},
31+
{label: 'Workforce', value: 'Workforce'},
32+
{label: 'Agentic AI', value: 'Agentic AI'},
33+
]}>
34+
35+
<TabItem value="CIAM">
36+
37+
### CIAM (Customer Identity and Access Management)
38+
39+
Your company sells products or services directly to individual consumers.
40+
41+
#### Key IAM requirements
42+
43+
- Self-service registration, login, and profile management for end users
44+
- Social login, multi-factor passwordless options, and robust account recovery
45+
- Privacy compliance (GDPR, CCPA)
46+
- High-scale performance for millions of users
47+
48+
</TabItem>
49+
50+
<TabItem value="B2B">
51+
52+
### B2B (Business-to-Business)
53+
54+
Your company sells products or services directly to other businesses rather than individual consumers. Your customers are
55+
organizations that use these products or services to run their own operations.
56+
57+
#### Key IAM requirements
58+
59+
- Multi-organization user management
60+
- SSO with SAML/OIDC providers
61+
- Self-service partner onboarding
62+
- Role-based permissions and API controls
63+
- Privacy compliance (GDPR, CCPA)
64+
- High-scale performance for millions of users
65+
66+
</TabItem>
67+
68+
<TabItem value="Workforce">
69+
70+
### Workforce (Business-to-Enterprise)
71+
72+
Your company provides products or services. Your company wants to manage access for a single organization's extended workforce.
73+
You want to consolidate employee user accounts and identities across multi-tenant brands, applications and systems. You need to
74+
seamlessly connect with existing enterprise identity providers and other 3rd party systems, and streamline user onboarding,
75+
offboarding, and permission management.
76+
77+
#### Key IAM requirements
78+
79+
- Streamline onboarding/offboarding of employee, contractor, and temporary workers
80+
- Role-based access aligned with organizational hierarchy
81+
- HR system integration with flexible identity schemas
82+
- Integrate with enterprise identity providers and third-party systems
83+
- Time-bound permissions and role assignments
84+
- Zero-trust security, MFA, and SSO for enterprise applications
85+
- Privacy compliance (GDPR, CCPA)
86+
- High-scale performance for millions of users
87+
88+
</TabItem>
89+
90+
<TabItem value="Agentic AI">
91+
92+
### Agentic AI
93+
94+
Your company wants to enable AI applications to securely connect to data sources and tools. For example, servers that host
95+
resources and clients (AI applications) that discover and use those resources.
96+
97+
#### Key IAM requirements
98+
99+
- Standardized protocol that works across many tools and data sources
100+
- Built-in authentication and access control
101+
102+
</TabItem>
103+
104+
</Tabs>
105+
106+
## Map all identity flows in your application
107+
108+
Document every identity-related (authentication and authorization) process in your system. Use your IAM scenario’s Key IAM
109+
requirements to identify these flows. This ensures you don’t miss critical flows during migration.
110+
111+
1. Identify all entry points where an identity-related process occurs (e.g., web app login, mobile app sign-in, API tokens, social
112+
or enterprise sign-ins).
113+
1. Create a comprehensive inventory of flows, for example:
114+
- Registration
115+
- Sign-in and sign-out
116+
- Multi-Factor Authentication (MFA)
117+
- Password reset and account recovery
118+
- Account linking (social, enterprise logins)
119+
- User profile management
120+
- Token refresh and session handling
121+
- Recovery flows, consent screens, or partner-specific integrations
122+
1. Create flow diagrams (sequence diagrams or flow charts) to surface dependencies and hidden complexity.
123+
1. Note where identity-related processes interact with other systems (databases, CRMs, partner apps, or external APIs).
124+
125+
At the end of this process you should have a living document (one that you'll update as you discover more) with diagrams that
126+
capture:
127+
128+
- All identity-related flows
129+
- Your system's existing functionality
130+
- Any existing dependencies on external systems
131+
- Edge cases requiring special handling
132+
133+
This will serve as your blueprint for planning, designing, testing, and validating your migration.
134+
135+
```mdx-code-block
136+
import Help from '@site/docs/_common/need-help.mdx'
137+
138+
<Help/>
139+
```

0 commit comments

Comments
 (0)