あなたの .NET Core (Blazor Server) アプリケーションに認証 (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) サービスを登録します：

Program.cs
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://http://localhost:3000//Callback

Logto サインアウト後リダイレクト URI を設定するには、次の URI を Logto アプリケーション詳細ページの「サインアウト後リダイレクト URI」リストに追加します：

http://http://localhost:3000//SignedOutCallback

デフォルトパスを変更する

Logto リダイレクト URI にはデフォルトパス /Callback があり、Logto サインアウト後リダイレクト URI にはデフォルトパス /SignedOutCallback があります。

特別な要件がない場合は、そのままにしておくことができます。変更したい場合は、LogtoOptions の CallbackPath と SignedOutCallbackPath プロパティを設定できます：

Program.cs
builder.Services.AddLogtoAuthentication(options =>
{
  // 他の設定...
  options.CallbackPath = "/Foo";
  options.SignedOutCallbackPath = "/Bar";
});

Logto アプリケーション詳細ページの値もそれに応じて更新することを忘れないでください。

ルートを追加する

Blazor Server は SignalR を使用してサーバーとクライアント間で通信するため、HTTP コンテキストを直接操作するメソッド（チャレンジやリダイレクトの発行など）は、Blazor コンポーネントから呼び出された場合、期待通りに動作しません。

これを正しく行うためには、サインインとサインアウトのリダイレクト用に 2 つのエンドポイントを明示的に追加する必要があります：

Program.cs
app.MapGet("/SignIn", async context =>
{
    if (!(context.User?.Identity?.IsAuthenticated ?? false))
    {
        await context.ChallengeAsync(new AuthenticationProperties { RedirectUri = "/" });
    } else {
        context.Response.Redirect("/");
    }
});

app.MapGet("/SignOut", async context =>
{
    if (context.User?.Identity?.IsAuthenticated ?? false)
    {
        await context.SignOutAsync(new AuthenticationProperties { RedirectUri = "/" });
    } else {
        context.Response.Redirect("/");
    }
});

これで、これらのエンドポイントにリダイレクトしてサインインとサインアウトをトリガーできます。

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

Razor コンポーネントに次のコードを追加します：

Components/Pages/Index.razor
@using Microsoft.AspNetCore.Components.Authorization
@using System.Security.Claims
@inject AuthenticationStateProvider AuthenticationStateProvider
@inject NavigationManager NavigationManager

@* ... *@

<p>認証 (Authentication) 済み: @User.Identity?.IsAuthenticated</p>
@if (User.Identity?.IsAuthenticated == true)
{
    <button @onclick="SignOut">サインアウト</button>
}
else
{
    <button @onclick="SignIn">サインイン</button>
}

@* ... *@

@code {
    private ClaimsPrincipal? User { get; set; }

    protected override async Task OnInitializedAsync()
    {
        var authState = await AuthenticationStateProvider.GetAuthenticationStateAsync();
        User = authState.User;
    }

    private void SignIn()
    {
        NavigationManager.NavigateTo("/SignIn", forceLoad: true);
    }

    private void SignOut()
    {
        NavigationManager.NavigateTo("/SignOut", forceLoad: true);
    }
}

説明：

インジェクトされた AuthenticationStateProvider は、現在のユーザーの認証 (Authentication) 状態を取得し、User プロパティを設定するために使用されます。
SignIn と SignOut メソッドは、それぞれサインインおよびサインアウトのエンドポイントにユーザーをリダイレクトするために使用されます。Blazor Server の性質上、リダイレクションをトリガーするために NavigationManager を強制ロードで使用する必要があります。

ページは、ユーザーが認証 (Authentication) されていない場合は「サインイン」ボタンを表示し、認証 (Authentication) されている場合は「サインアウト」ボタンを表示します。

`<AuthorizeView />` コンポーネント

代わりに、AuthorizeView コンポーネントを使用して、ユーザーの認証 (Authentication) 状態に基づいてコンテンツを条件付きでレンダリングすることができます。このコンポーネントは、認証 (Authentication) 済みユーザーと未認証ユーザーに異なるコンテンツを表示したい場合に便利です。

Razor コンポーネントに次のコードを追加します：

Components/Pages/Index.razor
@using Microsoft.AspNetCore.Components.Authorization

@* ... *@

<AuthorizeView>
    <Authorized>
        <p>Name: @User?.Identity?.Name</p>
        @* 認証 (Authentication) 済みユーザー向けのコンテンツ *@
    </Authorized>
    <NotAuthorized>
        @* 未認証ユーザー向けのコンテンツ *@
    </NotAuthorized>
</AuthorizeView>

@* ... *@

AuthorizeView コンポーネントは、Task<AuthenticationState> 型のカスケードパラメーターを必要とします。このパラメーターを取得する直接的な方法は、<CascadingAuthenticationState> コンポーネントを追加することです。ただし、Blazor Server の性質上、レイアウトやルートコンポーネントに単純にコンポーネントを追加することはできません（期待通りに動作しない可能性があります）。代わりに、ビルダー (Program.cs または Startup.cs) に次のコードを追加してカスケードパラメーターを提供します：

Program.cs
builder.Services.AddCascadingAuthenticationState();

その後、AuthorizeView コンポーネントを必要とするすべてのコンポーネントで使用できます。

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

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

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

ユーザー情報を取得する

ユーザー情報の表示

ユーザーが認証 (Authentication) されているかどうかを確認するには、User.Identity?.IsAuthenticated プロパティをチェックできます。

ユーザープロファイルのクレームを取得するには、User.Claims プロパティを使用します：

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

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

備考:

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

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

ヒント:

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

Logto SDK は常に 3 つのスコープ (Scope) をリクエストします：openid、profile、および offline_access。

追加のスコープをリクエストするには、options オブジェクトの Scopes プロパティを設定できます：

Program.cs
builder.Services.AddLogtoAuthentication(options =>
{
  // ...
  options.Scopes = new string[] {
    LogtoParameters.Scopes.Email,
    LogtoParameters.Scopes.Phone
  }
});

その後、User.Claims を介して追加のクレームにアクセスできます：

Controllers/HomeController.cs
var claims = User.Claims;

// ユーザーのメールを取得
var email = claims.FirstOrDefault(c => c.Type == LogtoParameters.Claims.Email)?.Value;

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

ユーザーオブジェクトの肥大化を防ぐために、一部のクレームは取得するためにネットワークリクエストが必要です。たとえば、custom_data クレームはスコープでリクエストされていてもユーザーオブジェクトに含まれていません。これらのクレームを取得するには、options オブジェクトで GetClaimsFromUserInfoEndpoint を true に設定できます：

Program.cs
builder.Services.AddLogtoAuthentication(options =>
{
  // ...
  options.GetClaimsFromUserInfoEndpoint = true;
});

スコープとクレーム

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 リソースを適切に設定する方法を理解できます。

アプリで API リソースを設定する

API リソースを設定したら、アプリで Logto を設定する際にそれらを追加できます：

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

Program.cs
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 リソースに発行します。

トークンを取得する

`HttpContext` を介してトークンを取得する

API 呼び出しのためにアクセストークンまたは ID トークンを取得する必要がある場合があります。GetTokenAsync メソッドを使用してトークンを取得できます：

var accessToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.AccessToken);
var idToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.IdToken);

トークンの有効期限について心配する必要はありません。認証 (Authentication) ミドルウェアが必要に応じてトークンを自動的に更新します。

注意:

認証 (Authentication) ミドルウェアはトークンを自動的に更新しますが、ユーザーオブジェクト内のクレームは、基盤となる OpenID Connect 認証 (Authentication) ハンドラーの制限により更新されません。これは、独自の認証 (Authentication) ハンドラーを作成することで解決できます。

上記のアクセストークンは、OpenID Connect の userinfo エンドポイント用の不透明トークンであり、JWT トークンではありません。API リソースを指定した場合、API リソース用のアクセストークンを取得するには LogtoParameters.Tokens.AccessTokenForResource を使用する必要があります：

var accessToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.AccessTokenForResource);

このトークンは、API リソースをオーディエンスとする JWT トークンになります。

Razor コンポーネントでトークンを取得する

HttpContext に直接アクセスできないため、Razor コンポーネントで HttpContextAccessor をコンポーネントに注入し、それを使用してトークンを取得する必要があります。以下のコードは、Razor コンポーネントで API リソースのアクセストークンを取得する方法を示しています：

Components/Pages/Index.razor
@using Microsoft.AspNetCore.Components.Authorization
@using System.Security.Claims
@using Logto.AspNetCore.Authentication
@using Microsoft.AspNetCore.Authentication
@inject AuthenticationStateProvider AuthenticationStateProvider
@inject IHttpContextAccessor HttpContextAccessor

@* ... *@

<p><b>Resource:</b> @(Resource ?? "(null)")</p>
<p><b>Access Token:</b> @(AccessToken ?? "(null)")</p>

@* ... *@

@code {
    private ClaimsPrincipal? User { get; set; }
    private string? AccessToken { get; set; }
    private string? Resource { get; set; }

    protected override async Task OnInitializedAsync()
    {
        var authState = await AuthenticationStateProvider.GetAuthenticationStateAsync();
        User = authState.User;

        if (User?.Identity?.IsAuthenticated == true)
        {
            await FetchTokenAsync();
        }
    }

    private async Task FetchTokenAsync()
    {
        var httpContext = HttpContextAccessor.HttpContext;
        if (httpContext == null)
        {
            return;
        }

        var logtoOptions = httpContext.GetLogtoOptions();
        Resource = logtoOptions?.Resource;
        // 必要に応じて他のトークンタイプに置き換えてください
        AccessToken = await httpContext.GetTokenAsync(LogtoParameters.Tokens.AccessTokenForResource);
    }
}

さらなる読み物

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

前提条件​

インストール​

統合​

Logto 認証 (Authentication) を追加する​

サインインとサインアウトのフロー​

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

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

デフォルトパスを変更する​

ルートを追加する​

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

<AuthorizeView /> コンポーネント​

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

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

ユーザー情報の表示​

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

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

スコープとクレーム​

API リソース​

アプリで API リソースを設定する​

トークンを取得する​

HttpContext を介してトークンを取得する​

Razor コンポーネントでトークンを取得する​

さらなる読み物​