Microsoft.Identity.Webでロギングを構成します。

Microsoft。Identity.Web は、ASP.NET Coreのログ 記録インフラストラクチャと統合されます。 これを使用して、次の問題を診断します。

• 認証フロー - サインイン、サインアウト、トークンの検証
• トークンの取得 - トークン キャッシュヒット/ミス、MSAL 操作
• ダウンストリーム API 呼び出し - HTTP 要求、API のトークン取得
• エラー条件 - 例外、検証エラー

ログ記録されたコンポーネントを理解する

ログ記録を始める

最小構成

次のログ レベルのエントリを appsettings.json に追加して、ID ログを有効にします。

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity": "Information"
    }
  }
}

これにより、Microsoft.Identity.Web とその依存関係 (MSAL.NET、IdentityModel) の Information レベル のログ記録が有効になります。

開発構成

開発中に詳細な診断を行う場合:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Identity": "Debug",
      "Microsoft.AspNetCore.Authentication": "Information"
    }
  },
  "AzureAd": {
    "EnablePiiLogging": true  // Development only!
  }
}

運用構成

運用環境では、エラーをキャプチャしながらログ ボリュームを最小限に抑えます。

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft": "Warning",
      "Microsoft.Identity": "Warning"
    }
  },
  "AzureAd": {
    "EnablePiiLogging": false  // Never true in production
  }
}

ログ のフィルター処理を構成する

名前空間ベースのフィルター処理

名前空間別にログの詳細度を制御します。 次の構成では、ID 関連の名前空間ごとに詳細なレベルを設定します。

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",

      // General Microsoft namespaces
      "Microsoft": "Warning",
      "Microsoft.AspNetCore": "Warning",

      // Identity-specific namespaces
      "Microsoft.Identity": "Information",
      "Microsoft.Identity.Web": "Information",
      "Microsoft.Identity.Client": "Information",

      // ASP.NET Core authentication
      "Microsoft.AspNetCore.Authentication": "Information",
      "Microsoft.AspNetCore.Authentication.JwtBearer": "Information",
      "Microsoft.AspNetCore.Authentication.OpenIdConnect": "Debug",

      // Token validation
      "Microsoft.IdentityModel": "Warning"
    }
  }
}

特定のログ記録を無効にする

ノイズの多いコンポーネントを他のコンポーネントに影響を与えずに無音にするには、ログ レベルを None または Warning に設定します。

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "None",  // Completely disable
      "Microsoft.Identity.Client": "Warning"  // Only errors/warnings
    }
  }
}

環境固有の構成

環境設定ごとに appsettings.{Environment}.json を使用します。

appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Debug"
    }
  },
  "AzureAd": {
    "EnablePiiLogging": true
  }
}

appsettings.Production.json:

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Warning"
    }
  },
  "AzureAd": {
    "EnablePiiLogging": false
  }
}

ログ レベルを理解する

ASP.NET Coreでは、次のログ レベルを定義します。 環境のログ ボリュームに対して診断の詳細のバランスを取るレベルを選択します。

ASP.NET Core のログレベル

MSAL.NET を ASP.NET Core レベルにマップする

環境別に推奨設定を適用する

環境ごとに次の構成を使用します。

開発：

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Debug",
      "Microsoft.Identity.Client": "Information"
    }
  }
}

ステージング：

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Information",
      "Microsoft.Identity.Client": "Warning"
    }
  }
}

生産：

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Warning",
      "Microsoft.Identity.Client": "Error"
    }
  }
}

PII ログの設定

既定では、Microsoft。Identity.Web は、個人を特定できる情報 (PII) をログから編集します。 開発環境でのみ PII ログを有効にして、完全なユーザーの詳細を表示します。

PII とは

個人を特定できる情報 (PII) には、次のものが含まれます。

• ユーザー名、メール アドレス
• 表示名
• オブジェクト ID、テナント ID
• IP アドレス
• トークン値、要求

セキュリティの警告

警告: お客様とアプリケーションは、 GDPR で規定されているものを含め、適用されるすべての規制要件に準拠する責任を負います。 PII ログを有効にする前に、この機密性の高いデータを安全に処理できることを確認してください。

PII ログを有効にする (開発のみ)

EnablePiiLoggingを開発構成ファイルのtrueに設定します。

appsettings.Development.json:

{
  "AzureAd": {
    "EnablePiiLogging": true  //  Development/Testing ONLY
  },
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity": "Debug"
    }
  }
}

プログラムによる PII ログ記録の制御

ホスティング環境に基づいて PII ログを切り替えます。

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<MicrosoftIdentityOptions>(options =>
{
    // Only enable PII in Development
    options.EnablePiiLogging = builder.Environment.IsDevelopment();
});

PII を有効にした場合の変更点

PII ログなし:

[Information] Token validation succeeded for user '{hidden}'
[Information] Acquired token from cache for scopes '{hidden}'

PII が有効になっている場合:

[Information] Token validation succeeded for user 'john.doe@contoso.com'
[Information] Acquired token from cache for scopes 'user.read api://my-api/.default'

ログ内のPIIの抹消

PII ログが無効になっている場合、機密データは次のように置き換えられます。

• {hidden} - ユーザー識別子を非表示にします
• {hash:XXXX} - 実際の値の代わりにハッシュを表示します
• *** - トークンを隠す

関連付け ID を使用する

関連付け ID は、サービス間で認証要求をトレースします。 問題の解決を高速化するために、ログやサポートチケットにそれらを含めてください。

関連付け ID とは

関連付け ID は、次の間で認証またはトークン取得要求を一意に識別する GUID です。

• ご利用のアプリケーション
• Microsoft ID プラットフォーム
• MSAL.NET ライブラリ
• バックエンド サービスのMicrosoft

関連付け ID を取得する

方法 1: AuthenticationResult から取得

トークンの取得が成功した後、 AuthenticationResult から関連付け ID を抽出します。

using Microsoft.Identity.Web;

public class TodoController : ControllerBase
{
    private readonly ITokenAcquisition _tokenAcquisition;
    private readonly ILogger<TodoController> _logger;

    public TodoController(
        ITokenAcquisition tokenAcquisition,
        ILogger<TodoController> logger)
    {
        _tokenAcquisition = tokenAcquisition;
        _logger = logger;
    }

    [HttpGet]
    public async Task<IActionResult> GetTodos()
    {
        var result = await _tokenAcquisition.GetAuthenticationResultForUserAsync(
            new[] { "user.read" });

        _logger.LogInformation(
            "Token acquired. CorrelationId: {CorrelationId}, Source: {TokenSource}",
            result.CorrelationId,
            result.AuthenticationResultMetadata.TokenSource);

        return Ok(result.CorrelationId);
    }
}

方法 2: MsalServiceException を使用して

トークンの取得が失敗したときに、 MsalServiceException から関連付け ID をキャプチャします。

using Microsoft.Identity.Client;

try
{
    var token = await _tokenAcquisition.GetAccessTokenForUserAsync(
        new[] { "user.read" });
}
catch (MsalServiceException ex)
{
    _logger.LogError(ex,
        "Token acquisition failed. CorrelationId: {CorrelationId}, ErrorCode: {ErrorCode}",
        ex.CorrelationId,
        ex.ErrorCode);

    // Return correlation ID to user for support
    return StatusCode(500, new {
        error = "authentication_failed",
        correlationId = ex.CorrelationId
    });
}

方法 3: カスタム関連付け ID を設定する

カスタム関連付け ID を割り当てて、アプリケーション トレースとMicrosoft Entra ID要求をリンクします。

[HttpGet("{id}")]
public async Task<IActionResult> GetTodo(int id)
{
    // Use request trace ID as correlation ID
    var correlationId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;

    var todo = await _downstreamApi.GetForUserAsync<Todo>(
        "TodoListService",
        options =>
        {
            options.RelativePath = $"api/todolist/{id}";
            options.TokenAcquisitionOptions = new TokenAcquisitionOptions
            {
                CorrelationId = Guid.Parse(correlationId)
            };
        });

    _logger.LogInformation(
        "Called downstream API. TraceId: {TraceId}, CorrelationId: {CorrelationId}",
        HttpContext.TraceIdentifier,
        correlationId);

    return Ok(todo);
}

サポート用の関連付け ID を提供する

Microsoftサポートに問い合わせる場合は、次の詳細を入力します。

1. 関連付け ID - ログまたは例外から
2. タイムスタンプ - エラーが発生したとき (UTC)
3. テナント ID - あなたの Microsoft Entra ID テナント
4. エラー コード - 該当する場合 (例: AADSTS50058)

サポート要求の例:

Subject: Token acquisition failing for user.read scope

Correlation ID: 12345678-1234-1234-1234-123456789012
Timestamp: 2025-01-15 14:32:45 UTC
Tenant ID: contoso.onmicrosoft.com
Error Code: AADSTS50058

トークン キャッシュのログ記録を有効にする

トークン キャッシュ のログ記録は、キャッシュのヒット/ミスの動作を理解し、分散キャッシュのパフォーマンスの問題を診断するのに役立ちます。

トークン キャッシュ診断を有効にする

分散トークン キャッシュを使用する .NET Framework または .NET Core アプリの場合は、詳細なログ記録を構成します。

using Microsoft.Extensions.Logging;
using Microsoft.Identity.Web.TokenCacheProviders;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDistributedTokenCaches();

// Enable detailed token cache logging
builder.Services.AddLogging(configure =>
{
    configure.AddConsole();
    configure.AddDebug();
})
.Configure<LoggerFilterOptions>(options =>
{
    options.MinLevel = LogLevel.Debug;  // Detailed cache operations
});

トークン キャッシュ ログの例

キャッシュ ヒット:

[Debug] Token cache: Token found in cache for scopes 'user.read'
[Information] Token source: Cache

キャッシュ ミス:

[Debug] Token cache: No token found in cache for scopes 'user.read'
[Information] Token source: IdentityProvider
[Debug] Token cache: Token stored in cache

分散キャッシュのトラブルシューティング

プロバイダー固有のログ記録を有効にして、キャッシュの接続とパフォーマンスの問題を診断します。

Redis Cache:

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = builder.Configuration["Redis:ConnectionString"];
});

// Enable Redis logging
builder.Services.AddLogging(configure =>
{
    configure.AddFilter("Microsoft.Extensions.Caching", LogLevel.Debug);
});

SQL Server cache:

ログを使用して分散キャッシュSQL Server構成します。

builder.Services.AddDistributedSqlServerCache(options =>
{
    options.ConnectionString = builder.Configuration["SqlCache:ConnectionString"];
    options.SchemaName = "dbo";
    options.TableName = "TokenCache";
});

// Enable SQL cache logging
builder.Services.AddLogging(configure =>
{
    configure.AddFilter("Microsoft.Extensions.Caching.SqlServer", LogLevel.Information);
});

一般的な問題のトラブルシューティング

次のシナリオを使用して、頻繁に発生する認証と承認の問題を診断します。

一般的なログ記録シナリオ

シナリオ 1: トークン検証エラー

現象: 401 未承認の応答

詳細なログを有効にします。

{
  "Logging": {
    "LogLevel": {
      "Microsoft.AspNetCore.Authentication.JwtBearer": "Debug",
      "Microsoft.IdentityModel": "Information"
    }
  }
}

以下のものを探します。

[Information] Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerHandler:
  Failed to validate the token.
[Debug] Microsoft.IdentityModel.Tokens: IDX10230: Lifetime validation failed.
  The token is expired.

シナリオ 2: トークン取得エラー

現象:MsalServiceException または MsalUiRequiredException

詳細なログを有効にします。

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity.Web": "Debug",
      "Microsoft.Identity.Client": "Information"
    }
  }
}

以下のものを探します。

[Error] Microsoft.Identity.Web: Token acquisition failed.
  ErrorCode: invalid_grant, CorrelationId: {guid}
[Information] Microsoft.Identity.Client: MSAL returned exception:
  AADSTS50058: Silent sign-in failed.

シナリオ 3: ダウンストリーム API 呼び出しエラー

症状： ダウンストリーム API を呼び出す HTTP 502 またはタイムアウト エラー

詳細なログを有効にします。

{
  "Logging": {
    "LogLevel": {
      "Microsoft.Identity.Abstractions": "Debug",
      "System.Net.Http": "Information"
    }
  }
}

コントローラーにカスタム ログを追加して、ダウンストリーム API エラーをキャプチャします。

[HttpGet]
public async Task<IActionResult> GetUserProfile()
{
    try
    {
        _logger.LogInformation("Acquiring token for Microsoft Graph");

        var user = await _downstreamApi.GetForUserAsync<User>(
            "MicrosoftGraph",
            options => options.RelativePath = "me");

        _logger.LogInformation(
            "Successfully retrieved user profile for {UserPrincipalName}",
            user.UserPrincipalName);

        return Ok(user);
    }
    catch (MsalUiRequiredException ex)
    {
        _logger.LogWarning(ex,
            "User interaction required. CorrelationId: {CorrelationId}",
            ex.CorrelationId);
        return Challenge();
    }
    catch (HttpRequestException ex)
    {
        _logger.LogError(ex, "Failed to call Microsoft Graph API");
        return StatusCode(502, "Downstream API error");
    }
}

ログ パターンを解釈する

次の例は、一般的な認証イベントの一般的なログ出力を示しています。

成功した認証フロー:

[Info] Authentication scheme OpenIdConnect: Authorization response received
[Debug] Correlation id: {guid}
[Info] Authorization code received
[Info] Token validated successfully
[Info] Authentication succeeded for user: {user}

同意が必要:

[Warning] Microsoft.Identity.Web: Incremental consent required
[Info] AADSTS65001: User consent is required for scopes: {scopes}
[Info] Redirecting to consent page

トークンの更新:

[Debug] Token expired, attempting silent token refresh
[Info] Token source: IdentityProvider
[Info] Token refreshed successfully

外部プロバイダーを使用してログを集計する

監視とアラートのために、一元化されたログ プラットフォームに ID ログを転送します。

Application Insights の統合:

関連付け ID エンリッチメントを使用して Application Insights に ID テレメトリを送信します。

using Microsoft.ApplicationInsights.Extensibility;

builder.Services.AddApplicationInsightsTelemetry();

// Enrich telemetry with correlation IDs
builder.Services.AddSingleton<ITelemetryInitializer, CorrelationIdTelemetryInitializer>();

Serilog の統合:

コンソールとローリング ファイルの出力に ID ログをキャプチャするように Serilog を構成します。

using Serilog;

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .MinimumLevel.Override("Microsoft.Identity", Serilog.Events.LogEventLevel.Debug)
    .Enrich.FromLogContext()
    .WriteTo.Console()
    .WriteTo.File("logs/identity-.txt", rollingInterval: RollingInterval.Day)
    .CreateLogger();

builder.Host.UseSerilog();

ログのベスト プラクティスに従う

これらのプラクティスを適用して、ID ログをセキュリティで保護し、役立ち、パフォーマンスを維持します。

やるべきこと

1. 構造化ログを使用する:

ログ アグリゲーターがインデックスを作成してクエリできるように、値を名前付きパラメーターとして渡します。

_logger.LogInformation(
    "Token acquired for user {UserId} with scopes {Scopes}",
    userId, string.Join(" ", scopes));

2. ログ相関 ID:

サポートの調査を簡略化するために、常にエラー ログに関連付け ID を含めます。

_logger.LogError(ex,
    "Operation failed. CorrelationId: {CorrelationId}",
    ex.CorrelationId);

3. 適切なログ レベルを使用します。

ログ レベルを重大度と対象ユーザーと一致させます。

_logger.LogDebug("Detailed diagnostic info");      // Development
_logger.LogInformation("Key application events");  // Selective production
_logger.LogWarning("Unexpected but handled");      // Production
_logger.LogError(ex, "Operation failed");          // Production

4. 運用環境でログをサニタイズする:

機密性の高い値を運用ログに書き込む前にマスクします。

var sanitizedEmail = environment.IsProduction()
    ? MaskEmail(email)
    : email;
_logger.LogInformation("Processing request for {Email}", sanitizedEmail);

してはいけないこと

1. 運用環境で PII を有効にしないでください。

//  Wrong
"EnablePiiLogging": true  // In production config!

//  Correct
"EnablePiiLogging": false

2. シークレットをログに記録しない:

//  Wrong
_logger.LogInformation("Token: {Token}", accessToken);

//  Correct
_logger.LogInformation("Token acquired, expires: {ExpiresOn}", expiresOn);

3. 運用環境では詳細ログを使用しないでください。

//  Wrong - production appsettings.json
"Microsoft.Identity": "Debug"

//  Correct
"Microsoft.Identity": "Warning"

関連するコンテンツ

• 認証のカスタマイズ
• トークン キャッシュのトラブルシューティング
• ダウンストリーム API の呼び出し
• 認可