# Descope 사용자 일괄 관리 스크립트

이 프로젝트는 CSV 파일 또는 Google Sheets URL을 사용하여 Descope 사용자를 일괄 생성하거나 비밀번호를 변경하는 Python 스크립트입니다.

## 주요 기능

- CSV 파일 또는 Google Sheets URL을 이용한 사용자 일괄 생성
- CSV 파일 또는 Google Sheets URL을 이용한 사용자 비밀번호 일괄 변경
- 사용자 라이선스 만료일(`egBimLExpiryDate`) 일괄 지정 기능
- Gitea Actions를 통한 워크플로우 자동화

## 요구 사항

- Python 3.13 이상
- [uv](https://github.com/astral-sh/uv) (가상 환경 및 패키지 관리 도구)
- Descope Project ID 및 Management Key

## 로컬 환경에서 실행

### 1. 설치 및 설정

1.  **저장소 복제**
    ```bash
    git clone https://gitea.hmac.kr/lectom/descope-bulk-user-script.git
    cd descope-bulk-user-script
    ```

2.  **가상 환경 생성 및 의존성 설치**
    ```bash
    uv venv
    source .venv/bin/activate
    uv sync
    ```

3.  **환경 변수 설정**
    프로젝트 루트에 `.env` 파일을 생성하고 Descope 키를 추가합니다. (`.env.example` 참고)
    ```
    DESCOPE_PROJECT_ID="YOUR_PROJECT_ID"
    DESCOPE_MANAGEMENT_KEY="YOUR_MANAGEMENT_KEY"
    ```

### 2. 사용법

스크립트는 `main.py`를 통해 실행하며, 처리할 데이터 소스(CSV 파일 또는 Google Sheets URL)와 함께 수행할 작업을 지정합니다.

- `source`: 처리할 CSV 파일 경로 또는 Google Sheets URL
- `--action`: 수행할 작업 (`create`, `change_password`, `test`)
- `--expiry-date`: (선택 사항) 라이선스 만료일을 `YYYY-MM-DD` 형식으로 지정. 지정 시 모든 사용자의 `egBimLExpiryDate` 값을 덮어씁니다.

#### Google Sheets URL 준비
Google Sheets를 데이터 소스로 사용하려면, 해당 시트에서 **파일 > 공유 > 웹에 게시**를 선택하세요. **링크** 탭에서 **"쉼표로 구분된 값(.csv)"** 형식을 선택하고 게시하여 생성된 URL을 사용해야 합니다.

#### 실행 예시

- **로컬 CSV 파일로 사용자 생성**
  ```bash
  python main.py jobs/sample.csv --action create
  ```

- **Google Sheets URL로 사용자 생성 및 만료일 지정**
  ```bash
  python main.py "https://docs.google.com/spreadsheets/d/e/.../pub?output=csv" --action create --expiry-date 2025-12-31
  ```

- **비밀번호 변경**
  ```bash
  python main.py users_passwords.csv --action change_password
  ```

- **단일 사용자 생성 테스트**
  CSV 파일 없이 API 연동을 빠르게 테스트합니다.
  ```bash
  python main.py --action test
  ```

## Gitea Actions를 이용한 실행

이 저장소의 Gitea Actions 워크플로우를 사용하면 로컬 환경 설정 없이 웹 UI에서 스크립트를 실행할 수 있습니다.

### 1. 사전 준비: Gitea Secrets 설정

워크플로우가 Descope API에 접근하려면 Gitea 저장소에 API 키를 Secret으로 등록해야 합니다. 이 작업은 저장소 관리자가 한 번만 수행하면 됩니다.

1.  Gitea 저장소에서 **Settings** > **Secrets** 탭으로 이동합니다.
2.  **Create Secret** 버튼을 클릭하여 다음 두 개의 Secret을 추가합니다.
    - **`DESCOPE_PROJECT_ID`**: Descope 프로젝트 ID를 값으로 입력합니다.
    - **`DESCOPE_MANAGEMENT_KEY`**: Descope 관리 키를 값으로 입력합니다.

### 2. 워크플로우 실행 방법

1.  저장소의 **Actions** 탭으로 이동합니다.
2.  왼쪽 사이드바에서 **Descope 사용자 일괄 처리** 워크플로우를 선택합니다.
3.  **Run Workflow** 버튼을 클릭합니다.
4.  나타나는 입력 필드에 값을 채웁니다.
    - **`google_sheet_url`**: 처리할 Google Sheets의 CSV 내보내기 URL. (자세한 내용은 "Google Sheets URL 준비" 섹션 참고)
    - **`action_type`**: 실행할 작업 (`create` 또는 `change_password`)
    - **`expiry_date`**: (선택 사항) `YYYY-MM-DD` 형식의 라이선스 만료일. 입력 시 모든 사용자의 만료일을 이 값으로 덮어씁니다.
5.  입력 확인 후, **Run Workflow** 버튼을 다시 클릭하여 실행을 시작합니다.

### 3. 실행 결과 확인

워크플로우가 실행되면 Actions 목록에 새로운 실행 항목이 나타납니다.

1.  해당 실행 항목을 클릭하여 상세 페이지로 들어갑니다.
2.  `run_bulk_operation` 작업을 클릭하면 스크립트의 실행 로그를 실시간으로 확인할 수 있습니다.
3.  사용자 생성 또는 비밀번호 변경 과정에서 발생하는 모든 성공 및 오류 메시지가 이 로그에 표시됩니다. 작업이 예상대로 완료되었는지 반드시 로그를 통해 확인하세요.

## CSV 데이터 형식

### 사용자 생성 (`create`)

| 헤더               | 설명                                                               | 필수 |
| ------------------ | ------------------------------------------------------------------ | ---- |
| `login_id`         | 사용자의 로그인 ID                                                 | 예   |
| `email`            | 사용자 이메일 주소                                                 | 예 |
| `display_name`     | 사용자 표시 이름                                                   | 예 |
| `tenants`          | 사용자를 할당할 테넌트 ID의 배열 (JSON 형식 문자열)                | 아니요 |
| `role_name`        | `tenants`에 명시된 모든 테넌트에서 할당할 역할 이름                | 아니요 |
| `company`          | 사용자 정의 속성 'company'                                         | 아니요 |
| `egBimLExpiryDate` | 사용자 정의 속성, **UTC 타임스탬프(초)** 값. `--expiry-date`로 덮어쓸 수 있음. | 아니요 |

**참고:**
- `tenants` 필드는 `["tenant-id-1", "tenant-id-2"]` 와 같이 JSON 배열 형식의 문자열로 입력해야 합니다.

### 비밀번호 변경 (`change_password`)

| 헤더             | 설명               | 필수 |
| ---------------- | ------------------ | ---- |
| `login_id`       | 사용자의 로그인 ID | 예   |
| `new_password`   | 새 비밀번호        | 예   |