# Verdent Team에서 Feishu SSO 구성 (/ko/docs/account-billing/configure-feishu-sso)

> Feishu를 Verdent Team에 연결하여 통합된 기업 로그인을 제공합니다



Verdent Team은 Feishu 통합 인증(SSO)을 지원합니다. 구성이 완료되면 지정된 회사 이메일 도메인을 사용하는 멤버가 회사 Feishu 계정으로 신원을 인증할 수 있습니다.

Feishu SSO를 사용하면 기존 기업 인증 체계를 활용하고 별도 로그인 정보를 줄이며 Team Owner가 접근 권한을 한곳에서 관리할 수 있습니다.

<Note>
  이 문서는 Verdent Team Owner를 위한 안내입니다. Team 설정에서 SSO를 관리할 수 있는 사용자는 Team Owner뿐입니다.
</Note>

## Feishu SSO 작동 방식 [#feishu-sso-작동-방식]

Team Owner가 Feishu Open Platform에서 기업용 커스텀 앱을 만든 다음 앱 자격 증명과 회사 이메일 도메인을 Verdent Team에 추가합니다.

멤버가 Verdent 로그인 화면에서 해당 도메인의 이메일을 입력하면 Feishu 인증 화면으로 이동합니다. Verdent는 Feishu가 반환한 회사 이메일로 신원을 확인합니다.

<Warning>
  멤버의 Feishu 디렉터리에 회사 이메일이 등록되어 있어야 합니다.
</Warning>

## 시작하기 전에 [#시작하기-전에]

다음 항목이 필요합니다.

* 커스텀 앱을 만들 수 있는 Feishu 기업 관리자 계정
* Verdent Team Owner 권한
* `yourcompany.com`과 같은 회사 이메일 도메인

구성에는 일반적으로 약 5분이 걸립니다.

## SSO 설정 열기 [#sso-설정-열기]

1. Verdent에 로그인하고 구성할 Team으로 전환합니다.
2. Team 콘솔에서 **Settings**를 엽니다.
3. **SSO**를 선택합니다.
4. **Connect SSO**를 클릭합니다.

구성하는 동안 Verdent와 Feishu Open Platform을 모두 열어 두는 것이 좋습니다.

## Feishu 앱 구성 [#feishu-앱-구성]

<Steps>
  <Step title="기업용 커스텀 앱 만들기">
    [Feishu Open Platform](https://open.feishu.cn/app)의 **Developer Console**에서 **Create custom enterprise app**을 클릭하고 이름과 아이콘을 설정합니다.
  </Step>

  <Step title="앱 자격 증명 확인">
    **Credentials & Basic Info**에서 App ID와 App Secret을 확인합니다.

    | Feishu         | Verdent SSO     |
    | -------------- | --------------- |
    | **App ID**     | `Client ID`     |
    | **App Secret** | `Client Secret` |

    <Warning>
      App Secret은 비밀번호처럼 보호하세요. Feishu에서 재설정한 경우 Verdent의 

      `Client Secret`

      도 업데이트해야 합니다.
    </Warning>
  </Step>

  <Step title="리디렉션 URL 추가">
    **Development Configuration → Security Settings**에서 다음 **Redirect URL**을 추가합니다.

    ```text
    https://login.verdent.ai/passport/sso/callback
    ```

    <Warning>
      URL이 정확히 일치해야 합니다. 

      `https`

      를 사용하고 끝에 

      `/`

       또는 공백을 추가하지 마세요. 잘못 구성하면 Feishu 오류 

      `20029`

      가 발생합니다.
    </Warning>
  </Step>

  <Step title="권한 부여">
    **Development Configuration → Permissions**에서 다음 권한을 부여합니다.

    | 권한            | 범위                            |
    | ------------- | ----------------------------- |
    | 기본 사용자 정보 읽기  | `contact:user.base:readonly`  |
    | 사용자 이메일 정보 읽기 | `contact:user.email:readonly` |

    Verdent는 이름과 회사 이메일을 사용해 멤버를 식별합니다.
  </Step>

  <Step title="앱 게시">
    **Version Management & Release**에서 버전을 만들고 게시합니다. 앱이 게시된 후에 멤버가 사용할 수 있습니다.
  </Step>
</Steps>

## Verdent에서 연결 완료 [#verdent에서-연결-완료]

Verdent의 Feishu SSO 구성으로 돌아가 다음 값을 입력합니다.

| Verdent 필드      | 값                 |
| --------------- | ----------------- |
| `Client ID`     | Feishu App ID     |
| `Client Secret` | Feishu App Secret |
| `Email domain`  | 회사 이메일 도메인        |

회사 도메인은 최대 5개까지 추가할 수 있습니다. Gmail과 같은 공용 이메일 도메인은 지원되지 않습니다.

저장한 후 구성 카드에서 Feishu SSO가 활성화되었는지 확인합니다. 연결을 삭제하지 않고 일시적으로 비활성화할 수도 있습니다.

<Note>
  Verdent는 저장할 때 자격 증명을 검증하지만 Feishu의 리디렉션 URL은 검증하지 않습니다.
</Note>

## 멤버 로그인 과정 [#멤버-로그인-과정]

멤버는 Verdent 로그인 화면에 회사 이메일을 입력하고 SSO 사용을 확인한 뒤 Feishu에서 인증합니다. 인증 후 Verdent로 돌아옵니다. 입력한 이메일과 Feishu가 반환한 이메일이 다르면 Verdent가 확인을 요청하고 Feishu 이메일로 인증합니다.

## 구성 테스트 및 관리 [#구성-테스트-및-관리]

전체 팀에 적용하기 전에 Feishu에 회사 이메일이 등록된 일반 멤버로 테스트하세요. 로그아웃한 뒤 해당 이메일로 로그인하고 Feishu 인증 후 Verdent와 Team에 접근할 수 있는지 확인합니다.

Team Owner는 **Team → Settings → SSO**에서 상태와 도메인을 확인하고 SSO 활성화 또는 비활성화, 자격 증명 업데이트, 재구성, 삭제를 수행할 수 있습니다.

## 문제 해결 [#문제-해결]

<AccordionGroup>
  <Accordion title="Feishu 오류 20029: 잘못된 리디렉션 URL">
    **Development Configuration → Security Settings**에서 `https://login.verdent.ai/passport/sso/callback`이 정확히
    추가되었는지 확인합니다.
  </Accordion>

  <Accordion title="Client ID 또는 Client Secret이 잘못되었다고 표시됨">
    **Credentials & Basic Info**에서 App ID와 App Secret을 다시 복사합니다. Secret을 재설정했다면 최신 값을 사용하세요.
  </Accordion>

  <Accordion title="로그인할 때 앱을 사용할 수 없음">
    **Version Management & Release**에서 버전이 게시되었는지 확인합니다.
  </Accordion>

  <Accordion title="로그인 후 이메일이 비어 있음">
    Feishu 디렉터리에서 멤버에게 회사 이메일을 추가한 뒤 다시 시도합니다.
  </Accordion>

  <Accordion title="멤버가 Feishu SSO로 이동하지 않음">
    이메일이 구성된 도메인과 일치하고 Verdent에서 Feishu SSO가 활성화되어 있는지 확인합니다.
  </Accordion>
</AccordionGroup>