# 機能設計書 549-Find-DbaLoginInGroup

## 概要

本ドキュメントは、SQL Serverインスタンス上のWindowsグループログイン内の個々のActive Directoryユーザーを検出するPowerShell関数`Find-DbaLoginInGroup`の機能設計書である。

### 本機能の処理概要

Find-DbaLoginInGroupは、SQL Serverインスタンスに接続し、すべてのWindows Active Directoryグループログインを再帰的に展開して、グループメンバーシップを通じてアクセス権を継承している個々のユーザーアカウントを明らかにする。Active Directoryを照会して、ネストされたグループを含む各Windowsグループログイン内のすべてのユーザーを列挙し、グループベース認証を通じて誰が実際にSQL Serverにアクセスできるかの完全なビューを提供する。

**業務上の目的・背景**：SQL Serverへのアクセスは、多くの場合Windowsグループを通じて付与される。しかし、実際にどのユーザーがグループ経由でアクセス権を持っているかを把握することは困難である。セキュリティ監査、コンプライアンスレポート、ログインアクセス問題のトラブルシューティングにおいて、グループメンバーシップの詳細な把握が不可欠となる。

**機能の利用シーン**：
- セキュリティ監査でのアクセス権限の完全な把握
- コンプライアンスレポートのためのアクセス者リスト生成
- 特定ユーザーがどのグループ経由でアクセス可能かの調査
- ユーザー退職時のアクセス権確認
- Active Directoryグループ整理の影響調査

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. WindowsGroupタイプのログイン一覧取得
3. 各グループに対するActive Directoryへの照会
4. ネストグループの再帰的展開
5. 個別ユーザーアカウントの抽出
6. 結果の出力

**関連システム・外部連携**：System.DirectoryServices.AccountManagement名前空間を使用してActive Directoryと連携。

**権限による制御**：SQL ServerおよびActive Directoryへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | なし（CLI専用機能） | - | PowerShellコマンドラインから実行 |

## 機能種別

検索・照会 / セキュリティ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | ValueFromPipeline |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | 有効なPSCredential |
| Login | string[] | No | 検索対象の個人ユーザー名 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- SQL Server sys.server_principalsシステムビュー（WindowsGroup）
- Active Directory（System.DirectoryServices.AccountManagement経由）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | SQL Serverインスタンス名 |
| Login | string | 個別ユーザーアカウント（DOMAIN\username形式） |
| DisplayName | string | ADのDisplayName |
| MemberOf | string | 所属するADグループログイン |
| ParentADGroupLogin | string | 親グループ（ネストグループの場合） |
| InstanceName | string | インスタンス名のみ |
| ComputerName | string | コンピュータ名 |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. アセンブリ読み込み
   └─ System.DirectoryServices.AccountManagement
2. インスタンスループ
   └─ 各SqlInstanceに対して処理
3. SQL Server接続
   └─ Connect-DbaInstance
4. ADグループログイン取得
   └─ LoginType='WindowsGroup'でフィルタ
   └─ BUILTIN\Administrators、NT SERVICE除外
   └─ ローカルグループ除外
5. グループメンバー取得（Get-AllLogins内部関数）
   └─ PrincipalContext作成
   └─ GroupPrincipal.FindByIdentity
   └─ Members列挙
6. ネストグループ処理
   └─ StructuralObjectClass='group'の場合再帰呼び出し
7. 結果出力
   └─ Login指定時はフィルタリング
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[アセンブリ読み込み]
    B --> C{読み込み成功?}
    C -->|No| D[エラー終了]
    C -->|Yes| E[インスタンスループ]
    E --> F[SQL Server接続]
    F --> G[ADグループログイン取得]
    G --> H[グループループ]
    H --> I[Get-AllLogins呼び出し]
    I --> J[ADグループ接続]
    J --> K[メンバー列挙]
    K --> L{グループ?}
    L -->|Yes| M[再帰呼び出し]
    L -->|No| N[ユーザー情報出力]
    M --> K
    N --> O{全メンバー完了?}
    O -->|No| K
    O -->|Yes| P{全グループ完了?}
    P -->|No| H
    P -->|Yes| Q{Login指定?}
    Q -->|Yes| R[フィルタリング]
    Q -->|No| S[全結果出力]
    R --> T{全インスタンス完了?}
    S --> T
    T -->|No| E
    T -->|Yes| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-549-01 | BUILTIN除外 | BUILTIN\Administratorsは処理対象外 | 常時 |
| BR-549-02 | NT SERVICE除外 | NT SERVICE*は処理対象外 | 常時 |
| BR-549-03 | ローカルグループ除外 | コンピュータ名\*のグループは除外 | 常時 |
| BR-549-04 | 再帰展開 | ネストグループは再帰的に展開 | 常時 |
| BR-549-05 | 重複防止 | 既に列挙したグループは再処理しない | ネストグループ処理時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ログイン取得 | sys.server_principals | SELECT | WindowsGroupログイン一覧 |

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

読み取り専用。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アセンブリエラー | DirectoryServicesアセンブリ読み込み失敗 | .NET環境を確認 |
| ConnectionError | 接続エラー | SQL Server接続失敗 | 接続情報を確認 |
| - | ADエラー | グループへの接続失敗 | AD権限・接続を確認 |

### リトライ仕様

リトライ機能なし。グループ処理エラー時は警告出力して継続。

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

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

## パフォーマンス要件

特に定義なし。大規模ADグループや深いネストでは処理時間が増加する可能性がある。

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

- SQL Serverへのアクセス権限が必要
- Active Directoryへの読み取りアクセス権限が必要
- ドメイン信頼関係がある環境でのみ動作

## 備考

- Windowsプラットフォームのみサポート
- Active Directory環境が必要
- ローカルグループはサポート対象外

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Find-DbaLoginInGroup.ps1 | `public/Find-DbaLoginInGroup.ps1` | 70-78行目のパラメータ定義 |

#### Step 2: 内部関数Get-AllLoginsを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaLoginInGroup.ps1 | `public/Find-DbaLoginInGroup.ps1` | 87-141行目の内部関数 |

**主要処理フロー**:
- **99-100行目**: ドメインとグループ名の分離
- **101-102行目**: PrincipalContextとGroupPrincipal作成
- **104-124行目**: メンバー列挙とタイプ判定
- **130-136行目**: ネストグループの再帰処理

**読解のコツ**: $discardリストで処理済みグループを追跡し、無限ループを防止。

#### Step 3: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Find-DbaLoginInGroup.ps1 | `public/Find-DbaLoginInGroup.ps1` | 144-173行目 |

**主要処理フロー**:
- **154-156行目**: WindowsGroupフィルタリング（BUILTIN、NT SERVICE除外）
- **158-161行目**: 各グループでGet-AllLogins呼び出し
- **163-170行目**: Login指定時のフィルタリング

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

```
Find-DbaLoginInGroup
    │
    ├─ Add-Type (System.DirectoryServices.AccountManagement)
    │
    ├─ Connect-DbaInstance
    │
    ├─ Server.Logins (WindowsGroup取得)
    │
    └─ Get-AllLogins (内部関数)
        ├─ PrincipalContext
        ├─ GroupPrincipal.FindByIdentity
        ├─ Group.Members列挙
        └─ Get-AllLogins (再帰呼び出し)
```

### データフロー図

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

SqlInstance       ───▶ Connect-DbaInstance     ───▶ SMO Server Object
    │                                                      │
    ▼                                                      ▼
Server.Logins     ───▶ Filter WindowsGroup     ───▶ AD Group List
(WindowsGroup)                                             │
    │                                                      ▼
    ▼
Active Directory  ───▶ GroupPrincipal          ───▶ Member Collection
    │                                                      │
    ▼                                                      ▼
Nested Groups     ───▶ Recursive Expansion     ───▶ User Accounts
    │                                                      │
    ▼                                                      ▼
$ADGroupOut       ───▶ Filter by Login param   ───▶ PSCustomObject Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaLoginInGroup.ps1 | `public/Find-DbaLoginInGroup.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
