あなたの React アプリケーションに認証 (Authentication) を追加する

このガイドでは、Logto をあなたの React アプリケーションに統合する方法を紹介します。

ヒント:

サンプルプロジェクトは、私たちの SDK リポジトリで利用可能です。
チュートリアルビデオは、私たちの YouTube チャンネルで視聴できます。

前提条件

Logto Cloud アカウントまたはセルフホスト Logto。
Logto コンソールで作成されたシングルページアプリケーション (SPA)。
React プロジェクト。

インストール

お好みのパッケージマネージャーを使用して Logto SDK をインストールします：

npm
pnpm
yarn

npm i @logto/react

pnpm add @logto/react

yarn add @logto/react

統合

Logto プロバイダーの初期化

LogtoProvider をインポートして使用し、Logto コンテキストをアプリに提供します：

App.tsx
import { LogtoProvider, LogtoConfig } from '@logto/react';

const config: LogtoConfig = {
  endpoint: '<your-logto-endpoint>', // 例: http://localhost:3001
  appId: '<your-application-id>',
};

const App = () => (
  <LogtoProvider config={config}>
    <YourAppContent />
  </LogtoProvider>
);

リダイレクト URI の設定

詳細に入る前に、エンドユーザーの体験について簡単に説明します。サインインプロセスは次のように簡略化できます：

あなたのアプリがサインインメソッドを呼び出します。
ユーザーは Logto のサインインページにリダイレクトされます。ネイティブアプリの場合、システムブラウザが開かれます。
ユーザーがサインインし、あなたのアプリにリダイレクトされます（リダイレクト URI として設定されています）。

リダイレクトベースのサインインについて

この認証 (Authentication) プロセスは OpenID Connect (OIDC) プロトコルに従い、Logto はユーザーのサインインを保護するために厳格なセキュリティ対策を講じています。
複数のアプリがある場合、同じアイデンティティプロバイダー (Logto) を使用できます。ユーザーがあるアプリにサインインすると、Logto は別のアプリにアクセスした際に自動的にサインインプロセスを完了します。

リダイレクトベースのサインインの理論と利点について詳しく知るには、Logto サインイン体験の説明を参照してください。

注記:

以下のコードスニペットでは、あなたのアプリが http://localhost:3000/ で実行されていると仮定しています。

リダイレクト URI を設定する

Logto Console のアプリケーション詳細ページに移動します。リダイレクト URI http://localhost:3000/callback を追加します。

サインインと同様に、ユーザーは共有セッションからサインアウトするために Logto にリダイレクトされるべきです。完了したら、ユーザーをあなたのウェブサイトに戻すと良いでしょう。例えば、http://localhost:3000/ をサインアウト後のリダイレクト URI セクションとして追加します。

その後、「保存」をクリックして変更を保存します。

リダイレクトの処理

http://localhost:3000/callback をリダイレクト URI として使用しているため、これを適切に処理する必要があります。

まず、コールバックページを作成しましょう：

pages/Callback/index.tsx
import { useHandleSignInCallback } from '@logto/react';

const Callback = () => {
  const { isLoading } = useHandleSignInCallback(() => {
    // 完了したときに何かを行う、例えばホームページにリダイレクトする
  });

  // 処理中の場合
  if (isLoading) {
    return <div>リダイレクト中...</div>;
  }

  return null;
};

最後に、認証を必要としない /callback ルートを作成するために、以下のコードを挿入します：

App.tsx
// react-router を想定
<Route path="/callback" element={<Callback />} />

サインインとサインアウトの実装

認証 (Authentication) フローを簡単に管理できるように、2 つのフック useHandleSignInCallback() と useLogto() を提供しています。

注記:

.signIn() を呼び出す前に、Admin Console でリダイレクト URI が正しく設定されていることを確認してください。 :::

pages/Home/index.tsx
import { useLogto } from '@logto/react';

const Home = () => {
  const { signIn, signOut, isAuthenticated } = useLogto();

  return isAuthenticated ? (
    <button onClick={signOut}>Sign Out</button>
  ) : (
    <button onClick={() => signIn('http://localhost:3000/callback')}>Sign In</button>
  );
};

.signOut() を呼び出すと、存在する場合、メモリと localStorage 内のすべての Logto データがクリアされます。

チェックポイント: アプリケーションをテストする

これで、アプリケーションをテストできます：

アプリケーションを実行すると、サインインボタンが表示されます。
サインインボタンをクリックすると、SDK がサインインプロセスを初期化し、Logto のサインインページにリダイレクトされます。
サインインすると、アプリケーションに戻り、サインアウトボタンが表示されます。
サインアウトボタンをクリックしてローカルストレージをクリアし、サインアウトします。

ユーザー情報の取得

ユーザー情報を表示する

ユーザーの情報を表示するには、getIdTokenClaims() メソッドを使用できます。例えば、ホームページで：

pages/Home/index.tsx
import { useLogto, type IdTokenClaims } from '@logto/react';
import { useEffect, useState } from 'react';

const Home = () => {
  const { isAuthenticated, getIdTokenClaims } = useLogto();
  const [user, setUser] = useState<IdTokenClaims>();

  useEffect(() => {
    (async () => {
      if (isAuthenticated) {
        const claims = await getIdTokenClaims();
        setUser(claims);
      }
    })();
  }, [getIdTokenClaims, isAuthenticated]);

  return (
    // ...
    {isAuthenticated && user && (
      <table>
        <thead>
          <tr>
            <th>名前</th>
            <th>値</th>
          </tr>
        </thead>
        <tbody>
          {Object.entries(user).map(([key, value]) => (
            <tr key={key}>
              <td>{key}</td>
              <td>{typeof value === 'string' ? value : JSON.stringify(value)}</td>
            </tr>
          ))}
        </tbody>
      </table>
    )}
  );
}

追加のクレーム (Claims) をリクエストする

getIdTokenClaims() から返されるオブジェクトに一部のユーザー情報が欠けていることがあります。これは、OAuth 2.0 と OpenID Connect (OIDC) が最小特権の原則 (PoLP) に従うように設計されており、Logto はこれらの標準に基づいて構築されているためです。

デフォルトでは、限られたクレーム (Claim) が返されます。より多くの情報が必要な場合は、追加のスコープ (Scope) をリクエストして、より多くのクレーム (Claim) にアクセスできます。

備考:

「クレーム (Claim)」はサブジェクトについての主張であり、「スコープ (Scope)」はクレーム (Claim) のグループです。現在のケースでは、クレーム (Claim) はユーザーに関する情報の一部です。

スコープ - クレーム (Claim) 関係の非規範的な例を示します：

ヒント:

「sub」クレーム (Claim) は「サブジェクト (Subject)」を意味し、ユーザーの一意の識別子（つまり、ユーザー ID）です。

Logto SDK は常に 3 つのスコープ (Scope) をリクエストします：openid、profile、および offline_access。

追加のスコープをリクエストするには、Logto プロバイダーの設定を構成できます：

App.tsx
import { LogtoConfig, UserScope } from '@logto/react';

const config: LogtoConfig = {
  // ...他の設定
  scopes: [
    UserScope.Email,
    UserScope.Phone,
    UserScope.CustomData,
    UserScope.Identities,
    UserScope.Organizations,
  ],
};

その後、getIdTokenClaims() の戻り値で追加のクレーム (Claims) にアクセスできます：

const claims = await getIdTokenClaims();
// 追加のクレーム (Claims) `claims.email`, `claims.phone` などにアクセスできます。

ネットワークリクエストが必要なクレーム (Claims)

ID トークンの肥大化を防ぐために、一部のクレーム (Claims) は取得するためにネットワークリクエストが必要です。例えば、custom_data クレームはスコープで要求されてもユーザーオブジェクトに含まれません。これらのクレームにアクセスするには、 fetchUserInfo() メソッドを使用できます：

const { fetchUserInfo } = useLogto();

const userInfo = await fetchUserInfo();

// クレーム (Claim) `userInfo.custom_data` にアクセスできます。

このメソッドは、userinfo エンドポイントにリクエストを送信してユーザー情報を取得します。利用可能なスコープとクレームについて詳しくは、スコープとクレームのセクションを参照してください。

スコープとクレーム (Claims)

Logto は OIDC のスコープとクレームの規約を使用して、ID トークンおよび OIDC userinfo エンドポイントからユーザー情報を取得するためのスコープとクレームを定義します。「スコープ」と「クレーム」は、OAuth 2.0 および OpenID Connect (OIDC) 仕様からの用語です。

サポートされているスコープと対応するクレーム (Claims) のリストはこちらです：

openid

クレーム名	タイプ	説明	ユーザー情報が必要か？
sub	`string`	ユーザーの一意の識別子	いいえ

profile

クレーム名	タイプ	説明	ユーザー情報が必要か？
name	`string`	ユーザーのフルネーム	いいえ
username	`string`	ユーザーのユーザー名	いいえ
picture	`string`	エンドユーザーのプロフィール写真の URL。この URL は、画像を含む Web ページではなく、画像ファイル（例えば PNG、JPEG、または GIF 画像ファイル）を指す必要があります。この URL は、エンドユーザーを説明する際に表示するのに適したプロフィール写真を特に参照するべきであり、エンドユーザーが撮影した任意の写真を参照するべきではありません。	いいえ
created_at	`number`	エンドユーザーが作成された時間。時間は Unix エポック（1970-01-01T00:00:00Z）からのミリ秒数で表されます。	いいえ
updated_at	`number`	エンドユーザーの情報が最後に更新された時間。時間は Unix エポック（1970-01-01T00:00:00Z）からのミリ秒数で表されます。	いいえ

その他の標準クレームには、family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo、および locale が含まれ、ユーザー情報エンドポイントを要求することなく profile スコープに含まれます。上記のクレームと異なる点は、これらのクレームは値が空でない場合にのみ返されることであり、上記のクレームは値が空の場合に null を返します。

注記:

標準クレームとは異なり、created_at と updated_at クレームは秒ではなくミリ秒を使用しています。

email

クレーム名	タイプ	説明	ユーザー情報が必要か？
email	`string`	ユーザーのメールアドレス	いいえ
email_verified	`boolean`	メールアドレスが確認済みかどうか	いいえ

phone

クレーム名	タイプ	説明	ユーザー情報が必要か？
phone_number	`string`	ユーザーの電話番号	いいえ
phone_number_verified	`boolean`	電話番号が確認済みかどうか	いいえ

address

住所クレームの詳細については、OpenID Connect Core 1.0 を参照してください。

custom_data

クレーム名	タイプ	説明	ユーザー情報が必要か？
custom_data	`object`	ユーザーのカスタムデータ	はい

identities

クレーム名	タイプ	説明	ユーザー情報が必要か？
identities	`object`	ユーザーのリンクされたアイデンティティ	はい
sso_identities	`array`	ユーザーのリンクされた SSO アイデンティティ	はい

urn:logto:scope:organizations

クレーム名	タイプ	説明	ユーザー情報が必要か？
organizations	`string[]`	ユーザーが所属する組織の ID	いいえ
organization_data	`object[]`	ユーザーが所属する組織のデータ	はい

urn:logto:scope:organization_roles

クレーム名	タイプ	説明	ユーザー情報が必要か？
organization_roles	`string[]`	ユーザーが所属する組織のロールで、`<organization_id>:<role_name>` の形式	いいえ

パフォーマンスとデータサイズを考慮して、「ユーザー情報が必要か？」が「はい」の場合、クレームは ID トークンに表示されず、ユーザー情報エンドポイントのレスポンスで返されます。

API リソース

まず 🔐 ロールベースのアクセス制御 (RBAC) を読むことをお勧めします。これにより、Logto の RBAC の基本概念と API リソースを適切に設定する方法を理解できます。

Logto クライアントを設定する

API リソースを設定したら、アプリで Logto を設定する際にそれらを追加できます：

App.tsx
import { LogtoConfig } from '@logto/react';

const config: LogtoConfig = {
  // ...other configs
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // API リソースを追加
};

各 API リソースには独自の権限 (スコープ) があります。

例えば、https://shopping.your-app.com/api リソースには shopping:read と shopping:write の権限があり、https://store.your-app.com/api リソースには store:read と store:write の権限があります。

これらの権限を要求するには、アプリで Logto を設定する際にそれらを追加できます：

App.tsx
import { LogtoConfig } from '@logto/react';

const config: LogtoConfig = {
  // ...other configs
  scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};

スコープが API リソースとは別に定義されていることに気付くかもしれません。これは、OAuth 2.0 のリソースインジケーターが、リクエストの最終的なスコープはすべてのターゲットサービスでのすべてのスコープの直積になると指定しているためです。

したがって、上記のケースでは、Logto での定義からスコープを簡略化できます。両方の API リソースは、プレフィックスなしで read と write スコープを持つことができます。その後、Logto の設定では：

App.tsx
import { LogtoConfig } from '@logto/react';

const config: LogtoConfig = {
  // ...other configs
  scopes: ['read', 'write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};

各 API リソースは、read と write の両方のスコープを要求します。

注記:

API リソースで定義されていないスコープを要求しても問題ありません。例えば、API リソースに email スコープが利用できなくても、email スコープを要求できます。利用できないスコープは安全に無視されます。

サインインが成功すると、Logto はユーザーのロールに応じて適切なスコープを API リソースに発行します。

API リソースのアクセストークンを取得する

特定の API リソースのアクセストークンを取得するには、getAccessToken メソッドを使用できます：

pages/Home/index.tsx
import { useLogto } from '@logto/react';

const Home = () => {
  const { isAuthenticated, getAccessToken } = useLogto();
  const [accessToken, setAccessToken] = useState('');

  useEffect(() => {
    (async () => {
      if (isAuthenticated) {
        const token = await getAccessToken('https://shopping.your-app.com/api');
        setAccessToken(token);
      }
    })();
  }, [isAuthenticated, getAccessToken]);

  return <p>{{ accessToken }}</p>;
};

このメソッドは、ユーザーが関連する権限を持っている場合に API リソースにアクセスするために使用できる JWT アクセストークンを返します。現在キャッシュされているアクセストークンが期限切れの場合、このメソッドは自動的にリフレッシュトークンを使用して新しいアクセストークンを取得しようとします。

組織トークンを取得する

組織 (Organization) が初めての場合は、🏢 組織 (マルチテナンシー) を読んで始めてください。

Logto クライアントを設定する際に、UserScope.Organizations スコープを追加する必要があります：

App.tsx
import { LogtoConfig, UserScope } from '@logto/react';

const config: LogtoConfig = {
  // ...other configs
  scopes: [UserScope.Organizations],
};

ユーザーがサインインしたら、ユーザーのための組織トークンを取得できます：

pages/Organizations/index.tsx
import { useLogto } from '@logto/react';
import { useEffect, useState } from 'react';

const Organizations = () => {
  const { isAuthenticated, getOrganizationToken, getIdTokenClaims } = useLogto();
  const [organizationIds, setOrganizationIds] = useState<string[]>();

  useEffect(() => {
    (async () => {
      if (!isAuthenticated) {
        return;
      }
      const claims = await getIdTokenClaims();

      console.log('ID トークン クレーム', claims);
      setOrganizationIds(claims?.organizations);
    })();
  }, [isAuthenticated, getIdTokenClaims]);

  return (
    <section>
      <ul>
        {organizationIds?.map((organizationId) => {
          return (
            <li key={organizationId}>
              <span>{organizationId}</span>
              <button
                type="button"
                onClick={async () => {
                  console.log('raw token', await getOrganizationToken(organizationId));
                }}
              >
                トークンを取得 (コンソールを参照)
              </button>
            </li>
          );
        })}
      </ul>
    </section>
  );
};

export default Organizations;

アクセストークンをリクエストヘッダーに添付する

トークンを HTTP ヘッダーの Authorization フィールドに Bearer 形式 (Bearer YOUR_TOKEN) で入れれば準備完了です。

注記:

Bearer トークンの統合フローは、使用しているフレームワークやリクエスターによって異なる場合があります。リクエスト Authorization ヘッダーを適用する独自の方法を選択してください。

さらなる読み物

エンドユーザーフロー：認証 (Authentication) フロー、アカウントフロー、組織フローコネクターを設定するあなたの API を保護する

前提条件​

インストール​

統合​

Logto プロバイダーの初期化​

リダイレクト URI の設定​

リダイレクトベースのサインインについて​

リダイレクト URI を設定する​

リダイレクトの処理​

サインインとサインアウトの実装​

チェックポイント: アプリケーションをテストする​

ユーザー情報の取得​

ユーザー情報を表示する​

追加のクレーム (Claims) をリクエストする​

ネットワークリクエストが必要なクレーム (Claims)​

スコープとクレーム (Claims)​

API リソース​

Logto クライアントを設定する​

API リソースのアクセス トークンを取得する​

組織トークンを取得する​

アクセス トークンをリクエストヘッダーに添付する​

さらなる読み物​