adusermanager/README.md

## AD/M365 통합 관리 도구

---

### 1. 개요

하이브리드 Active Directory (On-Premise AD + Azure AD) 환경에서 사용자 계정의 생성, 삭제, 동기화 관리를 자동화하고 간소화하기 위한 PowerShell 기반의 GUI 도구이다. IT 관리자는 이 도구를 통해 반복적인 작업을 줄이고 휴먼 에러를 최소화할 수 있다.

모든 작업은 UI가 멈추지 않는 동기 방식으로 처리되며, 스크립트 실행에 필요한 모듈이나 기능은 최초 실행 시 자동으로 설치를 안내하여 사용자 편의성을 높였다.

### 2. 주요 기능

-   **계정 생성**:
    -   On-Premise AD 사용자 생성.
    -   AAD Connect 동기화 (Delta) 자동 실행.
    -   Azure AD 사용자 확인 후 M365 라이선스 및 서비스 플랜 할당.
    -   On-Premise AD에만 사용자를 생성하는 옵션 제공.
-   **계정 삭제**:
    -   On-Premise AD에서 사용자 검색 및 다중 선택.
    -   삭제 대기열에 사용자를 추가하여 일괄 삭제.
    -   AAD Connect 동기화 (Delta) 자동 실행.
-   **하드 매칭 (Hard Match)**:
    -   Azure AD에만 존재하는 사용자(Cloud-Only)를 On-Premise AD 사용자와 연결.
    -   **시나리오 1**: 기존 On-Premise AD 계정과 매칭 (ImmutableId 설정).
    -   **시나리오 2**: 신규 On-Premise AD 계정을 생성하여 즉시 매칭.
    -   매칭 후 즉시 동기화를 실행하여 상태를 바로잡음.
-   **일괄 작업 (CSV)**:
    -   CSV 파일을 이용한 대량 계정 생성 및 삭제.
    -   작업별 CSV 템플릿 다운로드 기능 제공.
    -   실행 전 데이터 유효성 검사 (OU 존재 여부, 계정명 중복 등)를 통해 작업 실패율 최소화.
-   **편의 기능**:
    -   직관적인 GUI 및 작업 상태 실시간 로깅.
    -   스크립트 실행에 필요한 모듈(ActiveDirectory, Microsoft.Graph) 자동 검사 및 설치 안내.
    -   주요 설정(`config.json`)을 GUI 대화상자를 통해 쉽게 변경 및 저장.

### 3. 요구 사항 및 환경

-   **운영 체제**: Windows 10, Windows 11, Windows Server 2016 이상
-   **PowerShell**: 버전 5.1 이상
-   **권한**: 스크립트를 실행하는 사용자는 **로컬 관리자** 권한 및 **Domain Admins** 권한이 필요.
-   **필수 모듈/기능**:
    -   RSAT: Active Directory Domain Services 및 LDS(Lightweight Directory Services) 도구
    -   PowerShell Module: `Microsoft.Graph`
    > *위 항목들은 스크립트 최초 실행 시 자동으로 설치 여부를 확인하고 설치를 안내함.*
-   **네트워크**: On-Premise Domain Controller 및 Azure AD (graph.microsoft.com)와 통신이 가능해야 함.

### 4. 설치 및 설정

1.  **파일 다운로드**
    -   리포지토리의 모든 파일을 다운로드하여 원하는 위치에 압축을 해제한다.

2.  **설정 파일 (`config.json`) 수정**
    -   프로그램을 처음 실행하면 설정 대화상자가 나타나지만, 미리 `config.json` 파일을 자신의 환경에 맞게 수정할 수도 있다.

    | 키                      | 설명                                                                                               | 예시                                    |
    | ----------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------- |
    | `OnPremDomainController`  | On-Premise Active Directory 도메인 컨트롤러의 FQDN.                                                | `dc01.mydomain.local`                   |
    | `AADConnectServerName`    | Azure AD Connect가 설치된 서버의 이름. 비워두면 로컬에서 동기화 명령을 실행.                        | `aadc01`                                |
    | `AzureTenantId`           | Azure AD 테넌트의 ID.                                                                              | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`  |
    | `UPNSuffix`               | 사용자 계정의 UPN(User Principal Name)으로 사용할 접미사.                                          | `mydomain.com`                          |
    | `SynchronizedOUs`         | AAD Connect로 동기화되는 OU의 **이름** 목록. 세미콜론(;)으로 구분.                                  | `Sales;Marketing;Developers`            |
    | `DefaultPassword`         | 계정 생성 시 사용할 기본 초기 비밀번호.                                                            | `Password123!`                          |
    | `DefaultUsageLocation`    | M365 라이선스 할당 시 필요한 사용 위치 (ISO 3166-1 alpha-2 국가 코드).                               | `KR`                                    |

3.  **스크립트 실행**
    -   `Main.ps1` 파일을 마우스 오른쪽 버튼으로 클릭하여 **'PowerShell에서 실행'**을 선택한다.
    -   **반드시 관리자 권한으로 실행해야 한다.**
    -   최초 실행 시 필수 모듈 설치 여부를 확인하며, 설치가 필요할 경우 관리자 권한으로 설치를 진행한다.
    -   설정 대화상자가 나타나면 내용을 확인하고 '시작' 버튼을 클릭한다.

### 5. 사용 방법

#### 5.1. 계정 생성 탭

1.  **작업 모드 선택**: 'AD/Azure AD 동기화' 또는 '온프레미스 AD에만 생성' 중 하나를 선택한다.
2.  **사용자 정보 입력**: 한글 성/이름, 영문 계정명, 초기 비밀번호를 입력한다.
    -   영문 계정명은 입력이 끝나면 On-Premise 및 Azure AD에 중복되는 계정이 있는지 자동으로 검사한다.
3.  **대상 OU 선택**: 사용자를 생성할 On-Premise AD의 조직 단위(OU)를 트리에서 선택한다.
    -   선택한 OU가 AD Connect 동기화 대상인지 여부가 하단에 표시된다.
4.  **M365 라이선스 할당** (동기화 모드 시):
    -   할당할 라이선스를 목록에서 선택한다.
    -   선택한 라이선스에 포함된 서비스 플랜 중 비활성화할 항목은 체크를 해제한다.
5.  **계정 생성 실행**: 버튼을 클릭하여 작업을 시작한다. 작업 과정은 하단 로그 창에 출력된다.

#### 5.2. 계정 삭제 탭

1.  **사용자 검색**: 삭제할 사용자의 이름 또는 계정명 일부를 입력하고 '온프레미스 검색' 버튼을 클릭한다.
2.  **삭제 목록에 추가**: 검색 결과에서 삭제할 사용자를 선택(다중 선택 가능)하고 '삭제 목록에 추가' 버튼을 클릭하거나, 항목을 더블클릭한다.
3.  **삭제 실행**: 삭제 대기 목록을 확인한 후, '목록 삭제 실행' 버튼을 클릭한다. 최종 확인 대화상자에서 '예'를 누르면 작업이 시작된다.

#### 5.3. 하드 매칭 탭

1.  **Azure AD 사용자 검색**: 매칭할 Azure AD 사용자의 이름 또는 UPN을 입력하고 'Azure AD 검색' 버튼을 클릭한다.
2.  **사용자 선택**: 검색 결과 목록에서 대상 사용자를 선택한다.
3.  **상태 확인 및 작업 선택**:
    -   **On-Premise 계정이 없는 경우**: '계정 생성 및 하드 매칭' 모드로 전환된다. 신규 생성에 필요한 정보를 입력하고 대상 OU를 선택한다.
    -   **On-Premise 계정이 있는 경우**: '기존 계정과 하드 매칭' 모드로 전환된다. Azure AD의 `ImmutableId`와 On-Premise AD의 `ObjectGUID`를 비교하여 현재 동기화 상태를 진단하고 필요한 작업을 안내한다.
4.  **작업 실행**: 버튼을 클릭하여 매칭 작업을 시작한다.

#### 5.4. 일괄 작업 (CSV) 탭

1.  **작업 유형 선택**: '계정 생성' 또는 '계정 삭제'를 선택한다.
2.  **템플릿 다운로드**: '템플릿 다운로드' 버튼을 클릭하여 작업에 맞는 CSV 파일을 받는다.
3.  **CSV 파일 작성**: 다운로드한 템플릿에 맞춰 작업할 데이터를 입력한다.
4.  **파일 불러오기**: '파일 찾아보기' 버튼으로 작성한 CSV 파일을 선택하면 데이터가 그리드에 표시된다.
5.  **유효성 검사**: '유효성 검사' 버튼을 클릭하여 데이터의 정합성(필수 값, OU 경로, 계정 중복 등)을 미리 확인한다.
6.  **일괄 작업 실행**: 유효성 검사를 통과하면 '일괄 작업 실행' 버튼이 활성화된다. 버튼을 클릭하여 작업을 시작한다.

### 6. 주요 아키텍처 및 로직

-   **GUI**: PowerShell에서 `System.Windows.Forms` .NET 어셈블리를 직접 호출하여 모든 UI 요소를 동적으로 생성한다.
-   **비동기 처리**: `Invoke-Synchronous` 라는 공용 함수를 통해 시간이 오래 걸리는 작업(AD/Graph API 호출, 동기화 등)을 실행한다. 이 함수는 작업 중 UI 컨트롤을 비활성화하고 커서를 대기 상태로 변경하여 사용자에게 작업 상태를 명확히 알려주고, UI가 멈추는 현상을 방지한다.
-   **모듈화**: 기능별로 스크립트 파일을 분리하여 코드의 가독성과 유지보수성을 높였다.
    -   `Main.ps1`: 프로그램 진입점, 전역 변수 및 메인 폼 초기화.
    -   `Common.ps1`: 모든 기능에서 공통으로 사용하는 함수 라이브러리 (로그, API 호출 래퍼, 설정 관리 등).
    -   `UI-Tab-*.ps1`: 각 탭의 UI 생성 및 이벤트 핸들러 로직을 담당.

### 7. 파일 구조

```
.
├── Main.ps1                        # 메인 스크립트 (시작 파일)
├── config.json                     # 환경 설정 파일
├── logs/                           # 로그 파일 저장 디렉터리
└── Scripts/
    ├── Common.ps1                  # 공용 함수 라이브러리
    ├── UI-Tab-AddUser.ps1          # '계정 생성' 탭 UI 및 로직
    ├── UI-Tab-DeleteUser.ps1       # '계정 삭제' 탭 UI 및 로직
    ├── UI-Tab-HardMatch.ps1        # '하드 매칭' 탭 UI 및 로직
    └── UI-Tab-BatchTask.ps1        # '일괄 작업' 탭 UI 및 로직
```