# 画面設計書 67-ログイン権限同期

## 概要

本ドキュメントは、dbatools PowerShell モジュールにおける SQL Server ログイン権限同期機能の設計仕様を定義する。ソースインスタンスからターゲットインスタンスへログインの権限およびロールメンバーシップを同期する。

### 本画面の処理概要

本機能は、ソース SQL Server インスタンスからターゲットインスタンスへログインのセキュリティ設定を同期する。サーバーロール（sysadmin、bulkadmin 等）、サーバーレベル権限（Connect SQL、View any database 等）、SQL Agent ジョブ所有権、資格情報マッピング、データベースユーザーマッピング、データベースロール（db_owner、db_datareader 等）、データベースレベル権限を処理する。

**業務上の目的・背景**：DBA は開発、ステージング、本番環境間で一貫したセキュリティ構成を維持する必要がある。また、サーバー再構築時にログインを再作成せずに権限を復元する場合にも使用される。本機能により、既存のログインの権限のみを同期し、ログイン自体の作成・削除は行わない。

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

**主要な操作・処理内容**：
1. `Sync-DbaLoginPermission` - ログイン権限を同期
2. Login パラメータで特定ログインのみ同期
3. ExcludeLogin パラメータで特定ログインを除外
4. 複数の Destination に同時同期可能

**画面遷移**：
- Get-DbaLogin → Sync-DbaLoginPermission への連携
- Sync-DbaLoginPermission → Format-Table で結果出力

**権限による表示制御**：ソースおよびターゲットで sysadmin 権限が必要。SQL Server 2000 以上が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Sync-DbaLoginPermission | 主機能 | ログイン権限の同期 |
| - | Get-DbaLogin | 補助機能 | ログイン取得（内部使用） |
| - | Copy-DbaLogin | 関連機能 | ログインのコピー（権限含む） |

## 画面種別

CLI（コマンドラインインターフェース）/ 操作実行

## URL/ルーティング

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

```powershell
Sync-DbaLoginPermission -Source <ソースインスタンス> -Destination <ターゲットインスタンス>
Sync-DbaLoginPermission -Source <ソース> -Destination <ターゲット> -Login realcajun, netnerds
Sync-DbaLoginPermission -Source <ソース> -Destination <ターゲット> -ExcludeLogin serviceaccount
```

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| Source | DbaInstanceParameter | Yes | ソースSQL Serverインスタンス |
| SourceSqlCredential | PSCredential | No | ソース接続用認証情報 |
| Destination | DbaInstanceParameter[] | Yes | ターゲットSQL Serverインスタンス（複数可） |
| DestinationSqlCredential | PSCredential | No | ターゲット接続用認証情報 |
| Login | string[] | No | 同期対象ログイン名 |
| ExcludeLogin | string[] | No | 除外ログイン名 |
| WhatIf | switch | No | 実行せずに動作を表示 |
| Confirm | switch | No | 実行前に確認 |
| EnableException | switch | No | 例外処理を有効化 |

## 表示項目

### Sync-DbaLoginPermission 出力（MigrationObject）

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| DateTime | DbaDateTime | 同期実行日時 |
| SourceServer | string | ソースサーバー名 |
| DestinationServer | string | ターゲットサーバー名 |
| Name | string | ログイン名 |
| Type | string | 操作タイプ（常に "Login Permissions"） |
| Status | string | 結果（Successful/Failed） |
| Notes | string | エラーメッセージ（失敗時）、成功時は null |

## イベント仕様

### 1-Sync-DbaLoginPermission 実行

1. Connect-DbaInstance でソースサーバーに接続
2. Get-DbaLogin でソースからログイン取得（Login/ExcludeLogin フィルタリング）
3. 現在のログイン（TrueLogin）を取得（自身の権限は同期しない）
4. 各 Destination に対して Connect-DbaInstance（MinimumVersion 8）
5. 各ログインについて：
   - 現在のログインはスキップ
   - ホストベース/システムログイン（NT *）はスキップ
   - ターゲットに存在しないログインはスキップ
6. Update-SqlPermission で権限を同期
7. PSCustomObject で結果を出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Sync-DbaLoginPermission | サーバーロール、データベースロール、権限 | UPDATE | 権限設定の同期 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|----------|
| - | エラー | "Failure" | 接続エラー |
| - | エラー | "No matching logins found for ... on $Source" | ログインが見つからない |
| - | Verbose | "Sync does not modify the permissions of the current login..." | 現在のログインをスキップ |
| - | Verbose | "Sync does not modify the permissions of host or system login..." | ホスト/システムログインをスキップ |
| - | Verbose | "Login '...' not found on destination. Skipping." | ターゲットにログインが存在しない |

## 例外処理

| 例外条件 | ハンドリング | ユーザーへのフィードバック |
|---------|-------------|-------------------------|
| ソース接続エラー | Stop-Function | "Failure" と ConnectionError カテゴリ |
| ターゲット接続エラー | Stop-Function -Continue | "Failure" と ConnectionError カテゴリ |
| 権限同期エラー | Stop-Function -Continue | Status=Failed、Notes にエラー詳細 |

## 備考

- SQL Server 2000 以上が必要（MinimumVersion 8）
- ログイン自体の作成・削除は行わない（権限のみ同期）
- 現在接続中のログインの権限は変更しない（ロックアウト防止）
- ホストベースログイン（サーバー名\ユーザー）はスキップ
- システムログイン（NT * で始まる）はスキップ
- Update-SqlPermission 内部関数で実際の権限同期を実行
- SupportsShouldProcess で WhatIf/Confirm をサポート

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Sync-DbaLoginPermission.ps1 | `public/Sync-DbaLoginPermission.ps1` | 行 104-148: ログイン取得とスキップ処理 |

**主要処理フロー**:
- **行 107-112**: ソースサーバー接続
- **行 114-118**: Get-DbaLogin でログイン取得
- **行 121**: 現在のログイン（TrueLogin）取得
- **行 133-144**: スキップ条件（現在のログイン、ホスト/システムログイン）

#### Step 2: 権限同期と結果出力

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Sync-DbaLoginPermission.ps1 | `public/Sync-DbaLoginPermission.ps1` | 行 152-173: 同期実行と結果出力 |

**主要処理フロー**:
- **行 152-160**: PSCustomObject 構築（MigrationObject）
- **行 163**: Update-SqlPermission 呼び出し
- **行 166**: Select-DefaultView で出力

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

```
Sync-DbaLoginPermission
    |
    +-- Test-FunctionInterrupt
    |
    +-- Connect-DbaInstance (Source)
    |
    +-- Get-DbaLogin
    |
    +-- $sourceServer.ConnectionContext.TrueLogin
    |
    +-- foreach ($dest in $Destination)
            |
            +-- Connect-DbaInstance (MinimumVersion 8)
            |
            +-- foreach ($sourceLogin)
                    |
                    +-- スキップ条件チェック
                    |       |
                    |       +-- 現在のログイン
                    |       +-- ホストベースログイン
                    |       +-- システムログイン (NT *)
                    |       +-- ターゲットに存在しないログイン
                    |
                    +-- Write-ProgressHelper
                    |
                    +-- Update-SqlPermission
                    |
                    +-- Select-DefaultView (MigrationObject)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Sync-DbaLoginPermission.ps1 | `public/Sync-DbaLoginPermission.ps1` | ソース | ログイン権限同期 |
| Get-DbaLogin.ps1 | `public/Get-DbaLogin.ps1` | ソース | ログイン取得（内部使用） |
| Update-SqlPermission.ps1 | `private/functions/Update-SqlPermission.ps1` | ソース | 権限更新（内部関数） |
