メインコンテンツまでスキップ

マジックリンク（ワンタイムトークン）

ワンタイムパスワード（OTP）と同様に、ワンタイムトークンはユーザーのアイデンティティを検証するために使用できる、もう一つのパスワードレス認証 (Authentication) 方法です。 このトークンは一定期間のみ有効で、エンドユーザーのメールアドレスに紐付けられています。

新しいユーザーにアカウント作成を求めずにアプリケーション / 組織へ招待したい場合があります。そのような場合、アプリケーションは「マジックリンク」をメールで送信できます。リンクをクリックすると、即座に認証 (Authentication) されます。

アプリケーション開発者はワンタイムトークンを使ってマジックリンクを作成し、エンドユーザーのメールアドレスに送信できます。

ユースケース​

Logto はマジックリンクで次のシナリオをサポートしています：

  • 招待制登録：社内ツールやテスト段階の AI プロダクトなどで、公開登録を無効にし、特定のユーザーにマジックリンクで招待できます。
  • 組織メンバー招待：SaaS プロダクトで、マジックリンクを使って新しいメンバーを組織に招待し、オンボーディングを効率化できます。
  • サインイン / サインアップ：メール経由でパスワードレスのサインインやサインアップ用にマジックリンクを送信できます。

例えば、公開登録を無効にしている場合、ワンタイムトークン付きのマジックリンク（例： https://yourapp.com/landing-page?token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&email=user@example.com ）をユーザーのメールに送信し、アカウント作成を完了するよう招待できます。メールテンプレートは独自のメール配信サービスでカスタマイズ可能です。例：

招待制登録用メールテンプレート

現在サポートされていないもの：

  • マジックリンクによるパスワードリセット
  • 電話番号やユーザー名を識別子として使用すること

ワンタイムトークンフロー​

ワンタイムトークンを使った認証 (Authentication) フローのシーケンス図は以下の通りです：

実装ガイド​

Logto は、マジックリンク実装を容易にするために Management API および Experience API を提供しています。

始める前に、Logto インスタンスが準備できていること、アプリケーションサーバーと Logto エンドポイント間でマシン間通信 (M2M) 接続が確立されていること（Management API に必要）を確認してください。詳しくは Logto Management API をご覧ください。

ステップ 1: ワンタイムトークンをリクエスト​

Logto Management API を使ってワンタイムトークンを作成します。

POST /api/one-time-tokens

リクエストボディの例：

{
  "email": "user@example.com",
  // オプション。デフォルトは 600（10 分）。
  "expiresIn": 3600,
  // オプション。検証成功時に指定した組織へユーザーをプロビジョニングします。
  "context": {
    "jitOrganizationIds": ["abcdefgh1234"]
  }
}

ワンタイムトークンを取得したら、マジックリンクを作成し、エンドユーザーのメールアドレスに送信できます。 マジックリンクには少なくともトークンとユーザーのメールアドレスをパラメータとして含め、アプリケーション内のランディングページへ遷移させる必要があります。 例： https://yourapp.com/landing-page

マジックリンクの例：

https://yourapp.com/landing-page?token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&email=user@example.com
注記:

マジックリンク内のパラメータ名は完全にカスタマイズ可能です。 アプリケーションの要件に応じて追加情報をマジックリンクに含めたり、すべての URL パラメータをエンコードしたりできます。

ステップ 3: Logto SDK で認証 (Authentication) フローを開始​

エンドユーザーがマジックリンクをクリックしてアプリケーションに遷移した後、URL から token と email パラメータを抽出し、Logto SDK の signIn() 関数を呼び出して認証 (Authentication) フローを開始できます。

TokenLandingPage.tsx
// React の例
import { useLogto } from '@logto/react';
import { useEffect } from 'react';
import { useSearchParams } from 'react-router-dom';

const TokenLandingPage = () => {
  const { signIn } = useLogto();
  const [searchParams] = useSearchParams();

  useEffect(() => {
    // マジックリンクからトークンとメールを抽出
    const oneTimeToken = searchParams.get('token');
    const email = searchParams.get('email');

    // これはサインインリダイレクト URI の例
    const redirectUri = 'https://yourapp.com/callback';

    if (oneTimeToken && email) {
      signIn({
        redirectUri,
        clearTokens: false, // オプション。下記の警告メッセージ参照
        extraParams: {
          'one_time_token': oneTimeToken,
          'login_hint': email,
        },
      });
    }
  }, [searchParams, signIn]);

  return <>お待ちください...</>;
};
警告:

すでにユーザーがサインインしている場合、SDK の signIn() 関数を呼び出すと、クライアントストレージからすべてのキャッシュ済みトークン（ID トークン、アクセス トークン、リフレッシュ トークン）が自動的にクリアされ、 現在のユーザーの認証 (Authentication) 状態が失われます。

そのため、既存のトークンをクリアしないように追加のサインインパラメータ clearTokens: false を指定してください。 この場合、サインインコールバックページで手動でトークンをクリアする必要があります。

マジックリンクが認証 (Authentication) 済みユーザー向けでない場合は、この注意事項は無視してください。

ステップ 4: （オプション）サインインコールバックページでキャッシュ済みトークンをクリア​

サインイン関数で clearTokens: false を指定した場合、サインインコールバックページで手動でトークンをクリアする必要があります。

Callback.tsx
// React の例
import { useHandleSignInCallback, useLogto } from '@logto/react';
import { useEffect } from 'react';

const Callback = () => {
  const { clearAllTokens } = useLogto();

  useEffect(() => {
    void clearAllTokens();
  }, [clearAllTokens]);

  useHandleSignInCallback(() => {
    // ホームページへ遷移
  });

  return <>お待ちください...</>;
};

よくある質問​

はい、マジックリンクを使ってアプリケーションだけでなく組織にも新しいユーザーを招待できます。 組織に新しいユーザーを招待したい場合は、リクエストボディで jitOrganizationIds を指定してください。

ユーザーは検証成功時に自動的に組織に参加し、デフォルトの組織ロールが割り当てられます。 組織詳細ページの「ジャストインタイムプロビジョニング」セクションで、組織のデフォルトロールを設定できます。

マジックリンク認証 (Authentication) フローでは、ユーザーへのロール割り当てはサポートされていません。ただし、Webhook や Management API を使って、ユーザー登録後にロールを更新できます。

ワンタイムトークンは有効期限がありますか？​

はい、ワンタイムトークンは指定した expiresIn 時間（秒）で有効期限が切れます。デフォルトの有効期限は 10 分です。

はい、「サインアップとサインイン」でユーザー登録を無効にしても、マジックリンクでユーザーを招待できます。

いくつかのシナリオが考えられます：

  1. すでにサインインしているユーザーが、現在のアカウントに紐付いたマジックリンクをクリックした場合。この場合、Logto はワンタイムトークンを検証し、必要に応じて組織へのプロビジョニングを行います。
  2. すでにサインインしているユーザーが、別のアカウントに紐付いたマジックリンクをクリックした場合。この場合、Logto は新しいアカウントで続行するか、現在のアカウントでアプリケーションに戻るかをユーザーに促します。
    1. ユーザーが新しいアカウントで続行を選択した場合、トークン検証が成功すると新しいアカウントに切り替わります。
    2. 現在のアカウントを維持する場合、Logto はトークンを検証せず、現在のアカウントでアプリケーションに戻ります。
  3. サインインプロンプトが "login" または "login" を含む場合、Logto は切り替えを促さず、ワンタイムトークンに紐付いたアカウントで自動的にサインインします。これは "login" プロンプトが明示的な認証 (Authentication) 意図を示しており、現在のセッションより優先されるためです。