# 機能設計書 22-Revoke-DbaAgPermission

## 概要

本ドキュメントは、SQL Serverログインから可用性グループまたはデータベースミラーリングエンドポイントの権限を取り消すRevoke-DbaAgPermission機能の設計仕様を記述する。

### 本機能の処理概要

Revoke-DbaAgPermissionは、SQL Serverログインからデータベースミラーリングエンドポイントまたは可用性グループに対する権限を取り消すPowerShellコマンドレットである。

**業務上の目的・背景**：可用性グループ環境のセキュリティ管理において、サービスアカウントの変更、セキュリティポリシーの更新、または可用性グループのメンテナンス時に権限の削除が必要となる。本機能は、エンドポイントや可用性グループからConnect、Alter、Control等の権限を効率的に取り消すことを可能にする。

**機能の利用シーン**：
- サービスアカウント変更時の旧アカウントからの権限削除
- セキュリティポリシー変更に伴う権限の縮小
- 可用性グループの再構成前の権限クリーンアップ
- 不要なアクセス権の棚卸と削除

**主要な処理内容**：
1. SqlInstanceまたはInputObjectパラメータから対象ログインを特定
2. Type（Endpoint/AvailabilityGroup）に応じて処理を分岐
3. エンドポイント権限の場合：DatabaseMirroringエンドポイントのRevoke()メソッドを実行
4. 可用性グループ権限の場合：可用性グループオブジェクトのRevoke()メソッドを実行
5. 処理結果をPSCustomObjectとして返却

**関連システム・外部連携**：SQL Server Management Objects (SMO) のEndpoint、AvailabilityGroup、Loginクラスを使用してSQL Serverと連携する。

**権限による制御**：エンドポイントまたは可用性グループに対するCONTROL権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | AG権限管理 | 主機能 | 可用性グループからの権限取り消し |

## 機能種別

セキュリティ操作（権限取り消し）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス（SQL Server 2012以上） | - |
| SqlCredential | PSCredential | No | 代替認証情報 | 有効なPSCredential |
| Login | string[] | No | 権限を取り消すログイン名 | SqlInstance使用時は必須 |
| AvailabilityGroup | string[] | No | 対象可用性グループ名 | TypeがAvailabilityGroupの場合は必須 |
| Type | string[] | Yes | 権限取り消し対象種別（Endpoint/AvailabilityGroup） | ValidateSetで制限 |
| Permission | string[] | No | 取り消す権限（デフォルト：Connect） | ValidateSetで許可値を制限 |
| InputObject | Login[] | No | パイプラインからのログインオブジェクト | SqlInstanceまたはInputObjectいずれか必須 |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- SqlInstanceパラメータ：SQL Serverインスタンス名の直接指定
- InputObjectパラメータ：Get-DbaLoginからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | 権限を取り消したログイン名 |
| Permission | string | 取り消した権限 |
| Type | string | 操作種別（常に"Revoke"） |
| Status | string | 処理結果（"Success"） |

### 出力先

- PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstanceまたはInputObjectのいずれかが指定されていることを確認
2. 追加パラメータ検証
   └─ SqlInstance指定時にLoginまたはAvailabilityGroupが指定されていることを確認
   └─ TypeがAvailabilityGroupの場合、AvailabilityGroupが指定されていることを確認
3. ログインオブジェクト取得
   └─ Get-DbaLoginを使用してLoginオブジェクトを取得
   └─ 存在しないログインはNew-DbaLoginで作成
4. Type別処理
   └─ Endpoint: DatabaseMirroringエンドポイントに対してRevoke()実行
   └─ AvailabilityGroup: 指定AGに対してRevoke()実行
5. 結果出力
   └─ 処理成功時にPSCustomObjectを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance or InputObject?}
    B -->|Neither| C[Stop-Function: パラメータエラー]
    B -->|OK| D{SqlInstance and Login/AG?}
    D -->|No| E[Stop-Function: パラメータエラー]
    D -->|OK| F{Type = AvailabilityGroup?}
    F -->|Yes| G{AvailabilityGroup指定?}
    G -->|No| H[Stop-Function: パラメータエラー]
    G -->|Yes| I[Get-DbaLogin実行]
    F -->|No| I
    I --> J{Permission = CreateAnyDatabase?}
    J -->|Yes| K[ALTER AG GRANTクエリ実行]
    J -->|No| L[foreach account in InputObject]
    K --> L
    L --> M{Type contains Endpoint?}
    M -->|Yes| N[エンドポイント取得]
    N --> O{エンドポイント存在?}
    O -->|No| P[Stop-Function: エンドポイントなし]
    O -->|Yes| Q[foreach perm in Permission]
    Q --> R[Endpoint.Revoke実行]
    R --> S[結果出力]
    M -->|No| T{Type contains AG?}
    T -->|Yes| U[Get-DbaAvailabilityGroup]
    U --> V[foreach ag, foreach perm]
    V --> W{権限サポート?}
    W -->|No| X[Stop-Function: 非サポート権限]
    W -->|Yes| Y[AG.Revoke実行]
    Y --> Z[結果出力]
    S --> AA{次のアカウント?}
    Z --> AA
    P --> AA
    X --> AA
    AA -->|Yes| L
    AA -->|No| AB[終了]
    C --> AB
    E --> AB
    H --> AB
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | パラメータ相互排他 | SqlInstanceまたはInputObjectのいずれかが必須 | 常時 |
| BR-02 | ログイン指定必須 | SqlInstance指定時はLoginまたはAvailabilityGroupが必須 | SqlInstance指定時 |
| BR-03 | AG指定必須 | TypeがAvailabilityGroupの場合はAvailabilityGroupが必須 | Type=AvailabilityGroup時 |
| BR-04 | エンドポイント権限制限 | CreateAnyDatabaseはエンドポイントでサポートされない | Type=Endpoint時 |
| BR-05 | AG権限制限 | Alter, Control, TakeOwnership, ViewDefinitionのみサポート | Type=AvailabilityGroup時 |

### 計算ロジック

特になし（権限操作のため）

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

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

| 操作 | 対象オブジェクト | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Revoke Endpoint | sys.server_permissions | DELETE | エンドポイント権限の取り消し |
| Revoke AG | sys.server_permissions | DELETE | 可用性グループ権限の取り消し |

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

#### sys.server_permissions

SMOのRevoke()メソッドにより内部的にREVOKE文が実行され、対象権限が削除される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | SqlInstanceとInputObjectの両方が未指定 | Stop-Functionでエラーメッセージ出力 |
| - | パラメータエラー | SqlInstance指定時にLogin/AGが未指定 | Stop-Functionでエラーメッセージ出力 |
| - | パラメータエラー | TypeがAGでAvailabilityGroupが未指定 | Stop-Functionでエラーメッセージ出力 |
| - | オブジェクトエラー | DatabaseMirroringエンドポイントが存在しない | Stop-Functionで継続可能エラー |
| - | 権限エラー | サポートされない権限を指定 | Stop-Functionで継続可能エラー |
| - | 操作エラー | Revoke失敗 | Stop-Functionで継続可能エラー |

### リトライ仕様

リトライ機能は実装されていない。エラー発生時は次のアカウントの処理を継続する（-Continueフラグ使用）。

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

SMOのRevoke()メソッドは内部的にSQL Serverトランザクションを使用する。各アカウント・権限の操作は独立しており、1つの操作でエラーが発生しても他の操作は継続される。

## パフォーマンス要件

特に定義なし。操作自体は軽量で、通常は数秒以内に完了する。

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

- Windows認証、SQL Server認証、Active Directory認証をサポート
- MFA認証にはConnect-DbaInstanceの事前使用が必要
- エンドポイントまたは可用性グループに対するCONTROL権限が必要
- ShouldProcess実装によりWhatIfおよびConfirmをサポート

## 備考

- SQL Server 2012以上が必要
- 存在しないログインは自動的に作成される（New-DbaLogin使用）
- ConfirmImpactがLowに設定されているため、デフォルトでは確認プロンプトは表示されない

---

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

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

### 推奨読解順序

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

SMOのLoginクラス、Endpointクラス、AvailabilityGroupクラスが中心的なデータ構造である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Revoke-DbaAgPermission.ps1 | `public/Revoke-DbaAgPermission.ps1` | パラメータ定義と型（97-110行目）を確認 |

**読解のコツ**: ValidateSetで許可されるPermission値を確認。エンドポイントとAGで使用可能な権限が異なる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Revoke-DbaAgPermission.ps1 | `public/Revoke-DbaAgPermission.ps1` | process ブロック（111-220行目）がメイン処理 |

**主要処理フロー**:
1. **112-125行目**: パラメータ検証
2. **127-156行目**: ログインオブジェクト取得とCreateAnyDatabase特殊処理
3. **158-190行目**: エンドポイント権限取り消し処理
4. **192-218行目**: 可用性グループ権限取り消し処理

#### Step 3: 権限操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Revoke-DbaAgPermission.ps1 | `public/Revoke-DbaAgPermission.ps1` | ObjectPermissionSetの構築（174行目、201行目） |

**主要処理フロー**:
- **174行目**: `New-Object Microsoft.SqlServer.Management.Smo.ObjectPermissionSet`でPermissionSetを構築
- **175行目**: `endpoint.Revoke($bigperms, $account.Name)`でエンドポイント権限取り消し
- **202行目**: `$ag.Revoke($bigperms, $account.Name)`でAG権限取り消し

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

```
Revoke-DbaAgPermission
    │
    ├─ Test-Bound (パラメータ検証)
    │
    ├─ Stop-Function (エラー処理)
    │
    ├─ Connect-DbaInstance (接続)
    │
    ├─ Get-DbaLogin (ログイン取得)
    │
    ├─ New-DbaLogin (ログイン作成、必要時)
    │
    ├─ Get-DbaAvailabilityGroup (AG取得)
    │
    ├─ Endpoint.Revoke() (SMOメソッド)
    │
    └─ AvailabilityGroup.Revoke() (SMOメソッド)
```

### データフロー図

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

SqlInstance ───────────┐
                       │
SqlCredential ─────────┼──▶ Get-DbaLogin ──▶ Login[]
                       │            │
Login ─────────────────┤            │
                       │            ▼
AvailabilityGroup ─────┤     Type分岐処理
                       │      /        \
Type ──────────────────┤   Endpoint    AG
                       │      │         │
Permission ────────────┘      ▼         ▼
                         Revoke()   Revoke()
                              │         │
                              ▼         ▼
InputObject ──────────────────────────────────────▶ PSCustomObject[]
  (パイプライン)                                        (結果オブジェクト)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Revoke-DbaAgPermission.ps1 | `public/Revoke-DbaAgPermission.ps1` | ソース | メイン機能実装 |
| Grant-DbaAgPermission.ps1 | `public/Grant-DbaAgPermission.ps1` | ソース | 対になる権限付与機能 |
| Get-DbaLogin.ps1 | `public/Get-DbaLogin.ps1` | ソース | ログイン取得 |
| Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | ソース | 可用性グループ取得 |
