# 画面設計書 69-Windowsログインテスト

## 概要

本ドキュメントは、dbatools PowerShell モジュールにおける SQL Server Windows ログインの Active Directory 検証機能の設計仕様を定義する。Windows ログインとグループを Active Directory に対して検証し、孤立した、無効化された、または問題のあるアカウントを特定する。

### 本画面の処理概要

本機能は、SQL Server のすべての Windows ベースのログインとグループを取得し、各アカウントを Active Directory に対して検証する。AD アカウントが存在するか、有効化されているか、SQL Server の SID と一致するかをチェックし、ドメイン移行やアカウント削除による孤立したログインを検出する。

**業務上の目的・背景**：DBA はログインセキュリティを維持するために、SQL Server から削除すべき古い Windows 認証アカウントを特定する必要がある。セキュリティ監査、コンプライアンスレポート、孤立アカウントのクリーンアップに使用される。

**画面へのアクセス方法**：PowerShell コンソールから `Test-DbaWindowsLogin` コマンドを直接呼び出す。Get-DbaLogin からパイプラインで渡すことも可能。

**主要な操作・処理内容**：
1. `Test-DbaWindowsLogin` - Windows ログインを AD に対して検証
2. FilterBy パラメータで LoginsOnly/GroupsOnly にフィルタリング
3. IgnoreDomains パラメータで特定ドメインを除外
4. UserAccountControl フラグを解析してアカウント状態を取得
5. SID 比較で孤立アカウントを検出

**画面遷移**：
- Get-DbaLogin → Test-DbaWindowsLogin のパイプライン連携
- Test-DbaWindowsLogin → Format-Table で表形式出力

**権限による表示制御**：sysadmin 権限と Active Directory への読み取り権限が必要。SQL Server 2000 以上が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Test-DbaWindowsLogin | 主機能 | Windows ログインの AD 検証 |
| - | Get-DbaLogin | 補助機能 | ログイン取得（パイプライン入力） |
| - | Get-DbaADObject | 補助機能 | AD オブジェクト取得（内部使用） |

## 画面種別

CLI（コマンドラインインターフェース）/ 一覧出力

## URL/ルーティング

PowerShell コマンドレットとして呼び出し。URL は存在しない。

```powershell
Test-DbaWindowsLogin -SqlInstance <インスタンス名>
Test-DbaWindowsLogin -SqlInstance <インスタンス名> -FilterBy GroupsOnly
Test-DbaWindowsLogin -SqlInstance <インスタンス名> -IgnoreDomains testdomain
```

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 認証情報 |
| Login | string[] | No | 対象ログイン名（ワイルドカード可） |
| ExcludeLogin | string[] | No | 除外ログイン名（ワイルドカード可） |
| FilterBy | string | No | フィルタ（LoginsOnly/GroupsOnly/None）、デフォルト None |
| IgnoreDomains | string[] | No | 除外ドメイン |
| InputObject | Microsoft.SqlServer.Management.Smo.Login[] | No | パイプライン入力用ログインオブジェクト |
| EnableException | switch | No | 例外処理を有効化 |

## 表示項目

### Test-DbaWindowsLogin 出力（デフォルト表示）

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| Server | string | SQL Server インスタンス名 |
| Domain | string | Active Directory ドメイン名 |
| Login | string | ログイン名（ユーザー名またはグループ名） |
| Type | string | アカウントタイプ（User/Computer/Group） |
| Found | bool | AD にアカウントが存在するか |
| SamAccountNameMismatch | bool | SAM アカウント名の不一致 |
| DisabledInSQLServer | bool | SQL Server で無効化されているか |

### 追加プロパティ（Select-Object * で表示）

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| Enabled | bool | AD でアカウントが有効か（グループは null） |
| AccountNotDelegated | bool | 委任禁止フラグ |
| LockedOut | bool | ロックアウトされているか |
| PasswordExpired | bool | パスワード期限切れか |
| PasswordNeverExpires | bool | パスワード無期限か |
| PasswordNotRequired | bool | パスワード不要か |
| CannotChangePassword | bool | パスワード変更不可か |
| AllowReversiblePasswordEncryption | bool | 可逆暗号化パスワード許可 |
| SmartcardLogonRequired | bool | スマートカードログイン必須 |
| TrustedForDelegation | bool | 委任信頼 |
| UserAccountControl | int | UserAccountControl 生値 |

## イベント仕様

### 1-Test-DbaWindowsLogin 実行

1. IgnoreDomains を正規化（大文字変換）
2. UserAccountControl マッピング定義
3. Connect-DbaInstance で接続
4. WindowsUser/WindowsGroup タイプのログインを取得
5. NT *、BUILTIN\*、ローカルアカウント（ComputerName\*）を除外
6. Login/ExcludeLogin でフィルタリング
7. FilterBy で LoginsOnly/GroupsOnly に分割
8. 各ログインについて：
   - SID を SecurityIdentifier に変換
   - Get-DbaADObject で AD オブジェクト検索
   - SID 比較で存在確認
   - SamAccountName 比較で不一致検出
   - UserAccountControl フラグを解析
9. PSCustomObject で結果を出力
10. Select-DefaultView で表示列を制限

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Test-DbaWindowsLogin | $server.Logins | SELECT | ログイン情報読み取り |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|----------|
| - | エラー | "You must supply either -SqlInstance or an Input Object" | 両方未指定 |
| - | エラー | "Failure" | 接続エラー |
| - | Warning | "SID mismatch detected for $adLogin." | SID 不一致 |
| - | Warning | "SamAccountName mismatch detected for $adLogin." | SAM 名不一致 |
| - | Warning | "AD Searcher Error for $username." | AD 検索エラー |
| - | Verbose | "Excluding logins for domains..." | ドメイン除外時 |
| - | Verbose | "Search restricted to logins/groups." | FilterBy 指定時 |
| - | Verbose | "Parsing Login $adLogin." | ログイン処理中 |

## 例外処理

| 例外条件 | ハンドリング | ユーザーへのフィードバック |
|---------|-------------|-------------------------|
| パラメータ不足 | Stop-Function | 必要なパラメータ指定のガイダンス |
| 接続エラー | Stop-Function -Continue | "Failure" と ConnectionError カテゴリ |
| AD 検索エラー | Write-Message Warning | "AD Searcher Error" |

## 備考

- NT *、BUILTIN\*、ローカルアカウント（ComputerName\*）は検証対象外
- UserAccountControl フラグで多数のセキュリティ属性を解析
- コンピュータアカウント（$で終わる）は Type=Computer として処理
- グループアカウントは Enabled 等のセキュリティプロパティが null
- SID ベースで AD 検索を行い、孤立アカウントを検出

---

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

### 推奨読解順序

#### Step 1: UserAccountControl マッピング

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaWindowsLogin.ps1 | `public/Test-DbaWindowsLogin.ps1` | 行 131-155: UAC フラグマッピング |

**主要処理フロー**:
- **行 131-155**: UserAccountControl ビットフラグの定義
- **行 259-273**: UAC 値からプロパティへの変換

#### Step 2: AD 検証ロジック

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaWindowsLogin.ps1 | `public/Test-DbaWindowsLogin.ps1` | 行 202-296: Windows ユーザー検証 |
| 2-2 | Test-DbaWindowsLogin.ps1 | `public/Test-DbaWindowsLogin.ps1` | 行 298-355: Windows グループ検証 |

**主要処理フロー**:
- **行 214-218**: Get-DbaADObject で AD 検索
- **行 231-235**: SID 比較
- **行 236-240**: SamAccountName 比較

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

```
Test-DbaWindowsLogin
    |
    +-- begin ブロック
    |       |
    |       +-- IgnoreDomains 正規化
    |       +-- UserAccountControl マッピング定義
    |
    +-- process ブロック
    |       |
    |       +-- Connect-DbaInstance
    |       +-- $server.Logins | Where-Object (WindowsUser/WindowsGroup)
    |       +-- InputObject 処理
    |
    +-- end ブロック
            |
            +-- 除外フィルタ (NT *, BUILTIN\*, ComputerName\*)
            +-- Login/ExcludeLogin フィルタ
            +-- FilterBy 分岐
            |
            +-- foreach ($winLogin in $windowsLogins)
            |       |
            |       +-- SID → SecurityIdentifier 変換
            |       +-- Get-DbaADObject (User/Computer)
            |       +-- SID 比較
            |       +-- SamAccountName 比較
            |       +-- UserAccountControl 解析
            |       +-- PSCustomObject 出力
            |
            +-- foreach ($winLogin in $windowsGroups)
                    |
                    +-- Get-DbaADObject (Group)
                    +-- SID/SamAccountName 比較
                    +-- PSCustomObject 出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaWindowsLogin.ps1 | `public/Test-DbaWindowsLogin.ps1` | ソース | Windows ログイン AD 検証 |
| Get-DbaADObject.ps1 | `public/Get-DbaADObject.ps1` | ソース | AD オブジェクト取得（内部使用） |
