あなたの .NET Core (Razor Pages) アプリケーションに認証 (Authentication) を追加する
- 次のデモンストレーションは .NET Core 8.0 を基に構築されています。SDK は .NET 6.0 以上に対応しています。
- .NET Core のサンプルプロジェクトは GitHub リポジトリ で利用可能です。
前提条件
- Logto Cloud アカウントまたは セルフホスト Logto。
- Logto 従来の Web アプリケーションが作成されていること。
インストール
プロジェクトに NuGet パッケージを追加します：
dotnet add package Logto.AspNetCore.Authentication
統合
Logto 認証 (Authentication) を追加する
Startup.cs（または Program.cs）を開き、次のコードを追加して Logto 認証 (Authentication) サービスを登録します：
using Logto.AspNetCore.Authentication;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddLogtoAuthentication(options =>
{
options.Endpoint = builder.Configuration["Logto:Endpoint"]!;
options.AppId = builder.Configuration["Logto:AppId"]!;
options.AppSecret = builder.Configuration["Logto:AppSecret"];
});
AddLogtoAuthentication メソッドは次のことを行います：
- デフォルトの認証 (Authentication) スキームを
LogtoDefaults.CookieSchemeに設定します。 - デフォルトのチャレンジスキームを
LogtoDefaults.AuthenticationSchemeに設定します。 - デフォルトのサインアウトスキームを
LogtoDefaults.AuthenticationSchemeに設定します。 - 認証 (Authentication) スキームにクッキーと OpenID Connect 認証 (Authentication) ハンドラーを追加します。
サインインおよびサインアウトフロー
進む前に、.NET Core 認証 (Authentication) ミドルウェアにおける混乱しやすい用語を 2 つ明確にする必要があります：
- CallbackPath: ユーザーがサインインした後に Logto がユーザーをリダイレクトする URI （Logto における「リダイレクト URI」）
- RedirectUri: Logto 認証 (Authentication) ミドルウェアで必要なアクションが実行された後にリダイレクトされる URI
サインインプロセスは次のように示されます：
同様に、.NET Core にはサインアウトフローのための SignedOutCallbackPath と RedirectUri もあります。
明確にするために、これらを次のように呼びます：
| 使用する用語 | .NET Core 用語 |
|---|---|
| Logto リダイレクト URI | CallbackPath |
| Logto サインアウト後リダイレクト URI | SignedOutCallbackPath |
| アプリケーションリダイレクト URI | RedirectUri |
リダイレクトベースのサインインについて
- この認証 (Authentication) プロセスは OpenID Connect (OIDC) プロトコルに従い、Logto はユーザーのサインインを保護するために厳格なセキュリティ対策を講じています。
- 複数のアプリがある場合、同じアイデンティティプロバイダー (Logto) を使用できます。ユーザーがあるアプリにサインインすると、Logto は別のアプリにアクセスした際に自動的にサインインプロセスを完了します。
リダイレクトベースのサインインの理論と利点について詳しく知るには、Logto サインイン体験の説明を参照してください。
リダイレクト URI を設定する
以下のコードスニペットでは、あなたのアプリが http://localhost:3000/ で実行されていると仮定しています。
まず、Logto リダイレクト URI を設定しましょう。次の URI を Logto アプリケーション詳細ページの「リダイレクト URI」リストに追加します：
http://localhost:3000/Callback
Logto サインアウト後リダイレクト URI を設定するには、次の URI を Logto アプリケーション詳細ページの「サインアウト後リダイレクト URI」リストに追加します：
http://localhost:3000/SignedOutCallback
デフォルトパスを変更する
Logto リダイレクト URI にはデフォルトパス /Callback があり、Logto サインアウト後リダイレクト URI にはデフォルトパス /SignedOutCallback があります。
特別な要件がない場合は、そのままにしておくことができます。変更したい場合は、LogtoOptions の CallbackPath と SignedOutCallbackPath プロパティを設定できます：
builder.Services.AddLogtoAuthentication(options =>
{
// 他の設定...
options.CallbackPath = "/Foo";
options.SignedOutCallbackPath = "/Bar";
});
Logto アプリケーション詳細ページの値もそれに応じて更新することを忘れないでください。
サインインおよびサインアウトボタンを実装する
まず、PageModel にハンドラーメソッドを追加します。例えば：
public class IndexModel : PageModel
{
public async Task OnPostSignInAsync()
{
await HttpContext.ChallengeAsync(new AuthenticationProperties
{
RedirectUri = "/"
});
}
public async Task OnPostSignOutAsync()
{
await HttpContext.SignOutAsync(new AuthenticationProperties
{
RedirectUri = "/"
});
}
}
次に、Razor ページにボタンを追加します：
<p>Is authenticated: @User.Identity?.IsAuthenticated</p>
<form method="post">
@if (User.Identity?.IsAuthenticated == true) {
<button type="submit" asp-page-handler="SignOut">Sign out</button>
} else {
<button type="submit" asp-page-handler="SignIn">Sign in</button>
}
</form>
ユーザーが認証 (Authentication) されていない場合は「Sign in」ボタンが表示され、認証 (Authentication) されている場合は「Sign out」ボタンが表示されます。
チェックポイント: アプリケーションをテストする
これで、アプリケーションをテストできます：
- アプリケーションを実行すると、サインインボタンが表示されます。
- サインインボタンをクリックすると、SDK がサインインプロセスを初期化し、Logto のサインインページにリダイレクトされます。
- サインインすると、アプリケーションに戻り、サインアウトボタンが表示されます。
- サインアウトボタンをクリックして、トークンストレージをクリアし、サインアウトします。
ユーザー情報を取得する
ユーザー情報の表示
ユーザーが認証 (Authentication) されているかどうかを確認するには、User.Identity?.IsAuthenticated プロパティをチェックできます。
ユーザープロファイルのクレームを取得するには、User.Claims プロパティを使用します：
var claims = User.Claims;
// ユーザー ID を取得
var userId = claims.FirstOrDefault(c => c.Type == LogtoParameters.Claims.Subject)?.Value;
クレーム名とその意味のリストについては、LogtoParameters.Claims を参照してください。
追加のクレームをリクエストする
User.Claims から返されるオブジェクトに一部のユーザー情報が欠けていることがあります。これは、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。
追加のスコープをリクエストするには、options オブジェクトの Scopes プロパティを設定できます：
builder.Services.AddLogtoAuthentication(options =>
{
// ...
options.Scopes = new string[] {
LogtoParameters.Scopes.Email,
LogtoParameters.Scopes.Phone
}
});
その後、User.Claims を介して追加のクレームにアクセスできます：
var claims = User.Claims;
// ユーザーのメールを取得
var email = claims.FirstOrDefault(c => c.Type == LogtoParameters.Claims.Email)?.Value;
ネットワークリクエストが必要なクレーム
ユーザーオブジェクトの肥大化を防ぐために、一部のクレームは取得するためにネットワークリクエストが必要です。たとえば、custom_data クレームはスコープでリクエストされていてもユーザーオブジェクトに含まれていません。これらのクレームを取得するには、options オブジェクトで GetClaimsFromUserInfoEndpoint を true に設定できます：
builder.Services.AddLogtoAuthentication(options =>
{
// ...
options.GetClaimsFromUserInfoEndpoint = true;
});
スコープとクレーム
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 | 説明 |
|---|---|---|
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 リソースを適切に設定する方法を理解できます。
アプリで API リソースを設定する
API リソースを設定したら、アプリで Logto を設定する際にそれらを追加できます：
builder.Services.AddLogtoAuthentication(options =>
{
// ...
options.Resource = "https://<your-api-resource-indicator>";
});
各 API リソースには独自の権限 (スコープ) があります。
例えば、https://shopping.your-app.com/api リソースには shopping:read と shopping:write の権限があり、https://store.your-app.com/api リソースには store:read と store:write の権限があります。
これらの権限を要求するには、アプリで Logto を設定する際にそれらを追加できます：
builder.Services.AddLogtoAuthentication(options =>
{
// ...
options.Resource = "https://shopping.your-app.com/api";
options.Scopes = new string[] {
"openid",
"profile",
"offline_access",
"read",
"write"
};
});
スコープが API リソースとは別に定義されていることに気付くかもしれません。これは、OAuth 2.0 のリソースインジケーター が、リクエストの最終的なスコープはすべてのターゲットサービスでのすべてのスコープの直積になると指定しているためです。
API リソースで定義されていないスコープを要求しても問題ありません。例えば、API リソースに email スコープが利用できなくても、email スコープを要求できます。利用できないスコープは安全に無視されます。
サインインが成功すると、Logto はユーザーのロールに応じて適切なスコープを API リソースに発行します。
トークンを取得する
場合によっては、API コールのためにアクセス トークン (Access token) や ID トークン (ID token) を取得する必要があります。GetTokenAsync メソッドを使用してトークンを取得できます：
var accessToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.AccessToken);
var idToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.IdToken);
トークンの有効期限について心配する必要はありません。認証 (Authentication) ミドルウェアが必要に応じて自動的にトークンをリフレッシュします。
認証 (Authentication) ミドルウェアはトークンを自動的にリフレッシュしますが、ユーザーオブジェクト内のクレーム (Claims) は、基盤となる OpenID Connect 認証 (Authentication) ハンドラーの制限により更新されません。 独自の認証 (Authentication) ハンドラーを実装すれば、この問題は解決できます。
上記のアクセス トークン (Access token) は、OpenID Connect の userinfo エンドポイント用の不透明トークン (Opaque token) であり、JWT ではありません。API リソースを指定している場合は、LogtoParameters.Tokens.AccessTokenForResource を使用して API リソース用のアクセス トークン (Access token) を取得する必要があります：
var accessToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.AccessTokenForResource);
このトークンは、API リソースがオーディエンス (Audience) となる JWT になります。