> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 既存アプリをClerk Authに移行する

> アカウントや履歴データを失うことなく、既存の認証システムを持つアプリをClerk Authに移行するためのベストプラクティスを説明します。

アプリにすでに機能している認証システムと実際のユーザーのデータベースがある場合、[Clerk Auth](/references/auth-and-identity/clerk-auth)を組み込むことは**単なるコード変更ではなく、データ移行**です。慎重な計画なしには、`users`テーブルの既存の行がすべてClerkにとって見知らぬものになります。最初のサインイン時に新しいアカウントがプロビジョニングされますが、そのどれも履歴データと一致せず、既存のカスタマーは「アカウントを失った」ように見えてしまいます。

正しく処理する必要があることは実質的に2つだけです。

<Note>
  このページは**カスタム認証ソリューション**（独自のusersテーブル、パスワードハッシュ、セッションなど）からClerk Authへの移行のみを対象としています。[Replit Auth](/references/auth-and-identity/authentication)からClerk Authへの移行ガイドでは**ありません**。そちらの移行パスの公式ガイダンスは近日公開予定です。

  新しいアプリを開始する場合は[Clerk Auth概要](/references/auth-and-identity/clerk-auth)を参照してください。移行は必要ありません。
</Note>

## 1. 既存ユーザーをClerkにインポートする

アプリのすべてのアクティブユーザーは、Clerk Authが公開される*前に*Clerkユーザーとして存在する必要があります。各インポートには最低限以下の情報が必要です：

* **メール**（必須）
* **利用可能なプロフィールメタデータ**: 名前、認証ステータス、Authペインで表示したいその他の情報
* **パスワードダイジェスト**: ユーザーの既存のパスワードハッシュ
* **パスワードハッシャー**: そのハッシュのアルゴリズム/形式（Clerkが期待する正確な形式）

ハッシャーは間違えやすい部分です。Clerkは定義されたパスワードハッシュ形式のセットのみを受け付けており、それぞれに特定の文字列識別子（`bcrypt`、`scrypt_firebase`、`argon2i`、`pbkdf2_sha256`など）があります。各形式が必要とするダイジェスト形式の完全なリストは[Clerk Create User APIリファレンス](https://clerk.com/docs/reference/backend/user/create-user)で確認してください。

このステップには一行のプロンプト以上のものが必要です。移行を行うAgentは**現在のコードベースでのパスワードハッシュ方法について徹底的な理解**が必要です。使用ライブラリ、パラメータ（コストファクター、ソルトレイアウト、ペッパーなど）、そしてそれがClerkのサポートするハッシャーのどれにマッピングされるかです。適切に形成されたプロンプトは次のようになります：

```
Read my existing auth code and identify exactly how passwords are hashed
(library, algorithm, parameters, and how the stored value is formatted).
Then write a one-shot import script that, for every user in my users table,
calls the Clerk Backend API with email, profile metadata, the password
digest in the exact format the matching Clerk hasher expects, and the
correct `passwordHasher` value. Tell me which Clerk hasher you picked
and why before you run it.
```

ハッシュスキームがClerkのサポートするハッシャーのいずれにもクリーンにマッピングされない場合、インポートされたユーザーは既存のパスワードでサインインできません。その場合は、ダイジェストなしでインポートし、切り替え時にパスワードリセットメールを送信してください。

## 2. ClerkユーザーをリストアExisting User IDにマッピングする

インポートされたユーザーがサインインすると、すべての認証済みリクエストはClerkのアイデンティティを持ちます。サーバーは`users`テーブルの行にそのアイデンティティをマッピングし直す必要があります。そうしないと、ClerkユーザーIDが既存の外部キー（`orders.user_id`、`documents.owner_id`など）と一致せず、履歴データが失われたように見えてしまいます。

Replit管理のClerkではこれが簡単です。ユーザーを既存のIDをClerkユーザーの`externalId`としてインポートすると、その値が自動的にセッションクレームに`sessionClaims.userId`として書き込まれます。ミドルウェアは生のClerkユーザーIDよりもそれを優先させるだけでいいです：

```ts theme={null}
import { getAuth } from "@clerk/express";

const requireAuth = (req: any, res: any, next: any) => {
  const auth = getAuth(req);
  const userId = auth?.sessionClaims?.userId || auth?.userId;
  if (!userId) {
    return res.status(401).json({ error: "Unauthorized" });
  }
  req.userId = userId;
  next();
};
```

このパターンにより：

* **インポートされたユーザー**は`sessionClaims.userId`を通じて既存の`users.id`に解決されます。すべての履歴データが引き続き紐付けられます。
* **全く新しいユーザー**（切り替え後にサインアップし、`externalId`がないユーザー）は`auth.userId`にフォールバックします。これはClerkユーザーIDです。これを新しい行の主キーとして使用するか、最初のサインイン時に行を作成してリンクさせます。

## これだけです

それ以外のこと（古い認証を並行して動作させること、実際のアカウントでドライランを実行すること、切り替え後の重複ユーザー作成を監視すること、古いシステムを廃止すること）は標準的な移行のルーティンであり、Clerk Auth固有のものではありません。

## 追加リソース

* [Clerk Auth概要](/references/auth-and-identity/clerk-auth) — ReplitでのClerk Authの仕組み
* [Clerk: Create User API](https://clerk.com/docs/reference/backend/user/create-user) — サポートされているパスワードハッシャーとダイジェスト形式