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

ヒント:

以下のデモンストレーションは Nuxt 3.10.2 に基づいています。
サンプルプロジェクトは GitHub リポジトリで利用可能です。
Logto Nuxt SDK は、正しく動作するためにサーバーサイドレンダリング (SSR) を必要とします。シングルページアプリケーション (SPA) の場合は、Vue SDK をご覧ください。

前提条件

Logto Cloud アカウントまたはセルフホスト Logto。
Logto の従来のウェブアプリケーションが作成されていること。

インストール

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

npm
pnpm
Yarn

npm i @logto/nuxt

pnpm add @logto/nuxt

yarn add @logto/nuxt

統合

Logto モジュールを登録する

Nuxt の設定ファイルに Logto モジュールを追加し、設定します：

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@logto/nuxt'],
  runtimeConfig: {
    logto: {
      endpoint: '<your-logto-endpoint>',
      appId: '<your-logto-app-id>',
      appSecret: '<your-logto-app-secret>',
      cookieEncryptionKey: '<a-random-string>',
    },
  },
  // ...他の設定
});

これらの情報は機密性が高いため、環境変数 (.env) を使用することをお勧めします：

.env
NUXT_LOGTO_ENDPOINT="<your-logto-endpoint>"
NUXT_LOGTO_APP_ID="<your-logto-app-id>"
NUXT_LOGTO_APP_SECRET="<your-logto-app-secret>"
NUXT_LOGTO_COOKIE_ENCRYPTION_KEY="<a-random-string>"

詳細については、ランタイム設定を参照してください。

リダイレクト 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 セクションとして追加します。

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

コールバックを処理する

コールバックルートを処理するための追加の設定は必要ありません。@logto/nuxt モジュールを登録すると、次のことが行われます：

サインイン (/sign-in)、サインアウト (/sign-out)、およびコールバック (/callback) の 3 つのルートを追加します。
2 つのコンポーザブルをインポートします：useLogtoClient と useLogtoUser。

これらのルートは、モジュールオプションの logto.pathnames で設定可能です。例えば：

nuxt.config.ts
export default defineNuxtConfig({
  logto: {
    pathnames: {
      signIn: '/login',
      signOut: '/logout',
      callback: '/auth/callback',
    },
  },
  // ...他の設定
});

@logto/nuxt パッケージの型定義ファイルを確認してください。

注記:

コールバックルートを別のパスに設定する場合は、Logto でリダイレクト URI を更新する必要があります。

サインインとサインアウトを実装する

Nuxt ページは初期ロード後にシングルページアプリケーション (SPA) としてハイドレートされるため、必要に応じてユーザーをサインインまたはサインアウトルートにリダイレクトする必要があります。これを支援するために、SDK は useLogtoUser() コンポーザブルを提供しており、サーバーサイドとクライアントサイドの両方で使用できます。

index.vue
<script setup lang="ts">
  import { useLogtoUser } from '#imports'; // 自動インポートが無効な場合はこの行を追加
  const user = useLogtoUser();
</script>
<template>
  <!-- サインインとサインアウトのための簡略化されたボタン -->
  <nuxt-link :to="`/sign-${ user ? 'out' : 'in' }`"> Sign {{ user ? 'out' : 'in' }} </nuxt-link>
</template>

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

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

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

ユーザー情報を取得する

ユーザー情報の表示

ユーザーがサインインしているとき、useLogtoUser() の戻り値はユーザー情報を含むオブジェクトになります。この情報をアプリで表示できます：

index.vue
<script setup lang="ts">
  const user = useLogtoUser();
</script>
<template>
  <!-- サインイン時にユーザー情報を表示 -->
  <ul v-if="Boolean(user)">
    <li v-for="(value, key) in user"><b>{{ key }}:</b> {{ value }}</li>
  </ul>
  <!-- サインインとサインアウトの簡略化されたボタン -->
  <nuxt-link :to="`/sign-${ user ? 'out' : 'in' }`"> Sign {{ user ? 'out' : 'in' }} </nuxt-link>
</template>

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

useLogtoUser() から返されるオブジェクトに一部のユーザー情報が欠けていることがあります。これは、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 モジュールオプションを設定します：

nuxt.config.ts
import { UserScope } from '@logto/nuxt';

export default defineNuxtConfig({
  logto: {
    scopes: [UserScope.Email, UserScope.Phone], // 必要に応じてスコープを追加
    // ...その他の設定
  },
});

その後、user オブジェクトで追加のクレーム (Claims) にアクセスできます：

index.vue
<template>
  <div v-if="user">
    <p>Name: {{ user.name }}</p>
    <p>Email: {{ user.email }}</p>
    <p>Phone: {{ user.phone }}</p>
  </div>
</template>

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

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

nuxt.config.ts
export default defineNuxtConfig({
logto: {
  scopes: [UserScope.CustomData],
  fetchUserInfo: true,
},
// ...その他の設定
});

fetchUserInfo を設定することで、SDK はユーザーがサインインした後に userinfo エンドポイントにリクエストを送信してユーザー情報を取得し、リクエストが完了すると user.custom_data が利用可能になります。

ユーザー情報を手動で取得する

Logto クライアントが提供するすべてのメソッドにアクセスするには、useLogtoClient() コンポーザブルを使用します：

index.vue
const client = useLogtoClient();

警告:

Logto クライアントはサーバーサイドでのみ利用可能です。コンポーザブルはクライアントサイドでは undefined を返します。

これらの Logto メソッドを使用して、プログラムでユーザー情報を取得できます：

client.getIdTokenClaims(): ローカルの ID トークンをデコードしてユーザー情報を取得します。いくつかのクレームは利用できない場合があります。
client.fetchUserInfo(): userinfo エンドポイントにリクエストを送信してユーザー情報を取得します。

重要なのは、取得できるユーザー情報のクレームは、サインイン時にユーザーが使用したスコープに依存することです。パフォーマンスとデータサイズを考慮して、ID トークンにはすべてのユーザークレームが含まれていない場合があり、いくつかのユーザークレームは userinfo エンドポイントでのみ利用可能です（以下の関連リストを参照してください）。

例えば、ユーザー情報を手動で取得するには：

index.vue
import { useLogtoClient, useState, callOnce } from '#imports';

const client = useLogtoClient();
const userInfo = useState(null);

// クライアントサイドでの実行を防ぐために一度だけ呼び出す
await callOnce(async () => {
  if (!client) {
    throw new Error('Logto クライアントが利用できません');
  }

  if (!(await client.isAuthenticated())) {
    return;
  }

  try {
    userInfo.value = await client.fetchUserInfo();
  } catch (error) {
    console.error('ユーザー情報の取得に失敗しました:', error);
  }
});

スコープとクレーム (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 を設定する際にそれらを追加できます：

nuxt.config.ts
export default defineNuxtConfig({
  logto: {
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // API リソースを追加
    // ...other configs
  },
});

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

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

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

nuxt.config.ts
export default defineNuxtConfig({
  logto: {
    scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
    // ...other configs
  },
});

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

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

nuxt.config.ts
export default defineNuxtConfig({
  logto: {
    scopes: ['read', 'write'],
    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
    // ...other configs
  },
});

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

注記:

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

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

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

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

index.vue
<script setup lang="ts">
  // Logto クライアントにアクセスするためのコンポーザブル
  const client = useLogtoClient();
  // トークンをグローバルに利用可能にする
  const accessToken = useState<string | undefined>('access-token');

  // サーバーサイドで一度だけ呼び出す
  await callOnce(async () => {
    if (!client) {
      throw new Error('Logto client is not available');
    }

    if (!(await client.isAuthenticated())) {
      return;
    }

    try {
      accessToken.value = await client.getAccessToken('https://shopping.your-app.com/api');
    } catch (error) {
      console.error('Failed to get access token', error);
    }
  });
</script>

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

組織トークンを取得する

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

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

nuxt.config.ts
import { UserScope } from '@logto/nuxt';

export default defineNuxtConfig({
  logto: {
    scopes: [UserScope.Organizations],
    // ...other configs
  },
});

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

index.vue
const token = await client.getOrganizationToken(organizationId);

組織 API リソース

組織内の API リソースのアクセストークンを取得するには、getAccessToken メソッドを使用し、API リソースと組織 ID の両方をパラメーターとして渡します：

index.vue
const accessToken = await client.getAccessToken(
  'https://shopping.your-app.com/api',
  organizationId
);

さらなる読み物

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

前提条件​

インストール​

統合​

Logto モジュールを登録する​

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

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

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

コールバックを処理する​

サインインとサインアウトを実装する​

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

ユーザー情報を取得する​

ユーザー情報の表示​

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

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

ユーザー情報を手動で取得する​

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

API リソースと組織​

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

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

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

組織 API リソース​

さらなる読み物​

前提条件

インストール

統合

Logto モジュールを登録する

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

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

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

コールバックを処理する

サインインとサインアウトを実装する

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

ユーザー情報を取得する

ユーザー情報の表示

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

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

ユーザー情報を手動で取得する

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

API リソースと組織

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

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

組織トークンを取得する

組織 API リソース

さらなる読み物