Skip to content

feat: add Ory Console guide for password migration hook #2500

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MikeSagnelli merged 5 commits into from
Apr 15, 2026
Merged

feat: add Ory Console guide for password migration hook #2500

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f73e005
docs(kratos): add Ory Console steps for password migration hook
MikeSagnelli Apr 3, 2026
8641be1
feat: fix url to images
MikeSagnelli Apr 7, 2026
0fe87c5
fix: use explicit naming for images
MikeSagnelli Apr 8, 2026
ac90847
docs(kratos): address PR review feedback on password migration guide
MikeSagnelli Apr 9, 2026
b79653b
fix: format file
MikeSagnelli Apr 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added ...anage-identities/import-user-accounts-identities/pw-migration-pending-badge.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added ...nage-identities/import-user-accounts-identities/pw-migration-webhook-step-1.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added ...nage-identities/import-user-accounts-identities/pw-migration-webhook-step-2.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added ...anage-identities/import-user-accounts-identities/pw-migration-webhook-table.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
104 changes: 101 additions & 3 deletions docs/kratos/manage-identities/25_import-user-accounts-identities.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ toc_max_heading_level: 3

# Import identities

```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import BrowserWindow from "@site/src/theme/BrowserWindow"
```

Ory allows you to import identities from any other system. To import identities, you use the same endpoint as for
[creating identities](./20_create-users-identities.mdx). The main difference between creating and importing identities is that
when you import identities, you must provide the `credentials` field.
Expand Down Expand Up @@ -45,9 +51,6 @@ This is a sample payload for importing an identity with a verified address:
Test the above example with a cURL command:

````mdx-code-block
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'

<Tabs
defaultValue="cloud"
values={[
Expand Down Expand Up @@ -553,6 +556,75 @@ The following steps are necessary to set up password migration using a web hook:

2. Configure a password migration web hook

```mdx-code-block
<Tabs
defaultValue="console"
values={[
{label: 'Ory Console', value: 'console'},
{label: 'Ory CLI', value: 'cli'},
]}>
<TabItem value="console">
```

a. Go to your project in the [Ory Console](https://console.ory.sh).

b. Click **Authentication** in the top navigation bar.

c. Click **Actions & Webhooks** in the left sidebar.

d. Click **Create new Action**.

e. In the **Action Base Details** dialog, fill in the following fields:

- **Flow** — Select **Password Migration**. The execution phase and method fields are hidden because the migration hook runs
at login time automatically, outside of the standard flow lifecycle.

- **URL** — Enter the URL of your password migration webhook endpoint, for example `https://example.org/migrate-password`.

- **Method** — Select the HTTP method your endpoint expects, for example **POST**.

- **Action HTTP body** — The body is pre-filled with a Jsonnet template that maps `ctx.identifier` and `ctx.password` to the
request payload. You can customize it. See the
[webhook documentation](../../guides/integrate-with-ory-cloud-through-webhooks.mdx#customizing-request-body-with-jsonnet)
for all available context fields.

```mdx-code-block
<BrowserWindow url="https://console.ory.sh/projects/b3b748e5-7ddc-4860-a672-2436a877dc93/developers/actions">
![Action Base Details dialog with Password Migration flow selected](../_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-step-1.png)
</BrowserWindow>
```

f. Click **Next** to proceed to the **Action authentication** step. Select the authentication type for your webhook endpoint.
Ory supports **None**, **Basic** (username and password), and **Key** (API key in a header or cookie). See the
[webhook authentication documentation](../../guides/integrate-with-ory-cloud-through-webhooks.mdx#request-authentication) for
details on each option.

:::warning

Leaving your webhook endpoint unauthenticated exposes it to unauthorized access. Secure your endpoint with strong
authentication to protect sensitive credentials passed during migration.

:::

```mdx-code-block
<BrowserWindow url="https://console.ory.sh/projects/b3b748e5-7ddc-4860-a672-2436a877dc93/developers/actions">
![Action authentication dialog](../_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-step-2.png)
</BrowserWindow>
```

g. Click **Save action**. The new **Password Migration** action appears in the actions table.

```mdx-code-block
<BrowserWindow url="https://console.ory.sh/projects/b3b748e5-7ddc-4860-a672-2436a877dc93/developers/actions">
![Actions & Webhooks page showing the Password Migration action](../_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-table.png)
</BrowserWindow>
```

```mdx-code-block
</TabItem>
<TabItem value="cli">
```

Add the web hook URL to the configuration. See the
[web hook configuration](../../guides/integrate-with-ory-cloud-through-webhooks.mdx#request-authentication) for authentication
options. If you use Ory Network, update this configuration directly using the
Expand Down Expand Up @@ -589,6 +661,11 @@ The following steps are necessary to set up password migration using a web hook:
}
```

```mdx-code-block
</TabItem>
</Tabs>
```

3. Implement the password migration web hook

If a user logs in and the identifier points to an identity that has `use_password_migration_hook` set to `true`, Ory
Expand All @@ -602,6 +679,27 @@ The following steps are necessary to set up password migration using a web hook:
}
```

To verify that an identity is pending migration in the Ory Console:
Copy link
Copy Markdown
Contributor

@unatasha8 unatasha8 Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a way to verify an identity is pending migration from the CLI?

Copy link
Copy Markdown
Contributor Author

@MikeSagnelli MikeSagnelli Apr 9, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not directly through the CLI. The ory get identity command has an --include-credentials flag, but its documentation states it only supports oidc.

However, you can verify it through the Admin API by calling:

GET /admin/identities/{id}?include_credential=password

If credentials.password.config.use_password_migration_hook is true and hashed_password is empty, the identity is pending migration.

I can add this as an API example alongside the Console guide if that would be helpful. However, IMO it is not very straightfoward.

Copy link
Copy Markdown
Contributor

@unatasha8 unatasha8 Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this feature only for Ory Network? If not (or we plan to add to OEL/OSS later), we probably need the verify via Admin API too.

Copy link
Copy Markdown
Contributor Author

@MikeSagnelli MikeSagnelli Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not a new feature in Ory Network, this is a new feature in Console. We were already able to import identities using the password migration webhook. The only thing that was recently worked on was adding that capability to the Console. Therefore, I believe this is already in OEL/OSS.
In order to check via API if an identity has been successfully migrated, when getting the identity instead of seeing:

{
  "schema_id": "preset://email",
  "traits": {
    "email": "pw-migration@example.org"
  },
  "credentials": {
    "password": {
      "config": {
        "hashed_password": "",
        "use_password_migration_hook": true
      }
    }
  }
}

{
  "schema_id": "preset://email",
  "traits": {
    "email": "pw-migration@example.org"
  },
  "credentials": {
    "password": {
      "config": {
        "hashed_password": "<NON_EMPTY_VALUE>",
      }
    }
  }
}

Let me know if it makes sense to add this.


a. Go to your project in the [Ory Console](https://console.ory.sh).

b. Click **User management** in the top navigation bar.

c. Click **Users & identities** in the left sidebar.

d. Find the identity you want to review and click the three-dot menu (**⋮**) on its row.

e. Click **View identity** to open its details.

f. In the **Basic Information** section, under **Credential Identifiers**, the identity shows a **Migration pending** badge if
the user hasn't logged in and completed the password migration yet.

```mdx-code-block
<BrowserWindow url="https://console.ory.sh/projects/b3b748e5-7ddc-4860-a672-2436a877dc93/identities/2db9fa1c-95fd-4112-bdbc-a4bd857d7426">
![Identity detail page showing the Migration pending badge](../_static/manage-identities/import-user-accounts-identities/pw-migration-pending-badge.png)
</BrowserWindow>
```

The web hook can then check the identifier and password against the legacy system. If the password matches, the web hook must
respond with a `200 OK` status code and the following payload:

Expand Down
Loading