# 帳票設計書 5-Export-DbaLogin

## 概要

本ドキュメントは、dbatools PowerShellモジュールのExport-DbaLoginコマンドレットに関する帳票設計書です。SQL Serverログインをセキュリティコンテキスト付きでT-SQLスクリプトとして生成し、移行や災害復旧に使用する機能について記載しています。

### 本帳票の処理概要

Export-DbaLoginは、SQL ServerおよびWindowsログインを完全なセキュリティ構成とともにT-SQLスクリプトとして出力するコマンドレットです。ログインプロパティ（SID、ハッシュ化パスワード、デフォルトデータベース）、サーバーレベル権限とロールメンバーシップ、データベースユーザーマッピングとロール、SQLエージェントジョブ所有権の割り当てを含みます。

**業務上の目的・背景**：データベースを復元しても関連するログインは復元されないため、アプリケーションが接続できない問題が発生します。本コマンドはサーバー移行、災害復旧シナリオ、および環境間で一貫したセキュリティを維持するための課題を解決します。

**帳票の利用シーン**：
1. SQL Serverインスタンス間のログイン移行
2. 災害復旧用のログイン定義バックアップ
3. 開発・テスト環境への本番ログイン複製
4. セキュリティ監査用のログイン構成ドキュメント化
5. 複数データベースを持つログインの一括移行

**主要な出力内容**：
1. CREATE LOGIN文（SQL認証：ハッシュ化パスワード、SID付き / Windows認証）
2. サーバーロールメンバーシップ（ALTER SERVER ROLE / sp_addsrvrolemember）
3. サーバーレベル権限（GRANT/DENY文）
4. データベースユーザーマッピングとロール
5. SQLエージェントジョブ所有権割り当て

**帳票の出力タイミング**：Export-DbaLoginコマンドを実行した時点でT-SQLスクリプトが生成され、ファイル出力またはパイプライン出力されます。

**帳票の利用者**：データベース管理者（DBA）、セキュリティ管理者、システム管理者

## 帳票種別

ログイン定義スクリプト（T-SQL）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | PowerShellコンソール | N/A | Export-DbaLoginコマンド実行 |
| N/A | SQLスクリプト実行 | SSMS/sqlcmd | 生成スクリプトの実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | SQL (.sql) |
| 用紙サイズ | N/A（スクリプトファイル） |
| 向き | N/A |
| ファイル名 | 自動生成（インスタンス名-タイムスタンプ.sql） |
| 出力方法 | ファイル出力 / パイプライン出力 |
| 文字コード | UTF8（デフォルト） |

### 出力モード

| モード | 条件 | 出力先 |
|-------|------|-------|
| ファイル出力 | -Path または -FilePath 指定時 | 指定ファイル |
| パイプライン出力 | -Passthru 指定時 | パイプライン |
| コンソール出力 | 上記以外 | コンソール |

## 帳票レイアウト

### レイアウト概要

T-SQLスクリプトは論理的なセクションで構成されます。

```
┌─────────────────────────────────────┐
│    ヘッダーコメント（オプション）      │
│  (作成日時、作成者、dbatools情報)     │
├─────────────────────────────────────┤
│    USE master                       │
│    GO                               │
├─────────────────────────────────────┤
│    CREATE LOGIN文                   │
│    GO                               │
├─────────────────────────────────────┤
│    ALTER LOGIN (無効化/DENY等)       │
│    GO                               │
├─────────────────────────────────────┤
│    サーバーロールメンバーシップ         │
│    GO                               │
├─────────────────────────────────────┤
│    ジョブ所有権割り当て               │
│    GO                               │
├─────────────────────────────────────┤
│    サーバーレベル権限                 │
│    GO                               │
├─────────────────────────────────────┤
│    USE [database]                   │
│    データベースユーザー/ロール         │
│    GO                               │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | コメント | 作成日時、作成者、バージョン情報 | 自動生成 | /* ... */ |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | USE文 | データベースコンテキスト | 固定 | T-SQL | 可変 |
| 2 | CREATE LOGIN | ログイン作成文 | SMO Login | T-SQL | 可変 |
| 3 | ALTER LOGIN | ログイン状態変更 | IsDisabled, DenyWindowsLogin | T-SQL | 可変 |
| 4 | サーバーロール | ロールメンバーシップ追加 | Server.Roles | T-SQL | 可変 |
| 5 | ジョブ所有権 | sp_update_job | JobServer.Jobs | T-SQL | 可変 |
| 6 | 権限 | GRANT/DENY文 | EnumServerPermissions | T-SQL | 可変 |
| 7 | DBユーザー | CREATE USER/ロール | EnumDatabaseMappings | T-SQL | 可変 |

### フッター部

コマンドはファイル出力時にFileInfoオブジェクト、Passthru時に文字列を返します。

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | FullName | ファイル完全パス | System.IO.FileInfo | 文字列 |
| 2 | Script | T-SQLスクリプト | 生成結果 | 文字列 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| SqlInstance | 対象SQL Serverインスタンス | Yes（パイプライン時はNo） |
| InputObject | パイプライン入力（Login/Database/Server） | No |
| Login | エクスポート対象ログイン名 | No |
| ExcludeLogin | 除外するログイン名 | No |
| Database | 対象データベース（権限フィルタ） | No |

### 自動除外ログイン

| ログイン | 除外理由 |
|---------|---------|
| ##で始まるログイン | システム証明書ログイン |
| sa | 組み込み管理者 |
| ローカルマシン名ログイン | マシン固有 |
| NT で始まるログイン | Windows組み込みアカウント |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | ログイン名順（サーバーLogins順） | N/A |

### 改ページ条件

スクリプトファイルのため改ページは適用されません。

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| master.dbo.syslogins | ログイン存在確認 | loginname |
| master.dbo.syslogins / sys.sql_logins | パスワードハッシュ取得 | name / principal_id |
| sys.server_principals | ログインSID取得 | principal_id |
| msdb.dbo.sysjobs | ジョブ所有権 | OwnerLoginName |

### パスワードハッシュ取得SQL（バージョン別）

| SQLバージョン | クエリ |
|-------------|-------|
| SQL 2000 (versionMajor 0/8) | `SELECT CONVERT(VARBINARY(256),password) FROM master.dbo.syslogins` |
| SQL 2005 (versionMajor 9) | `SELECT CONVERT(VARBINARY(256),password_hash) FROM sys.sql_logins` |
| SQL 2008以降 | `SELECT CAST(CONVERT(VARCHAR(256), CAST(LOGINPROPERTY(name,'PasswordHash')...` |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| SID | 16進数変換（0x + PadLeft(2, "0")） | N/A | バイト配列を16進文字列に |
| HashedPass | 16進数変換（0x + PadLeft(2, "0")） | N/A | パスワードハッシュ変換 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Export-DbaLogin実行] --> B{入力タイプ判定}
    B -->|SqlInstance| C[Connect-DbaInstance]
    B -->|InputObject| D[オブジェクト展開]
    C --> E[ログインリスト取得]
    D --> E
    E --> F{Database指定?}
    F -->|Yes| G[EnumLoginMappingsでフィルタ]
    F -->|No| H[全ログイン処理]
    G --> I[各ログイン処理]
    H --> I
    I --> J{除外対象?}
    J -->|Yes| K[スキップ]
    J -->|No| L[CREATE LOGIN生成]
    L --> M{無効/DENY?}
    M -->|Yes| N[ALTER LOGIN追加]
    M -->|No| O[サーバーロール処理]
    N --> O
    O --> P{ExcludeJobs?}
    P -->|No| Q[ジョブ所有権処理]
    P -->|Yes| R[サーバー権限処理]
    Q --> R
    R --> S{ExcludeDatabase?}
    S -->|No| T[DB権限処理]
    S -->|Yes| U[ログイン完了]
    T --> U
    U --> V[次のログインへ]
    V --> I
    K --> V
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 入力エラー | SqlInstanceもInputObjectもなし | "You must pipe in a login, database, or server or specify a SqlInstance" | パラメータを指定 |
| 入力タイプエラー | 非対応オブジェクト | "InputObject is not a server, database, or login." | 対応オブジェクトを使用 |
| 接続エラー | SQL Server接続失敗 | "Failure" | 接続情報確認 |
| ログインタイプ未対応 | 証明書/非対称キーログイン | "logins not supported. skipped" | 手動対応必要 |
| DBユーザー取得失敗 | ユーザー不在 | "User cannot be found in selected database" | 警告のみ |
| 権限エクスポート失敗 | Export-DbaUser失敗 | "Failed to extract permissions for user..." | 権限確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数十〜数百ログイン |
| 目標出力時間 | 数秒〜数分（ログイン数と権限量に依存） |
| 同時出力数上限 | 1セッション |

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

- パスワードハッシュが含まれるため、出力ファイルの保護が必須
- ExcludePasswordオプションでパスワードを#######に置換可能
- sysadminまたは適切な権限が必要（パスワードハッシュ取得）
- 出力スクリプトをバージョン管理に含める場合はセキュリティ考慮

## 備考

- SQL Server 2000以上対応
- DestinationVersionでターゲットSQL Server構文を指定可能
- SQL 2012以降はALTER SERVER ROLE、それ以前はsp_addsrvrolemember使用
- ObjectLevelオプションでオブジェクトレベル権限の詳細エクスポート可能
- NoPrefixオプションでヘッダーコメント除去

---

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

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

### 推奨読解順序

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

SMO Loginオブジェクトの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaLogin.ps1 | `public/Export-DbaLogin.ps1` | ログインプロパティの使用箇所 |

**読解のコツ**: LoginType、DefaultDatabase、IsDisabled、DenyWindowsLogin等のプロパティに注目

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaLogin.ps1 | `public/Export-DbaLogin.ps1` | パラメータ定義と処理フロー全体 |

**主要処理フロー**:
1. **行213-226**: beginブロック - 初期設定
2. **行227-582**: processブロック - ログイン処理
3. **行583-621**: endブロック - 出力処理

#### Step 3: 入力タイプ別処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaLogin.ps1 | `public/Export-DbaLogin.ps1` | InputObjectの型判定ロジック |

**主要処理フロー**:
- **行239-268**: 入力タイプ判定（DbaInstanceParameter, Server, Database, Login）
- **行270-298**: データベースマッピング取得

#### Step 4: ログインスクリプト生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Export-DbaLogin.ps1 | `public/Export-DbaLogin.ps1` | CREATE LOGIN文生成ロジック |

**主要処理フロー**:
- **行365-405**: SQL認証ログインのCREATE LOGIN生成（パスワードハッシュ取得含む）
- **行407-409**: Windows認証ログインのCREATE LOGIN生成
- **行416-422**: ALTER LOGIN（DISABLE/DENY）

#### Step 5: 権限・ロール処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Export-DbaLogin.ps1 | `public/Export-DbaLogin.ps1` | ロールと権限のエクスポート |

**主要処理フロー**:
- **行425-443**: サーバーロールメンバーシップ
- **行445-453**: ジョブ所有権
- **行455-482**: サーバーレベル権限
- **行484-571**: データベースレベル権限

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

```
Export-DbaLogin (PowerShell)
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続
    │
    ├─ EnumLoginMappings (SMO)
    │      └─ ログイン-DB マッピング取得
    │
    ├─ Login.EnumDatabaseMappings (SMO)
    │      └─ データベースマッピング取得
    │
    ├─ Server.Roles.EnumMemberNames (SMO)
    │      └─ サーバーロールメンバー取得
    │
    ├─ Server.EnumServerPermissions (SMO)
    │      └─ サーバー権限取得
    │
    ├─ Database.EnumDatabasePermissions (SMO)
    │      └─ データベース権限取得
    │
    ├─ Export-DbaUser (ObjectLevel時)
    │      └─ 詳細権限エクスポート
    │
    └─ Get-ExportFilePath
           └─ ファイルパス生成
```

### データフロー図

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

SqlInstance / InputObject  ┌──────────────────┐
         │                 │ Connect /        │
         └────────────────▶│ オブジェクト展開 │
                           └────────┬─────────┘
                                    │
                                    ▼
                           ┌──────────────────┐
                           │ ログインリスト   │
                           │ 取得・フィルタ   │
                           └────────┬─────────┘
                                    │
        ┌───────────────────────────┼───────────────────────────┐
        │                           │                           │
        ▼                           ▼                           ▼
 ┌─────────────┐            ┌─────────────┐            ┌─────────────┐
 │ CREATE      │            │ サーバー    │            │ DB権限      │
 │ LOGIN       │            │ ロール/権限 │            │ ユーザー    │
 └──────┬──────┘            └──────┬──────┘            └──────┬──────┘
        │                           │                           │
        └───────────────────────────┼───────────────────────────┘
                                    │
                                    ▼
                           ┌──────────────────┐
                           │ $outsql配列      │────▶  T-SQLスクリプト
                           │ に蓄積          │       (.sql / パイプライン)
                           └──────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaLogin.ps1 | `public/Export-DbaLogin.ps1` | ソース | メインコマンドレット |
| Export-DbaUser.ps1 | `public/Export-DbaUser.ps1` | ソース | ObjectLevel権限エクスポート |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Get-ExportFilePath.ps1 | `private/functions/Get-ExportFilePath.ps1`（推定） | ソース | ファイルパス生成 |
| New-DbaScriptingOption.ps1 | `public/New-DbaScriptingOption.ps1` | ソース | スクリプトオプション |
| dbatools.psd1 | `dbatools.psd1` | 設定 | モジュールマニフェスト |
