メインコンテンツへスキップ

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を組み込むことは単なるコード変更ではなく、データ移行です。慎重な計画なしには、usersテーブルの既存の行がすべてClerkにとって見知らぬものになります。最初のサインイン時に新しいアカウントがプロビジョニングされますが、そのどれも履歴データと一致せず、既存のカスタマーは「アカウントを失った」ように見えてしまいます。 正しく処理する必要があることは実質的に2つだけです。
このページはカスタム認証ソリューション（独自のusersテーブル、パスワードハッシュ、セッションなど）からClerk Authへの移行のみを対象としています。Replit AuthからClerk Authへの移行ガイドではありません。そちらの移行パスの公式ガイダンスは近日公開予定です。新しいアプリを開始する場合はClerk Auth概要を参照してください。移行は必要ありません。

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

アプリのすべてのアクティブユーザーは、Clerk Authが公開される前にClerkユーザーとして存在する必要があります。各インポートには最低限以下の情報が必要です：
  • メール（必須）
  • 利用可能なプロフィールメタデータ: 名前、認証ステータス、Authペインで表示したいその他の情報
  • パスワードダイジェスト: ユーザーの既存のパスワードハッシュ
  • パスワードハッシャー: そのハッシュのアルゴリズム/形式（Clerkが期待する正確な形式）
ハッシャーは間違えやすい部分です。Clerkは定義されたパスワードハッシュ形式のセットのみを受け付けており、それぞれに特定の文字列識別子（bcrypt、scrypt_firebase、argon2i、pbkdf2_sha256など）があります。各形式が必要とするダイジェスト形式の完全なリストはClerk Create User APIリファレンスで確認してください。 このステップには一行のプロンプト以上のものが必要です。移行を行う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よりもそれを優先させるだけでいいです： 
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固有のものではありません。

​
追加リソース