> For the complete documentation index, see [llms.txt](https://docs.smply.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smply.one/start/integrate_gws/googleworkspace.md).

# GoogleWorkspace 연동 상세 설정

## Google Workspace 연동 상세 설정

Google Workspace(이하 GWS)와 연동하면 조직의 사용자·조직 단위·그룹 정보를 심플리로 자동 동기화할 수 있습니다. **여러 도메인을 한 번에 관리**할 수 있고, 구성원 상세 페이지에서 **Google 계정 자체를 직접 생성·정지·삭제**할 수 있습니다.

{% hint style="info" %}
**매일 오후 9시 자동 동기화** 연동 후에는 매일 한국 시간 오후 9시에 사용자·조직·그룹 정보가 자동 동기화됩니다. 필요한 경우 설정 화면에서 수동 동기화도 가능합니다.
{% endhint %}

***

### 1. 연동 시작

**전제 조건**

* Google Workspace **관리자** 권한을 가진 계정
* 심플리의 **관리자(Admin)** 역할

**단계 1: 연동 관리 열기**

1. 사이드바 **설정** > **연동 관리**로 이동합니다.
2. **Google Workspace** 카드에서 **`연동하기`** 버튼을 클릭합니다.

**단계 2: Google 관리자 계정으로 로그인**

1. 구글 로그인 화면으로 이동합니다.
2. **관리자** 권한을 가진 계정으로 로그인하고 요청된 권한을 승인합니다.

**단계 3: 연동 완료 확인**

1. 연동 관리 페이지에 상태 뱃지 **`연동됨`** 이 표시됩니다.
2. **Google Workspace** 카드를 다시 클릭하면 상세 설정 화면으로 이동합니다.

***

### 2. 여러 도메인 관리 (신규)

Google Workspace에 연결된 **모든 도메인**을 한 화면에서 관리할 수 있습니다.

#### 도메인 선택

설정 화면의 **`동기화 범위`** 카드에 연결된 도메인이 체크박스로 나열됩니다.

* **`기본`** 뱃지: Google Workspace에 기본 도메인(Primary)으로 설정된 도메인. 툴팁: *"구글 워크스페이스에 설정된 기본 도메인입니다."*
* **삭제된 도메인**: Google Workspace 측에서 제거된 도메인은 취소선 + **`삭제됨`** 뱃지로 표시되며 선택할 수 없습니다.

체크박스로 원하는 도메인만 선택하면, 해당 도메인에 속한 사용자·조직 단위·그룹만 심플리로 동기화됩니다.

{% hint style="info" %}
**도메인별 독립 설정** 도메인이 여러 개 선택되면 탭(Tabs) UI가 나타나 **각 도메인의 동기화 범위를 독립적으로 설정**할 수 있습니다. 탭 뱃지로 현재 설정 요약이 표시됩니다 (`전체` / `조직 단위 N + 그룹 N` / `미선택`).
{% endhint %}

***

### 3. 동기화 범위 설정

각 도메인의 탭에서 다음 세 가지 중 하나를 선택합니다.

| 옵션          | 설명                                           |
| ----------- | -------------------------------------------- |
| **전체 동기화**  | 해당 도메인의 모든 사용자·조직·그룹을 동기화합니다.                |
| **선택적 동기화** | **조직 단위(OU)** 또는 **그룹** 체크박스로 범위를 좁혀 동기화합니다. |

**선택적 동기화를 고르면 나타나는 항목:**

* **조직 단위(Org Units)**: 스크롤 가능한 체크박스 목록. 체크된 OU의 사용자만 동기화됩니다.
* **그룹(Groups)**: 스크롤 가능한 체크박스 목록. 체크된 그룹의 사용자만 동기화됩니다.

{% hint style="warning" %}
**조직 단위와 그룹이 없으면** Google Workspace에 조직 단위·그룹이 하나도 없으면 **선택적 동기화** 옵션은 UI에 나타나지 않습니다.
{% endhint %}

설정을 마친 뒤 **`저장 및 동기화하기`** 버튼을 누르면 즉시 동기화가 트리거됩니다. 성공 시 토스트: *"설정이 저장되었습니다."*

***

### 4. 소프트웨어 자동 동기화 토글

설정 화면 하단 **`소프트웨어 자동으로 동기화하기`** 스위치를 켜면, Google 로그인 기록 기반으로 **소프트웨어와 각 소프트웨어의 사용자**가 자동으로 추가됩니다.

> *"로그인 정보를 기반으로 소프트웨어와 각 소프트웨어의 사용자를 추가합니다"*

끄면 사용자·조직만 동기화되고 소프트웨어 데이터는 수집되지 않습니다.

***

### 5. 수동 동기화

자동 동기화 외에 언제든지 직접 동기화를 실행할 수 있습니다.

1. 설정 > 연동 관리 > Google Workspace 설정으로 이동
2. **`저장 및 동기화하기`** 버튼을 클릭

{% hint style="warning" %}
**10분 쿨다운** 동기화 실행 후 10분 이내에 재시도하면 안내 메시지 *"이전 동기화로부터 10분 이내에는 동기화할 수 없습니다. 잠시 후 다시 시도해주세요."* 가 표시됩니다.
{% endhint %}

***

### 6. 구성원 상세에서 Google 계정 직접 관리 (신규)

**구성원 상세 페이지** 헤더의 **`수정하기`** 버튼 우측 드롭다운에서, **구글 워크스페이스 계정** 묶음 아래의 메뉴로 해당 구성원의 Google Workspace 계정을 직접 관리할 수 있습니다.

{% hint style="info" %}
**권한 요구** 구성원 수정 권한(`canEditMember`)이 있고 워크스페이스 플랜이 만료되지 않아야 수정 버튼이 노출됩니다.
{% endhint %}

#### 현재 GWS 계정 상태별 가능한 액션

| 상태                | 가능한 액션               |
| ----------------- | -------------------- |
| **활성(active)**    | **`정지`** / **`삭제`**  |
| **정지(suspended)** | **`활성화`** / **`삭제`** |
| **삭제(deleted)**   | **`재생성`**            |

#### 계정 재생성 플로우

삭제된 Google 계정을 다시 만들려면:

1. 드롭다운의 **구글 워크스페이스 계정** 묶음에서 **`재생성`** 을 선택합니다.
2. 다이얼로그 *"Google Workspace 계정 재생성"* 이 열립니다.
3. 다음 필드를 입력합니다.
   * **성(Family Name)** — 필수
   * **이름(Given Name)** — 필수
   * **보조 이메일** — 필수, 이메일 형식
4. **`재생성`** 을 클릭합니다.
5. 성공 토스트: *"Google Workspace 계정이 재생성되었습니다."*

#### 구성원 비활성화 시 Google 계정 동시 삭제

구성원을 비활성화할 때 **`구성원 비활성화`** 다이얼로그에서 **`Google Workspace 계정도 함께 삭제`** 체크박스를 켜면 심플리에서 비활성화하는 동시에 Google Workspace 계정도 삭제합니다.

***

### 7. Google Workspace 계정으로 구성원 추가 (청구 기준 안내)

구성원 목록에서 Google 계정과 심플리 구성원을 동시에 생성하는 플로우입니다.

1. **구성원** 메뉴에서 **Google Workspace 계정으로 구성원 추가** 다이얼로그를 엽니다.
2. 필수 정보(이름, 이메일 등)를 입력하고 **다음**을 눌러 확인 단계로 이동합니다.
3. 확인 단계 상단에 **청구 기준 안내 배너**(노란색)가 표시됩니다.

{% hint style="warning" %}
**한국시간 오후 5시를 기준으로 청구일이 달라집니다**

* **오후 5시 이전**: 당일 날짜로 청구됩니다. 배너: *"한국시간 오후 5시 이전에 추가하면 {오늘}로 청구됩니다."*
* **오후 5시 이후**: 다음 날 날짜로 청구됩니다. 배너: *"한국시간 오후 5시 이후에 추가하면 {내일}로 청구됩니다."*

이 배너는 실시간으로 계산되어 표시되므로, 언제 추가해야 최적인지 참고할 수 있습니다.
{% endhint %}

**기존 Google 계정이 있는 경우:**

이미 Google Workspace에 동일한 이메일이 존재하면 다음 문구가 표시됩니다.

> *"이미 Google Workspace에 동일한 이메일의 계정이 존재합니다. 기존 계정을 동기화하시겠습니까?"*

그대로 진행하면 새로 생성하지 않고 기존 계정과 연결만 수행합니다.

***

### 8. 연동 상태 뱃지

연동 관리 > Google Workspace 카드에는 현재 상태가 뱃지로 표시됩니다.

| 뱃지            | 의미                            | 조치                                  |
| ------------- | ----------------------------- | ----------------------------------- |
| **연동됨**       | 정상 동작 중                       | —                                   |
| **연동 대기**     | 연동 진행 중 또는 첫 동기화 대기           | 잠시 후 새로고침                           |
| **인증 만료**     | OAuth 토큰이 만료되었거나 권한이 변경됨      | 재연동 필요                              |
| **관리자 승인 필요** | 심플리 앱이 Google 관리 콘솔에서 승인되지 않음 | Google 관리 콘솔에서 심플리 앱 액세스 승인 (아래 참고) |

{% hint style="warning" %}
**`관리자 승인 필요` 뱃지가 뜬 경우** Google 관리 콘솔에서 **보안 > API 제어 > 타사 앱 액세스 관리**로 이동해 심플리 앱의 액세스를 승인해 주세요. 또는 관리자 권한이 있는 계정으로 모든 권한에 동의하여 재연동해도 됩니다. 이 상태일 때는 동기화 화면의 기술 메시지가 뱃지로 대체되어 숨겨집니다.
{% endhint %}

***

### 9. 연동 해제

연동을 중단하고 싶을 때:

1. Google Workspace 설정 화면 하단의 **`연동 해제하기`** 버튼을 클릭합니다.
2. 확인 다이얼로그:
   * 제목: *"구글 워크스페이스 연동 해제"*
   * 설명: *"정말 구글 워크스페이스 연동을 해제하시겠습니까? 연동 해제 후에는 구성원 및 구독 데이터 동기화가 중단됩니다."*
3. 확인하면 토스트 *"Google Workspace 연동이 해제되었습니다."* 와 함께 동기화가 중단됩니다.

{% hint style="info" %}
**기존 데이터는 보존됩니다** 연동 해제 후에도 이미 동기화된 구성원·기기·소프트웨어 데이터는 그대로 유지됩니다. 언제든 다시 연동하여 동기화를 재개할 수 있습니다.
{% endhint %}

***

### 10. 문제 해결

#### Q: 연동했는데 도메인 목록에 특정 도메인이 안 보여요

**원인**: 연동한 Google 계정의 관리자 권한이 부족하거나, 해당 도메인이 Google Workspace에서 검증(Verified)되지 않았을 수 있습니다.

**해결 방법**:

1. Google 관리 콘솔에서 해당 도메인의 검증 상태를 확인합니다.
2. 관리자 권한을 가진 계정으로 **연동 해제** 후 **재연동**을 진행합니다.
3. 설정 화면 하단 안내 *"보이지 않는 도메인, 조직 단위가 있나요?"* 를 참고하세요.

#### Q: 설정 화면 위에 *"디렉터리 읽기 권한이 없습니다"* 배너가 떠요

연동한 계정에 디렉터리 정보를 읽을 권한(403)이 부족하면 동기화 범위 폼 위에 경고 배너가 표시됩니다. 두 가지 경우로 나뉩니다.

* **도메인조차 읽지 못하는 경우**: *"연동된 계정에 디렉터리 정보를 읽을 권한이 없습니다."* — 동기화 자체가 진행되지 않습니다.
* **도메인은 읽히고 그룹·조직 단위만 막힌 경우**: *"연동된 계정에 그룹·조직 단위를 읽을 권한이 없습니다."* — **도메인 단위 전체 동기화는 가능**하지만, 그룹·조직 단위로 범위를 좁히려면 권한이 필요합니다.

**해결 방법** (두 경우 공통):

1. **관리자 권한이 있는 계정**으로 **모든 권한에 동의**하여 재연동합니다.
2. 또는 Google 관리 콘솔 **보안 > API 제어 > 타사 앱 액세스 관리**에서 심플리 앱 액세스를 승인합니다.

#### Q: "인증 만료" 뱃지가 표시됩니다

**원인**: 연동한 관리자 계정의 권한이 변경되었거나 OAuth 토큰이 만료되었습니다.

**해결 방법**:

1. 연동 관리에서 **`재연동`** 을 클릭합니다.
2. 관리자 계정으로 다시 로그인해 권한을 승인합니다.

#### Q: 특정 사용자가 동기화되지 않아요

**확인 사항**:

1. Google Workspace에서 사용자 상태가 **활성**인지 확인합니다.
2. 선택한 조직 단위·그룹에 해당 사용자가 포함되어 있는지 확인합니다.
3. 수동 동기화(`저장 및 동기화하기`)를 한 번 더 실행합니다.

#### Q: Google 계정 재생성이 실패해요

**원인 후보**:

* 해당 이메일이 아직 Google Workspace에서 유예(trash) 상태일 수 있습니다.
* 보조 이메일 형식이 맞지 않을 수 있습니다.

**해결 방법**:

1. Google 관리 콘솔에서 해당 사용자가 **완전 삭제** 상태인지 확인합니다.
2. 보조 이메일을 정확히 입력했는지 확인합니다.
3. 다이얼로그 내 에러 메시지를 참고해 원인을 확인한 뒤 재시도합니다.

#### Q: 소프트웨어 자동 동기화 토글을 켰는데 소프트웨어가 안 추가돼요

**확인 사항**:

1. 동기화 대상 도메인·조직·그룹에 해당 사용자가 포함되어 있는지
2. Google 로그인 기록이 최근에 있는지 (기록이 있어야 소프트웨어가 발견됩니다)
3. 매일 오후 9시 자동 동기화 이후 데이터가 반영됩니다. 즉시 확인이 필요하면 **`저장 및 동기화하기`** 를 수동 실행하세요.

#### Q: 이 외의 문제

채널톡으로 문의해 주세요.