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

このガイドでは、Logto を PHP ウェブアプリケーションに統合する方法を示します。

ヒント:

例は Laravel を使用していますが、他のフレームワークでも概念は同じです。

前提条件

Logto Cloud アカウントまたはセルフホスト型 Logto （持っていない場合は Introduction ガイドを参照して作成してください）。
Logto の従来の Web アプリケーションが作成されていること。

インストール

composer require logto/sdk

統合

LogtoClient の初期化

まず、Logto の設定を作成します：

index.php
use Logto\Sdk\LogtoClient;
use Logto\Sdk\LogtoConfig;

$client = new LogtoClient(
  new LogtoConfig(
    endpoint: "https://you-logto-endpoint.app",
    appId: "replace-with-your-app-id",
    appSecret: "replace-with-your-app-secret",
  ),
);

ヒント:

「App Secret」は管理コンソールのアプリケーション詳細ページから見つけてコピーできます：

デフォルトでは、SDK は組み込みの PHP セッションを使用して Logto データを保存します。他のストレージを使用したい場合は、カスタムストレージオブジェクトを 2 番目のパラメーターとして渡すことができます：

index.php
$client = new LogtoClient(
  new LogtoConfig(
    // ...
  ),
  new YourCustomStorage(),
);

詳細については、Storage を参照してください。

リダイレクト 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 はユーザーを Logto コンソールで設定したコールバック URL にリダイレクトします。この例では、/callback をコールバック URL として使用します：

Route::get('/callback', function () {
  try {
    $client->handleSignInCallback(); // 多くの処理を行います
  } catch (\Throwable $exception) {
    return $exception; // これをエラーハンドリングロジックに変更してください
  }
  return redirect('/'); // サインインが成功した後、ユーザーをホームページにリダイレクトします
});

サインインルートの実装

あなたの Web アプリケーションで、ユーザーからのサインインリクエストを適切に処理するためのルートを追加します。例えば：

Route::get('/sign-in', function () {
return redirect($client->signIn('http://localhost:3000/callback'));
});

このアプリケーションのために Logto コンソールで設定したコールバック URL に http://localhost:3000/callback を置き換えてください。

最初の画面にサインアップページを表示したい場合は、interactionMode を signUp に設定できます：

Route::get('/sign-in', function () {
return redirect($client->signIn('http://localhost:3000/callback', InteractionMode::signUp));
});

これで、ユーザーが http://localhost:3000/sign-in を訪れるたびに、新しいサインイン試行が開始され、ユーザーは Logto のサインインページにリダイレクトされます。

注意サインインルートを作成することは、サインイン試行を開始する唯一の方法ではありません。常に signIn メソッドを使用してサインイン URL を取得し、ユーザーをそれにリダイレクトすることができます。

サインアウトルートの実装

ユーザーがサインアウトリクエストを行った後、Logto はセッション内のすべてのユーザー認証 (Authentication) 情報をクリアします。

PHP セッションと Logto セッションをクリーンアップするために、次のようにサインアウトルートを実装できます：

Route::get('/sign-out', function () {
return redirect(
  // サインアウトが成功した後、ユーザーをホームページにリダイレクトします
  $client->signOut('http://localhost:3000/')
);
});

postLogoutRedirectUri はオプションであり、提供されない場合、ユーザーはサインアウトが成功した後に Logto のデフォルトページにリダイレクトされます（あなたのアプリケーションに戻るリダイレクトは行われません）。

注 > postLogoutRedirectUri という名前は、OpenID Connect RP-Initiated Logout 仕様から来ています。Logto は「サインアウト」を「ログアウト」の代わりに使用していますが、概念は同じです。

認証 (Authentication) ステータスの処理

Logto SDK では、$client->isAuthenticated() を使用して認証 (Authentication) ステータスを確認できます。ユーザーがサインインしている場合、この値は true になります。そうでない場合、この値は false になります。

デモ用にホームページを実装する必要があります：

ユーザーがサインインしていない場合、サインインボタンを表示します。
ユーザーがサインインしている場合、サインアウトボタンを表示します。

Route::get('/', function () {
  if ($client->isAuthenticated() === false) {
    return "Not authenticated <a href='/sign-in'>Sign in</a>";
  }

  return "<a href='/sign-out'>Sign out</a>";
});

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

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

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

ユーザー情報の取得

ユーザー情報の表示

ユーザーの情報を表示するには、getIdTokenClaims メソッドまたは fetchUserInfo メソッドを使用してユーザー情報を取得できます。getIdTokenClaims は ID トークンに含まれるユーザー情報を返し、fetchUserInfo は userinfo エンドポイントからユーザー情報を取得します。

index.php
Route::get('/userinfo', function () {
  if ($client->isAuthenticated() === false) {
    return "認証されていません <a href='/sign-in'>サインイン</a>";
  }

  return (
    // ローカル ID トークンのクレームを取得
    json_decode($client->getIdTokenClaims())
    . "<br>"
    // Logto userinfo エンドポイントからユーザー情報を取得
    json_decode($client->fetchUserInfo())
  );
});

私たちのデータモデルは JsonModel に基づいており、JSON のエンコードまたはデコード時に未定義のキーを受け入れることが安全です。

null 値のフィールド（クレーム）は、そのフィールドが設定されていることを意味しません。関連するスコープが要求されていないか、ユーザーがそのフィールドを持っていない可能性があります。

例えば、サインイン時に email スコープを要求しなかった場合、email フィールドは null になります。しかし、email スコープを要求した場合、email フィールドは利用可能であればユーザーのメールアドレスになります。

追加のクレームを要求する

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 クライアントを初期化する際に scopes オプションを設定できます：

index.php
$client = new LogtoClient(
  new LogtoConfig(
    // ...他の設定
    scopes: ["email", "phone"], // 必要に応じて更新
  ),
);

または、UserScope enum を使用してスコープを追加することもできます：

index.php
use Logto\Sdk\Constants\UserScope;

$client = new LogtoClient(
  new LogtoConfig(
    // ...他の設定
    scopes: [UserScope::email, UserScope::phone], // 必要に応じて更新
  ),
);

その後、追加のクレームは getIdTokenClaims または fetchUserInfo の戻り値で利用可能になります。

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

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

index.php
$client->fetchUserInfo()->custom_data;

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

スコープとクレーム

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

index.php
$client = new LogtoClient(
  new 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 を設定する際にそれらを追加できます：

index.php
$client = new LogtoClient(
  new 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 リソースを追加
  ),
);

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

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

index.php
$client = new LogtoClient(
  new LogtoConfig(
    // ...other configs
    scopes: ["read", "write"], // スコープを追加
    resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"], // API リソースを追加
  ),
);

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

注記:

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

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

API リソースのためのアクセストークンの取得

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

index.php
$accessToken = $client->getAccessToken("https://shopping.your-app.com/api");

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

組織トークンの取得

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

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

use Logto\Sdk\Constants\UserScope;

$client = new LogtoClient(
  new LogtoConfig(
    // ...other configs
    scopes: [UserScope::organizations], // スコープを追加
  ),
);

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

index.php
# パラメーターを有効な組織 ID に置き換えてください。
# ユーザーの有効な組織 ID は、ID トークンのクレーム `organizations` にあります。
$organizationToken = $client->getOrganizationToken(organization_id);
# または
$claims = $client->getOrganizationTokenClaims(organization_id);

さらなる読み物

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

前提条件​

インストール​

統合​

LogtoClient の初期化​

リダイレクト URI の設定​

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

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

コールバックの処理​

サインインルートの実装​

サインアウトルートの実装​

認証 (Authentication) ステータスの処理​

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

ユーザー情報の取得​

ユーザー情報の表示​

追加のクレームを要求する​

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

スコープとクレーム​

API リソースと組織​

Logto クライアントの設定​

API リソースのためのアクセス トークンの取得​

組織トークンの取得​

さらなる読み物​

前提条件

インストール

統合

LogtoClient の初期化

リダイレクト URI の設定

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

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

コールバックの処理

サインインルートの実装

サインアウトルートの実装

認証 (Authentication) ステータスの処理

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

ユーザー情報の取得

ユーザー情報の表示

追加のクレームを要求する

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

スコープとクレーム

API リソースと組織

Logto クライアントの設定

API リソースのためのアクセストークンの取得

組織トークンの取得

さらなる読み物