あなたの 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 はこれらの標準に基づいて構築されているためです。

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

備考:

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

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

ヒント:

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

Logto SDK は常に 3 つのスコープ (Scopes) をリクエストします：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 のスコープ (Scope) とクレーム (Claim) の規約を使用して、ID トークンおよび OIDC userinfo エンドポイントからユーザー情報を取得するためのスコープ (Scope) とクレーム (Claim) を定義しています。「スコープ (Scope)」と「クレーム (Claim)」は、OAuth 2.0 および OpenID Connect (OIDC) 仕様の用語です。

標準の OIDC クレーム (Claim) については、ID トークンへの含有はリクエストされたスコープ (Scope) によって厳密に決定されます。拡張クレーム (Claim)（例：custom_data や organizations）は、カスタム ID トークン設定を通じて ID トークンに追加で表示するように構成できます。

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

標準 OIDC スコープ

openid（デフォルト）

Claim name	Type	説明
sub	`string`	ユーザーの一意の識別子

profile（デフォルト）

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

その他の標準クレーム (Standard Claims) には、family_name、given_name、middle_name、nickname、preferred_username、profile、website、gender、birthdate、zoneinfo、locale などがあり、これらも profile スコープに含まれます（userinfo エンドポイントをリクエストする必要はありません）。上記のクレームとの違いは、これらのクレームは値が空でない場合のみ返される点です。一方、上記のクレームは値が空の場合 null が返されます。

注記:

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

email

Claim name	Type	説明
email	`string`	ユーザーのメールアドレス
email_verified	`boolean`	メールアドレスが認証済みかどうか

phone

Claim name	Type	説明
phone_number	`string`	ユーザーの電話番号
phone_number_verified	`boolean`	電話番号が認証済みかどうか

address

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

備考:

（デフォルト） と記載されたスコープは常に Logto SDK によってリクエストされます。標準 OIDC スコープ下のクレーム (Claims) は、対応するスコープがリクエストされた場合、常に ID トークン (ID token) に含まれます — 無効化できません。

拡張スコープ

以下のスコープは Logto によって拡張されており、userinfo エンドポイントを通じてクレーム (Claims) を返します。これらのクレームは Console > Custom JWT を通じて ID トークン (ID token) に直接含めるよう設定することもできます。詳細はカスタム ID トークンを参照してください。

custom_data

Claim name	Type	説明	デフォルトで ID トークンに含まれるか
custom_data	`object`	ユーザーのカスタムデータ

identities

Claim name	Type	説明	デフォルトで ID トークンに含まれるか
identities	`object`	ユーザーのリンク済みアイデンティティ
sso_identities	`array`	ユーザーのリンク済み SSO アイデンティティ

roles

Claim name	Type	説明	デフォルトで ID トークンに含まれるか
roles	`string[]`	ユーザーのロール	✅

urn:logto:scope:organizations

Claim name	Type	説明	デフォルトで ID トークンに含まれるか
organizations	`string[]`	ユーザーが所属する組織 ID	✅
organization_data	`object[]`	ユーザーが所属する組織データ

注記:

これらの組織クレーム (Organization Claims) は、不透明トークン (Opaque token) を使用している場合でも userinfo エンドポイント経由で取得できます。ただし、不透明トークン (Opaque token) は組織トークン (Organization token) として組織固有リソースへのアクセスには使用できません。詳細は不透明トークン (Opaque token) と組織 (Organizations) を参照してください。

urn:logto:scope:organization_roles

Claim name	Type	説明	デフォルトで ID トークンに含まれるか
organization_roles	`string[]`	ユーザーが所属する組織ロール（`<organization_id>:<role_name>` 形式）	✅

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) フロー、アカウントフロー、組織フローコネクターの設定認可 (Authorization)

前提条件​

インストール​

統合​

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

リダイレクト URI の設定​

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

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

リダイレクトの処理​

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

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

ユーザー情報の取得​

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

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

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

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

標準 OIDC スコープ​

拡張スコープ​

API リソース​

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

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

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

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

さらなる読み物​