SvelteKit アプリケーションへ認証機能の追加

ヒント:

• 以下のデモンストレーションは SvelteKit 2.0.0 に基づいています。
• サンプルプロジェクトは GitHub リポジトリ で利用可能です。

前提条件

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

インストール

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

npm

npm i @logto/sveltekit

pnpm

pnpm add @logto/sveltekit

yarn

yarn add @logto/sveltekit

統合

Logto フックを追加する

hooks.server.ts ファイルに、次のコードを追加して Logto フックをサーバーに注入します：

hooks.server.ts

import { handleLogto } from '@logto/sveltekit';

export const handle = handleLogto(
  {
    endpoint: '<your-logto-endpoint>',
    appId: '<your-logto-app-id>',
    appSecret: '<your-logto-app-secret>',
  },
  {
    encryptionKey: '<a-random-string>',
  }
);

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

hooks.server.ts

import { handleLogto } from '@logto/sveltekit';
import { env } from '$env/dynamic/private';

export const handle = handleLogto(
  {
    endpoint: env.LOGTO_ENDPOINT,
    appId: env.LOGTO_APP_ID,
    appSecret: env.LOGTO_APP_SECRET,
  },
  {
    encryptionKey: env.LOGTO_COOKIE_ENCRYPTION_KEY,
  }
);

複数のフックがある場合は、sequence() ヘルパー関数 を使用してそれらを連鎖させることができます：

hooks.server.ts

import { sequence } from '@sveltejs/kit/hooks';

export const handle = sequence(handleLogto, handleOtherHook);

これで locals オブジェクトで Logto クライアントにアクセスできます。TypeScript の場合、app.d.ts に型を追加できます：

import type { LogtoClient, UserInfoResponse } from '@logto/sveltekit';

declare global {
  namespace App {
    interface Locals {
      logtoClient: LogtoClient;
      user?: UserInfoResponse;
    }
  }
}

user オブジェクトについては後で説明します。

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

注記:

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

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

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

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

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

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

---

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

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

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

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

サインインとサインアウトを実装したいページで、次のアクションを定義します：

+page.server.ts

import type { Actions } from './$types';

export const actions: Actions = {
  signIn: async ({ locals }) => {
    await locals.logtoClient.signIn('http://localhost:3000/callback');
  },
  signOut: async ({ locals }) => {
    await locals.logtoClient.signOut('http://localhost:3000/');
  },
};

次に、これらのアクションを Svelte コンポーネントで使用します：

+page.svelte

<form method="POST" action="?/{data.user ? 'signOut' : 'signIn'}">
  <button type="submit">Sign {data.user ? 'out' : 'in'}</button>
</form>

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

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

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

ユーザー情報の取得

ユーザー情報を表示する

ユーザーの情報を表示するには、locals.user オブジェクトをレイアウトに注入し、すべてのページで利用できるようにします：

+layout.server.ts

import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = async ({ locals }) => {
  return { user: locals.user };
};

Svelte コンポーネント内で：

+page.svelte

<script>
  /** @type {import('./$types').PageData} */
  export let data;
</script>

{#if data.user}
<ul>
  {#each Object.entries(data.user) as [key, value]}
  <li>{key}: {value}</li>
  {/each}
</ul>
{/if}

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

locals.user から返されるオブジェクトに一部のユーザー情報が欠けていることがあります。これは、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。

追加のスコープをリクエストするには、handleLogto 関数内の LogtoConfig オブジェクトにスコープを渡します：

hooks.server.ts

import { UserScope, handleLogto } from '@logto/sveltekit';

export const handle = handleLogto({
  // ...other options
  scopes: [UserScope.email, UserScope.phone], // 必要に応じてスコープを追加
});

その後、locals.user オブジェクトで追加のクレームにアクセスできます。

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

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

デフォルトでは、locals.user オブジェクトは getIdTokenClaims メソッドを手動で呼び出す便利な方法です。fetchUserInfo メソッドの結果を使用したい場合は、フックの fetchUserInfo オプションを true に設定することで可能です：

hooks.server.ts

import { handleLogto } from '@logto/sveltekit';

export const handle = handleLogto(
  {
    /* Logto config */
  },
  {
    /* Cookie config */
  },
  {
    fetchUserInfo: true,
  }
);

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

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

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

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

スコープとクレーム

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

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

openid

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

profile

クレーム名	タイプ	説明	ユーザー情報が必要か？
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）からのミリ秒数で表されます。	いいえ

その他の 標準クレーム には、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 アイデンティティ	はい

roles

クレーム名	タイプ	説明	ユーザー情報が必要か？
roles	string[]	ユーザーのロール	いいえ

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 を設定する際にそれらを追加できます：

hooks.server.ts

export const handle = handleLogto(
  {
    // ...other configs
    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 を設定する際にそれらを追加できます：

hooks.server.ts

export const handle = handleLogto(
  {
    // ...other configs
    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 の設定では：

hooks.server.ts

export const handle = handleLogto(
  {
    // ...other configs
    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 メソッドを使用できます：

const token = await locals.logtoClient.getAccessToken('https://shopping.your-app.com/api');

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

組織トークンを取得する

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

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

hooks.server.ts

import { handleLogto, UserScope } from '@logto/sveltekit';

export const handle = handleLogto(
  {
    // ...other configs
    scopes: [UserScope.Organizations],
  }
  // ...other configs
);

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

const token = await locals.logtoClient.getOrganizationToken(organizationId);

さらなる読み物

エンドユーザーフロー：認証 (Authentication) フロー、アカウントフロー、組織フロー コネクターの設定 認可 (Authorization)