# 画面設計書 68-グループ内ログイン

## 概要

本ドキュメントは、dbatools PowerShell モジュールにおける Windows Active Directory グループ内の個別ユーザー検索機能の設計仕様を定義する。SQL Server の Windows グループログインを展開し、グループメンバーシップを通じてアクセス権を継承する個別ユーザーアカウントを特定する。

### 本画面の処理概要

本機能は、SQL Server インスタンスに接続し、すべての Windows Active Directory グループログインを再帰的に展開して、グループメンバーシップを通じてアクセス権を継承する個別ユーザーアカウントを明らかにする。Active Directory をクエリしてネストされたグループを含む各 Windows グループログイン内のすべてのユーザーを列挙する。

**業務上の目的・背景**：DBA はセキュリティ監査、コンプライアンスレポート作成、ログインアクセス問題のトラブルシューティングで、グループログインを通じて SQL Server に接続できる特定のユーザーを把握する必要がある。本機能により、グループベース認証を通じて実際にアクセスできるユーザーの完全なビューを提供する。

**画面へのアクセス方法**：PowerShell コンソールから `Find-DbaLoginInGroup` コマンドを直接呼び出す。

**主要な操作・処理内容**：
1. `Find-DbaLoginInGroup` - AD グループ内のユーザーを検索
2. WindowsGroup タイプのログインを取得
3. Active Directory の PrincipalContext でグループメンバーを列挙
4. ネストされたグループを再帰的に展開
5. Login パラメータで特定ユーザーを含むグループのみフィルタリング

**画面遷移**：
- Find-DbaLoginInGroup → Format-Table で表形式出力
- Find-DbaLoginInGroup → Where-Object でフィルタリング

**権限による表示制御**：SQL Server へのアクセス権限と Active Directory への読み取り権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Find-DbaLoginInGroup | 主機能 | AD グループ内ユーザーの検索 |
| - | Get-DbaLogin | 関連機能 | ログイン取得 |

## 画面種別

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

## URL/ルーティング

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

```powershell
Find-DbaLoginInGroup -SqlInstance <インスタンス名>
Find-DbaLoginInGroup -SqlInstance <インスタンス名> -Login "MyDomain\Stephen.Bennett"
```

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 認証情報 |
| Login | string[] | No | 検索対象ユーザー（DOMAIN\username 形式） |
| EnableException | switch | No | 例外処理を有効化 |

## 表示項目

### Find-DbaLoginInGroup 出力（デフォルト表示）

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| SqlInstance | string | SQL Server インスタンス名 |
| Login | string | 個別ユーザーアカウント（DOMAIN\username 形式） |
| DisplayName | string | Active Directory 表示名 |
| MemberOf | string | ユーザーが所属する AD グループログイン |
| ParentADGroupLogin | string | 元の親グループログイン（ネストグループの場合は MemberOf と異なる） |

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

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| InstanceName | string | インスタンス名のみ |
| ComputerName | string | コンピュータ名 |

## イベント仕様

### 1-Find-DbaLoginInGroup 実行

1. System.DirectoryServices.AccountManagement アセンブリをロード
2. Connect-DbaInstance で SQL Server に接続
3. $server.Logins から WindowsGroup タイプのログインを取得
4. BUILTIN\Administrators と NT SERVICE\* を除外
5. ローカルグループ（ComputerName\*）を除外
6. 各グループについて Get-AllLogins 内部関数を呼び出し：
   - PrincipalContext でドメインに接続
   - GroupPrincipal.FindByIdentity でグループを検索
   - メンバーを列挙（ネストグループは再帰的に展開）
   - PSCustomObject でユーザー情報を出力
7. Login パラメータ指定時は結果をフィルタリング
8. Select-DefaultView で表示列を制限して出力

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

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

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

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|----------|
| - | エラー | "Failed to load Assembly needed" | アセンブリロード失敗 |
| - | エラー | "Failure" | 接続エラー |
| - | エラー | "Failed to connect to Group: $member." | AD グループ接続失敗 |
| - | Verbose | "skipping $fullName, already enumerated" | 既に列挙済みのグループをスキップ |
| - | Verbose | "Looking at $gr, recursively." | 再帰的にネストグループを展開 |
| - | Verbose | "Looking at Group: $AdGroup" | グループ処理開始 |

## 例外処理

| 例外条件 | ハンドリング | ユーザーへのフィードバック |
|---------|-------------|-------------------------|
| アセンブリロード失敗 | Stop-Function | "Failed to load Assembly needed" |
| 接続エラー | Stop-Function -Continue | "Failure" と ConnectionError カテゴリ |
| AD グループ接続失敗 | Stop-Function | "Failed to connect to Group" |

## 備考

- System.DirectoryServices.AccountManagement アセンブリが必要
- BUILTIN\Administrators と NT SERVICE\* は除外される
- ローカルグループ（ComputerName\*）は除外される（#7820）
- ネストされたグループは再帰的に展開される
- 既に列挙済みのグループはスキップされる（循環参照防止）
- Login パラメータで特定ユーザーを含むグループのみ出力可能

---

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

### 推奨読解順序

#### Step 1: AD グループ展開ロジック

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

**主要処理フロー**:
- **行 99-102**: PrincipalContext でドメイン接続、GroupPrincipal.FindByIdentity でグループ検索
- **行 104-125**: メンバー列挙（グループとユーザーを区別）
- **行 130-136**: ネストグループの再帰処理

#### Step 2: ログイン取得とフィルタリング

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaLoginInGroup.ps1 | `public/Find-DbaLoginInGroup.ps1` | 行 147-172: メイン処理 |

**主要処理フロー**:
- **行 154-156**: WindowsGroup ログイン取得と除外フィルタ
- **行 163-170**: Login パラメータによるフィルタリング
- **行 171**: Select-DefaultView で出力

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

```
Find-DbaLoginInGroup
    |
    +-- begin ブロック
    |       |
    |       +-- Add-Type (System.DirectoryServices.AccountManagement)
    |       +-- Get-AllLogins 関数定義
    |
    +-- process ブロック
            |
            +-- Connect-DbaInstance
            |
            +-- $server.Logins | Where-Object
            |       |
            |       +-- LoginType -eq "WindowsGroup"
            |       +-- 除外: BUILTIN\Administrators
            |       +-- 除外: *NT SERVICE*
            |       +-- 除外: $server.ComputerName\*
            |
            +-- foreach ($AdGroup)
            |       |
            |       +-- Get-AllLogins (再帰)
            |               |
            |               +-- PrincipalContext
            |               +-- GroupPrincipal.FindByIdentity
            |               +-- foreach ($member)
            |                       |
            |                       +-- (group) → 再帰呼び出し
            |                       +-- (user) → PSCustomObject 出力
            |
            +-- (Login 指定時) Where-Object フィルタリング
            |
            +-- Select-DefaultView
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaLoginInGroup.ps1 | `public/Find-DbaLoginInGroup.ps1` | ソース | AD グループ内ユーザー検索 |
