convert to gitea
This commit is contained in:
131
README.md
Normal file
131
README.md
Normal file
@ -0,0 +1,131 @@
|
||||
## 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 및 로직
|
||||
```
|
||||
Reference in New Issue
Block a user