# 機能設計書 344-Test-DbaKerberos

## 概要

本ドキュメントは、dbatools PowerShellモジュールのTest-DbaKerberos関数の機能設計書である。この関数はSQL ServerインスタンスのKerberos認証設定を包括的に診断し、問題を特定して修復方法を提案する。

### 本機能の処理概要

Test-DbaKerberos関数は、SQL ServerインスタンスのKerberos認証に関する20以上の診断チェックを実行し、問題を特定して修復方法を提案する機能を提供する。

**業務上の目的・背景**：Kerberos認証は複雑な設定を必要とし、SPN設定、DNS、時刻同期、サービスアカウント、ネットワーク、セキュリティポリシーなど多くの要素が関与する。問題が発生した場合、原因の特定が困難であることが多い。この関数は、Kerberos認証の一般的な問題を体系的にチェックし、問題を迅速に特定・解決することを支援する。

**機能の利用シーン**：Kerberos認証の問題をトラブルシューティングする場合、新しいSQL Server環境のKerberos設定を検証する場合、セキュリティ監査の一環としてKerberos設定を確認する場合、定期メンテナンスでKerberos設定の健全性を確認する場合に使用される。

**主要な処理内容**：
1. SPN登録状態の検証（Test-DbaSpn、Test-DbaAgSpn連携）
2. 時刻同期の検証（クライアント-サーバー間、サーバー-DC間）
3. DNS設定の検証（正引き、逆引き、CNAME検出）
4. サービスアカウント設定の検証（アカウントタイプ、ロック状態、委任設定）
5. 認証スキームの検証（KERBEROS/NTLM判定）
6. ネットワーク接続の検証（Kerberosポート88、LDAPポート389、Kdc-Kerberosポート464）
7. セキュリティポリシーの検証（暗号化タイプ、セキュアチャネル、hostsファイル）
8. SQL Server構成の検証（サービスアカウント、ネットワークプロトコル）
9. クライアント側チェック（klistによるチケットキャッシュ検査）

**関連システム・外部連携**：SQL Server SMO、Active Directory、DNS、Windows Time Service、WinRM（リモートコンピュータ診断用）。

**権限による制御**：SQL ServerおよびActive Directoryへのアクセス権限が必要。リモート診断にはWinRM接続権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主機能 | PowerShellコマンドラインから直接実行 |

## 機能種別

診断・検証処理（Kerberos認証設定の包括的診断）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes (ParameterSet=Instance) | 対象のSQL Serverインスタンス | SQL Serverインスタンス名 |
| ComputerName | DbaInstanceParameter[] | Yes (ParameterSet=Computer) | 対象のコンピュータ名 | コンピュータ名/IP/FQDN |
| SqlCredential | PSCredential | No | SQL Server接続用の資格情報 | 有効なPSCredentialオブジェクト |
| Credential | PSCredential | No | リモート接続およびAD検索用の資格情報 | 有効なPSCredentialオブジェクト |
| EnableException | switch | No | 例外処理の動作を制御 | true/false |

### 入力データソース

- SqlInstance: SQL Serverインスタンス指定による直接入力（すべてのチェックを実行）
- ComputerName: コンピュータ名指定による入力（SQL Server固有のチェックはスキップ）
- パイプライン入力: Get-DbaRegServerからの入力をサポート

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | テスト対象のコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名（コンピュータレベルテストの場合はnull） |
| Check | string | 診断チェックの名前 |
| Category | string | チェックカテゴリ（SPN, Time Sync, DNS, Service Account, Authentication, Network, Security Policy, SQL Configuration, Client） |
| Status | string | チェック結果（Pass, Fail, Warning） |
| Details | string | チェック結果の詳細 |
| Remediation | string | 問題解決のための推奨アクション |

### 出力先

PowerShellパイプライン（PSCustomObject）- 各チェックごとに1オブジェクト

## 処理フロー

### 処理シーケンス

```
1. ターゲット解決
   └─ SqlInstance指定時: Connect-DbaInstanceで接続
   └─ ComputerName指定時: コンピュータ名を使用

2. Tier 1チェック（必須・基本）
   ├─ SPN登録チェック (Test-DbaSpn)
   ├─ AGリスナーSPNチェック (Test-DbaAgSpn) ※AGがある場合
   ├─ 時刻同期チェック（クライアント-サーバー）
   ├─ 時刻同期チェック（サーバー-DC）
   ├─ DNS正引きチェック
   ├─ DNS逆引きチェック
   ├─ CNAME検出チェック
   ├─ サービスアカウントタイプチェック ※Instanceのみ
   ├─ アカウントロック状態チェック ※Instanceのみ
   ├─ 委任設定チェック ※Instanceのみ
   └─ 認証スキームチェック ※Instanceのみ

3. Tier 2チェック（実用・補助）
   ├─ Kerberosポート(TCP/88)接続チェック
   ├─ LDAPポート(TCP/389)接続チェック
   ├─ Kerberos-Kdcポート(TCP/464)接続チェック
   ├─ Kerberos暗号化タイプチェック
   ├─ コンピュータセキュアチャネルチェック
   ├─ hostsファイルチェック
   ├─ SQLサービスアカウント構成チェック ※Instanceのみ
   ├─ ネットワークプロトコル構成チェック ※Instanceのみ
   └─ Kerberosチケットキャッシュチェック(klist)

4. 結果出力
   └─ 各チェックの結果をリアルタイムで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance or ComputerName?}
    B -->|SqlInstance| C[Connect-DbaInstance]
    B -->|ComputerName| D[コンピュータ名を使用]
    C --> E[Tier 1: SPNチェック]
    D --> E
    E --> F[Tier 1: AGリスナーSPNチェック]
    F --> G[Tier 1: 時刻同期チェック]
    G --> H[Tier 1: DNSチェック]
    H --> I{SqlInstance?}
    I -->|Yes| J[Tier 1: サービスアカウントチェック]
    I -->|No| K[スキップ]
    J --> L[Tier 2: ネットワークポートチェック]
    K --> L
    L --> M[Tier 2: セキュリティポリシーチェック]
    M --> N{SqlInstance?}
    N -->|Yes| O[Tier 2: SQL構成チェック]
    N -->|No| P[スキップ]
    O --> Q[Tier 2: クライアントチェック]
    P --> Q
    Q --> R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 時刻同期閾値 | 5分以上の差はFail、2-5分はWarning | 時刻同期チェック時 |
| BR-002 | CNAMEはKerberosで非対応 | CNAME検出時はFail | DNS CNAME検出チェック時 |
| BR-003 | gMSA/ドメインアカウント推奨 | ローカルアカウントはFail | サービスアカウントタイプチェック時 |
| BR-004 | NTLM使用はFail | Kerberos以外はFail | 認証スキームチェック時 |
| BR-005 | hostsファイルエントリはWarning | アクティブエントリがある場合 | hostsファイルチェック時 |
| BR-006 | TCP/IPプロトコル必須 | TCP/IP無効時はWarning | ネットワークプロトコルチェック時 |

### 計算ロジック

時刻差分の計算：
```
$timeDiff = [Math]::Abs(($clientTime - $serverTime).TotalMinutes)
```

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 時刻取得 | - | SELECT | SELECT GETDATE() AS ServerTime |
| 認証スキーム | sys.dm_exec_connections | SELECT | Test-DbaConnectionAuthScheme経由 |

### テーブル別操作詳細

該当なし（システムDMVの読み取りのみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | SQL接続失敗 | SqlInstanceへの接続が失敗 | 接続設定を確認 |
| - | AD検索失敗 | Active Directory接続が失敗 | 資格情報とドメイン接続を確認 |
| - | WinRM失敗 | リモートコンピュータへのInvoke-Command失敗 | WinRM設定を確認 |
| - | DCアクセス失敗 | ドメインコントローラーへの接続が失敗 | ネットワーク接続を確認 |

### リトライ仕様

明示的なリトライ機能はなし。各チェックは独立して実行され、1つのチェック失敗が他のチェックに影響しない。

## トランザクション仕様

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- 20以上のチェックを順次実行するため、完了まで数分かかる場合がある
- 各チェック結果はリアルタイムで出力される
- ネットワークポートチェックは各ポートへのTCP接続テストを行う

## セキュリティ考慮事項

- SQL ServerおよびActive Directoryへの読み取りアクセス権限が必要
- WinRMを使用したリモートコマンド実行が必要
- w32tmやklistなどのシステムコマンドを実行
- レジストリの読み取り（暗号化タイプ設定）

## 備考

- 9つのカテゴリ、20以上の診断チェックを実行
- ComputerName指定時はSQL Server固有のチェック（Service Account, Authentication, SQL Configuration）はスキップ
- Get-DbaRegServerとのパイプライン連携で複数サーバーを一括診断可能
- Where-Object Status -eq "Fail"でFailedチェックのみをフィルタリング可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

出力されるPSCustomObjectの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | 207-215行目の出力オブジェクト構造を確認（各チェックで同じ形式） |

**読解のコツ**: すべてのチェック結果は同じ7プロパティ（ComputerName, InstanceName, Check, Category, Status, Details, Remediation）を持つ。

#### Step 2: エントリーポイントを理解する

関数の入口と主要パラメータを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | 145-154行目のパラメータ定義を確認 |

**主要処理フロー**:
1. **145-154行目**: param()ブロックでパラメータ定義
2. **147-150行目**: ParameterSetによるSqlInstance/ComputerNameの排他制御

#### Step 3: Tier 1チェックを理解する

必須・基本チェックのロジックを追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | 177-270行目: SPNチェック |
| 3-2 | Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | 272-451行目: 時刻同期チェック |
| 3-3 | Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | 453-588行目: DNSチェック |
| 3-4 | Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | 590-786行目: サービスアカウントチェック |
| 3-5 | Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | 789-835行目: 認証スキームチェック |

#### Step 4: Tier 2チェックを理解する

実用・補助チェックのロジックを追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | 841-955行目: ネットワークポートチェック |
| 4-2 | Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | 956-1106行目: セキュリティポリシーチェック |
| 4-3 | Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | 1108-1207行目: SQL構成チェック |
| 4-4 | Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | 1210-1252行目: クライアントチェック（klist） |

### プログラム呼び出し階層図

```
Test-DbaKerberos
    │
    ├─ Connect-DbaInstance (SqlInstance指定時)
    │
    ├─ Test-DbaSpn (SPN検証)
    │      └─ Get-DbaADObject
    │
    ├─ Get-DbaAgListener / Test-DbaAgSpn (AGリスナーSPN検証)
    │
    ├─ $server.Query() (時刻取得、認証スキーム)
    │
    ├─ [System.Net.Dns]::GetHostEntry() (DNS検証)
    │
    ├─ Invoke-Command (リモートコンピュータ診断)
    │      ├─ nslookup (CNAME検出)
    │      ├─ w32tm (DC時刻同期)
    │      ├─ Test-ComputerSecureChannel
    │      ├─ Get-Content (hostsファイル)
    │      └─ Get-ItemProperty (レジストリ)
    │
    ├─ Test-NetConnection (ポート接続テスト)
    │
    ├─ Test-DbaConnectionAuthScheme (認証スキーム検証)
    │
    ├─ Get-DbaNetworkConfiguration (ネットワーク構成)
    │
    └─ klist (Kerberosチケットキャッシュ)
```

### データフロー図

```
[入力]                     [処理]                              [出力]

SqlInstance ───┬──▶ Connect-DbaInstance ──▶ SQL Server接続
               │            │
ComputerName ──┘            ▼
                    ┌───────┴───────┐
                    │               │
              Tier 1チェック    Tier 2チェック
                    │               │
                    ├─ SPN          ├─ ネットワークポート
                    ├─ 時刻同期      ├─ セキュリティポリシー
                    ├─ DNS          ├─ SQL構成
                    ├─ サービスアカウント └─ クライアント(klist)
                    └─ 認証スキーム
                            │
                            ▼
                    PSCustomObject ──▶ 各チェック結果
                    (リアルタイム出力)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaKerberos.ps1 | `public/Test-DbaKerberos.ps1` | ソース | メイン関数 |
| Test-DbaSpn.ps1 | `public/Test-DbaSpn.ps1` | ソース | SPN検証サブ関数 |
| Test-DbaAgSpn.ps1 | `public/Test-DbaAgSpn.ps1` | ソース | AGリスナーSPN検証サブ関数 |
| Test-DbaConnectionAuthScheme.ps1 | `public/Test-DbaConnectionAuthScheme.ps1` | ソース | 認証スキーム検証サブ関数 |
| Get-DbaAgListener.ps1 | `public/Get-DbaAgListener.ps1` | ソース | AGリスナー取得 |
| Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | ソース | ネットワーク構成取得 |
| Get-DbaADObject.ps1 | `private/functions/Get-DbaADObject.ps1` | ソース | ADオブジェクト検索 |
