> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Feishu/Lark, DingTalk, OIDC를 통한 Single Sign-On

> Feishu 또는 Lark, DingTalk, 또는 Okta, Entra ID, Auth0, Keycloak 같은 OpenID Connect 자격 증명 공급자로 구성원이 Alforse에 로그인하게 합니다.

[SAML 2.0](https://docs.alforse.com/ko/docs/reference/single-sign-on.md) 외에도 Alforse는 로그인을 회사의 Feishu / Lark 또는 DingTalk 조직, 혹은 모든 OpenID Connect(OIDC) 자격 증명 공급자에 위임할 수 있습니다. 회사 관리자가 **Single Sign-On** 페이지에서 한 번 설정하면, 이후 검증된 도메인의 업무용 이메일을 입력한 사용자는 해당 공급자로 이동하여 로그인합니다.

## 개념

* **회사당 하나의 연결.** 회사에는 하나의 프로토콜을 사용하는 Single Sign-On 연결이 하나만 있습니다. 프로토콜은 **OpenID Connect**, **Feishu / Lark**, **DingTalk**, SAML 중 하나입니다. 이 페이지에서 앞의 셋 중 하나를 저장하면 SAML 연결이 대체됩니다([SAML에서 전환](#switching-from-saml) 참조).
* **검증된 도메인이 로그인을 라우팅합니다.** DNS 레코드로 소유를 증명한 이메일 도메인만 사용자를 공급자로 보냅니다.
* **초대 우선.** Single Sign-On은 스스로 계정을 만들지 않습니다. 기존 구성원이거나 회사가 보낸 대기 중인 초대를 수락한 경우에만 들어올 수 있습니다.
* **연결된 계정.** 처음 로그인에 성공하면 공급자 계정이 Alforse의 사람과 연결됩니다. 이후 로그인은 이 연결을 바로 사용합니다.

## 시작하기 전에

* **권한.** 회사 설정을 변경할 권한(`settings` 업데이트)이 필요합니다. 권한이 없으면 페이지에 **"Administrators only"**(관리자 전용)가 표시됩니다.
* **사용 가능 여부.** 구독에 Single Sign-On이 포함되어 있지 않으면 페이지에 **"Single sign-on isn't in your plan"**(Single sign-on은 현재 플랜에 포함되어 있지 않습니다)이 표시됩니다.
* **공급자 액세스.** 자격 증명 공급자에서 애플리케이션을 생성할 권한이 필요합니다. Feishu / Lark 오픈 플랫폼의 커스텀 앱, DingTalk 개발자 콘솔의 내부 앱, 또는 IdP의 OIDC 웹 애플리케이션입니다.
* **DNS 액세스.** 각 이메일 도메인에 TXT 레코드를 게시하게 됩니다.

## Single Sign-On 페이지 열기

1. [https://app.alforse.com](https://app.alforse.com) 에서 ERP에 로그인합니다.
2. 같은 브라우저에서 **[https://api.alforse.com/identity](https://api.alforse.com/identity)**를 엽니다.

페이지에 **"Sign in to continue"**(계속하려면 로그인하세요)가 표시되면 **로그인**을 선택하여 ERP에 로그인한 다음 주소를 다시 엽니다. 상단의 **EN** / **中文** 버튼은 페이지를 영어와 중국어 간체 사이에서 전환합니다. 제목 옆의 상태는 연결이 있으면 **Active**(활성), 없으면 **Not configured**(구성되지 않음)로 표시됩니다.

페이지에는 **자격 증명 공급자**(Identity Provider), **Single Sign-On 필수**(Require single sign-on), **이메일 도메인**(Email Domains), **로그인 링크**(Sign-in Links), **연결된 계정**(Linked Accounts)의 다섯 카드가 있습니다. 연결을 저장하기 전에는 **자격 증명 공급자**만 표시됩니다.

Alforse screenshot**api.alforse.com/identity의 Single Sign-On 페이지: 공급자 선택, 리디렉션 URI 복사 필드, 연결 버튼이 있는 자격 증명 공급자 카드**

모든 공급자는 자격 증명 공급자 카드에서 설정합니다.

## 자격 증명 공급자 카드

| 필드 | 표시 대상 | 입력할 내용 |
| - | - | - |
| **공급자**(Provider) | 전체 | **OpenID Connect (Okta, Entra ID, Auth0, Keycloak…)**, **Feishu / Lark** 또는 **DingTalk**. |
| **리디렉션 URI**(Redirect URI) | 전체 | 읽기 전용이며 복사 버튼이 있습니다. 이 값을 그대로 공급자에 등록합니다. |
| **설정 가이드 보기**(View setup guide) | 전체 | 공급자별 단계를 측면 패널에서 엽니다. |
| **발급자 URL**(Issuer URL) | OpenID Connect | IdP의 발급자이며 `https://`로 시작합니다. |
| **리전**(Region) | Feishu / Lark | **Feishu (feishu.cn)** 또는 **Lark (larksuite.com)**. |
| **Client ID** / **App ID** / **Client ID (AppKey)** | 전체 | 공급자가 발급한 애플리케이션 ID입니다. |
| **Client secret** / **App Secret** / **Client Secret (AppSecret)** | 전체 | 애플리케이션의 시크릿입니다. 저장한 뒤에는 다시 표시되지 않으며, 필드에 "Saved. Leave empty to keep it."(저장되었습니다. 유지하려면 비워 두세요.)라고 표시됩니다. |
| **Tenant key**(선택) | Feishu / Lark | Feishu 테넌트 키입니다. 비워 두면 Alforse가 App Secret으로 Feishu에서 읽어 옵니다. |
| **CorpId** | DingTalk | DingTalk 조직의 CorpId입니다. 필수입니다. |

**연결**(Connect)을 선택합니다(기존 연결이면 **변경 사항 저장**). Alforse는 저장하기 전에 공급자와 설정을 확인하고 "Single sign-on saved"(Single sign-on이 저장되었습니다)로 알려 줍니다.

### 리디렉션 URI

모든 공급자 애플리케이션은 이 하나의 리디렉션(콜백) URI를 사용해야 합니다.

```text theme={null}
https://api.alforse.com/api/web/auth/v1/sso/oauth/callback
```

모든 회사와 모든 공급자에게 동일합니다. 직접 입력하지 말고 페이지에서 복사하십시오.

## 공급자 설정

**Feishu / Lark**

**Feishu 오픈 플랫폼**([https://open.feishu.cn](https://open.feishu.cn), Lark는 [https://open.larksuite.com)에서](https://open.larksuite.com\)에서):

1. **커스텀 앱**(企业自建应用)을 생성합니다.
2. **Credentials & Basic Info**(자격 증명 및 기본 정보)에서 **App ID**와 **App Secret**을 복사합니다.
3. **Security Settings → Redirect URLs**(보안 설정 → 리디렉션 URL)에 위에 표시된 리디렉션 URI를 추가합니다.
4. **Permissions**(권한)에서 다음을 허용합니다.
   * 사용자 기본 정보 읽기(필수)
   * 이메일로 사람을 대응시킬 수 있도록 사용자의 기업 이메일 읽기
   * Alforse에서 **Tenant key**를 비워 둘 경우 테넌트 정보 읽기
5. 버전을 생성하고 로그인할 사람들에게 앱을 게시합니다.

**Alforse에서:** **Feishu / Lark**를 선택하고, 사용한 플랫폼과 일치하는 **리전**을 고른 다음 **App ID**와 **App Secret**을 붙여 넣고, 필요하면 **Tenant key**도 붙여 넣은 뒤 **연결**을 선택합니다.

* Feishu 테넌트가 발급한 **기업 이메일**만 검증된 것으로 간주됩니다. 사용자가 자기 프로필에 직접 입력한 주소는 대응에 사용되지 않습니다.
* 기업 이메일이 없는 사람은 [로그인 링크](#sign-in-links)로 한 번 연결합니다.

**DingTalk**

**DingTalk 개발자 콘솔**([https://open-dev.dingtalk.com)에서](https://open-dev.dingtalk.com\)에서):

1. **App Development**(앱 개발)에서 **내부 앱**(企业内部应用)을 생성합니다.
2. **Credentials & Basic Info**(자격 증명 및 기본 정보)에서 **Client ID (AppKey)**와 **Client Secret (AppSecret)**을 복사합니다.
3. **Security Settings → Redirect URL**(보안 설정 → 리디렉션 URL)에 위에 표시된 리디렉션 URI를 추가합니다.
4. **Permissions**(권한)에서 사용자 개인 정보 읽기(`Contact.User.Read`)를 허용합니다.
5. 개발자 콘솔 홈 페이지에서 조직의 **CorpId**를 복사합니다.

**Alforse에서:** **DingTalk**를 선택하고 **Client ID (AppKey)**, **Client Secret (AppSecret)**, **CorpId**를 붙여 넣은 다음 **연결**을 선택합니다.

> [!NOTE]
>
> DingTalk 이메일은 사용자가 직접 관리하므로 Alforse는 대응에 절대 사용하지 않습니다. 각 사람을 [로그인 링크](#sign-in-links)로 한 번 연결하십시오. 그 이후에는 DingTalk로 바로 로그인합니다.

**OpenID Connect**

**자격 증명 공급자**(Okta, Entra ID, Auth0, Keycloak 또는 모든 OIDC 공급자)에서:

1. OpenID Connect **웹 애플리케이션**을 생성합니다. Okta에서는 **Applications → Create App Integration → OIDC – Web Application**입니다.
2. 그랜트 유형을 **Authorization Code**로, 로그인 리디렉션 URI를 위에 표시된 리디렉션 URI로 설정합니다.
3. 로그인할 수 있는 사람 또는 그룹을 지정합니다.
4. **Client ID**와 **Client secret**을 복사합니다.
5. **발급자 URL**을 찾습니다. Okta에서는 **Security → API → Authorization Servers → Issuer URI**이며, 예를 들어 `https://your-org.okta.com/oauth2/default`입니다.

**Alforse에서:** **OpenID Connect**를 선택하고 **발급자 URL**, **Client ID**, **Client secret**을 입력한 다음 **연결**을 선택합니다.

공급자 측 요구 사항:

* 발급자는 자격 증명, 쿼리, 프래그먼트가 없는 `https://` URL이어야 하며, 디스커버리 문서의 `issuer`와 정확히 일치해야 합니다.
* 디스커버리 문서의 모든 엔드포인트는 발급자 자체 호스트의 `https://`여야 합니다.
* ID 토큰은 **RS256**으로 서명되어야 합니다.
* Alforse는 `openid email profile` 스코프를 요청하고 PKCE를 사용합니다. 이메일로 사람을 대응시키려면 ID 토큰에 `email`과 `email_verified: true`가 있어야 합니다.

## 이메일 도메인 검증

연결을 저장한 후 **이메일 도메인** 카드에서 구성원이 로그인에 사용하는 도메인을 각각 추가합니다. **Add a domain**(도메인 추가) 아래에 도메인(예: `example.com`)을 입력하고 **추가**를 선택합니다. 새 도메인은 **대기 중**(Pending)이며 게시할 TXT 레코드가 표시됩니다.

| 필드 | 값 |
| - | - |
| **호스트** | `_alforse-challenge.example.com` |
| **값** | `alforse-domain-verification=<your unique token>` |

DNS 공급자에서 레코드를 게시한 다음 **검증**을 선택합니다. 성공하면 도메인이 **확인됨**(Verified)으로 표시되고 페이지에 "Domain verified"(도메인이 검증되었습니다)가 나타납니다. 규칙은 SAML과 같습니다. [도메인 검증](https://docs.alforse.com/ko/docs/reference/single-sign-on.md#verifying-a-domain)을 참조하십시오.

## 로그인을 사람에게 대응시키는 방법

사용자는 ERP 로그인 페이지에서 업무용 이메일을 입력하고 **계속**을 선택하여 로그인합니다. 검증된 도메인의 이메일이면 공급자로 이동합니다. 돌아오면 Alforse는 회사 내부에서만 다음 순서로 찾습니다.

1. **연결된 계정.** 공급자 계정이 이미 어떤 사람에게 연결되어 있으면 그 사람으로 로그인합니다.
2. **검증된 이메일.** 공급자가 검증된 도메인 중 하나의 검증된 이메일을 알려 줍니다. 일치하는 활성 구성원이면 로그인하고, 일치하는 대기 중인 초대는 수락되어 지정된 역할이 적용됩니다. 그런 다음 계정이 연결됩니다.
3. **로그인 링크.** 사용자가 발급받은 일회용 로그인 링크를 열었습니다. 계정은 링크가 만들어진 대상 구성원 또는 초대에 연결됩니다.

그 외에는 거부되며 계정이 생성되지 않습니다. Feishu / Lark와 DingTalk의 경우 Alforse는 공급자 계정이 연결에 저장된 Tenant key 또는 CorpId에 속하는지도 확인합니다.

NOTE

**사람당 공급자 계정 하나**

각 사람은 공급자별로 연결된 계정을 하나만 가질 수 있습니다. 다른 계정을 연결하려면 먼저 **연결된 계정**에서 기존 계정을 취소(Revoke)하십시오.

## 로그인 링크

공급자가 이메일을 증명하지 못하는 사람, 즉 DingTalk의 모든 사용자와 기업 이메일이 없는 Feishu 사용자를 연결하려면 **로그인 링크** 카드를 사용합니다.

1. **Pending invitation**(대기 중인 초대)을 선택하거나 **Or an existing member's email**(또는 기존 구성원의 이메일)에 입력합니다.
2. **링크 생성**(Create link)을 선택합니다.
3. **Sign-in link created**(로그인 링크가 생성되었습니다) 대화 상자에서 링크를 복사하여 해당 사람에게 직접 보냅니다.

링크는 `https://api.alforse.com/api/web/auth/v1/sso/oauth/invite?token=…` 형식입니다. 해당 사람이 링크를 열고 공급자로 로그인하면 계정이 연결되며, 이후에는 평소처럼 로그인합니다.

* **한 번만 표시.** 링크는 그 대화 상자에서만 표시됩니다. 분실하면 취소하고 새로 만드십시오.
* **1회 사용, 7일 유효.** 표에는 각 링크의 **For**(대상), **상태**(**Open**, **Used**, **Revoked**, **Expired**), **만료**가 표시됩니다. 열려 있는 링크는 **취소**(Revoke)를 선택하여 무효화합니다.
* **검증된 도메인 필요.** 초대 또는 구성원의 이메일이 연결의 검증된 도메인에 속해야 합니다.
* 로그인 링크는 OpenID Connect, Feishu / Lark, DingTalk 연결에서 사용할 수 있으며 SAML에서는 사용할 수 없습니다.

## 연결된 계정

**연결된 계정** 카드에는 모든 연결이 **담당자**(Person), **Provider account**(공급자 계정), **Linked by**(연결 방식: **Verified email** 또는 **Sign-in link**), **연결됨**(Linked)과 함께 나열됩니다. 연결을 제거하려면 **취소**를 선택합니다. 해당 사람의 Alforse 계정은 유지되며, 다음 로그인 때 검증된 이메일로 다시 대응되거나 새 로그인 링크가 필요합니다.

## Single Sign-On 필수화

**Single Sign-On 필수**(Require single sign-on)를 켜면 검증된 도메인의 사용자에게는 공급자가 유일한 접속 방법이 됩니다. 매직 링크 같은 다른 로그인 방법은 이들에게 거부됩니다. 이 스위치는 도메인이 하나 이상 검증된 뒤에 적용되므로, 강제하기 전에 로그인을 테스트할 수 있습니다.

## SAML에서 전환

회사가 이미 [SAML](https://docs.alforse.com/ko/docs/reference/single-sign-on.md)을 사용 중이면 카드에 "Your company currently signs in with SAML. Saving another provider here replaces it."(회사가 현재 SAML로 로그인하고 있습니다. 여기서 다른 공급자를 저장하면 SAML이 대체됩니다.)가 표시됩니다.

* OpenID Connect, Feishu / Lark 또는 DingTalk 연결을 저장하면 연결에서 SAML 설정(IdP 메타데이터)이 제거됩니다. SAML 로그인은 그 시점에 중단됩니다.
* 이메일 도메인과 그 검증, 그리고 **Single Sign-On 필수** 설정은 그대로 유지됩니다.
* SAML이 아닌 연결이 활성인 동안에는 **설정 → 보안**의 SAML 카드를 저장할 수 없습니다. 먼저 이 페이지에서 연결을 비활성화하십시오.

## 비활성화

**자격 증명 공급자** 카드에서 **비활성화**(Deactivate)를 선택하고 **Deactivate single sign-on**(Single sign-on 비활성화)에서 확인합니다. 해당 도메인의 사용자는 더 이상 공급자를 통해 로그인하지 않습니다. 도메인 검증은 제거되지만 연결된 계정은 유지되므로, 나중에 같은 공급자를 다시 연결하면 도메인만 다시 검증하면 됩니다.

## 문제 해결

| 증상 또는 메시지 | 원인 | 해결 방법 |
| - | - | - |
| "Administrators only" | 회사 설정을 변경할 권한이 없습니다. | 관리자에게 `settings` 업데이트 권한을 요청하십시오. |
| "Single sign-on isn't in your plan" | 구독에 Single Sign-On이 포함되어 있지 않습니다. | 플랜을 업그레이드하십시오. |
| "The issuer URL must start with https\://." | 발급자가 https URL이 아니거나, 쿼리 또는 프래그먼트가 있거나, 디스커버리 문서의 `issuer`와 다릅니다. | 디스커버리 문서에 명시된 그대로 발급자를 입력하십시오. |
| "The identity provider couldn't be reached. Check the issuer URL." (자격 증명 공급자에 연결할 수 없습니다. 발급자 URL을 확인하세요.) | 디스커버리 문서를 가져올 수 없거나, 엔드포인트가 발급자 호스트의 https가 아니거나, IdP가 ID 토큰을 RS256으로 서명하지 않습니다. | 발급자 URL과 IdP의 서명 알고리즘을 확인하십시오. |
| "Enter a valid client secret." (유효한 클라이언트 시크릿을 입력하세요.) | 시크릿이 없거나 Feishu가 App ID / App Secret을 거부했습니다. | ID와 시크릿을 다시 복사하고 **리전**을 확인하십시오. |
| "Enter the CorpId." (CorpId를 입력하세요.) | CorpId가 없는 DingTalk이거나, Tenant key도 없고 테넌트도 읽을 수 없는 Feishu입니다. | CorpId를 입력하거나, Feishu Tenant key를 붙여 넣거나, 테넌트 정보 권한을 부여하십시오. |
| "Verify this email's domain first." (먼저 이 이메일의 도메인을 검증하세요.) | 도메인이 검증되지 않은 이메일에 대해 로그인 링크를 만들었습니다. | 도메인을 검증한 다음 링크를 만드십시오. |
| "No invitation or member uses this email." (이 이메일을 사용하는 초대나 구성원이 없습니다.) | 이메일이 활성 구성원 한 명과도 일치하지 않습니다. | 해당 사람을 초대한 다음 초대를 선택하십시오. |
| "The TXT record wasn't found yet. Try again in a few minutes." (아직 TXT 레코드를 찾을 수 없습니다. 몇 분 후에 다시 시도하세요.) | DNS가 아직 전파되지 않았거나 레코드가 잘못된 호스트에 있습니다. | 호스트 이름을 확인하고 다시 시도하십시오. |
| "The configuration changed in the meantime. It has been reloaded — check and try again." (그 사이 설정이 변경되어 다시 불러왔습니다. 확인 후 다시 시도하세요.) | 다른 관리자가 변경 사항을 저장했습니다. | 다시 불러온 페이지를 검토하고 변경을 반복하십시오. |
| 로그인 시: "Single sign-on succeeded, but this account is not yet linked to your company. Ask your administrator for a sign-in link." (Single sign-on은 성공했지만 이 계정은 아직 회사에 연결되지 않았습니다. 관리자에게 로그인 링크를 요청하세요.) | 공급자가 검증된 이메일을 제공하지 않았습니다(DingTalk는 항상 해당). | 해당 사람에게 로그인 링크를 만들어 주십시오. |
| 로그인 시: "Single sign-on succeeded but no invite exists for `jane@example.com`. Contact your administrator." (Single sign-on은 성공했지만 `jane@example.com`에 대한 초대가 없습니다. 관리자에게 문의하세요.) | 검증된 이메일이지만 구성원도 초대받은 사람도 아닙니다. | 초대한 다음 다시 로그인하도록 안내하십시오. |
| 로그인 시: "Single sign-on rejected: this email domain is not registered for your company's single sign-on connection." (Single sign-on이 거부되었습니다. 이 이메일 도메인은 회사의 single sign-on 연결에 등록되어 있지 않습니다.) | 공급자의 이메일이 검증하지 않은 도메인에 속합니다. | 해당 도메인을 검증하십시오. |
| 로그인 시: "This account belongs to another organization than your company's single sign-on connection." (이 계정은 회사의 single sign-on 연결과 다른 조직에 속합니다.) | Feishu 테넌트, DingTalk CorpId 또는 OIDC 발급자가 연결과 일치하지 않습니다. | 해당 사람은 귀사 조직의 계정을 사용해야 합니다. 저장된 Tenant key 또는 CorpId를 확인하십시오. |
| 로그인 시: "This sign-in link is unknown, already used, revoked or expired. Ask your administrator for a new one." (이 로그인 링크는 알 수 없거나 이미 사용, 취소 또는 만료되었습니다. 관리자에게 새 링크를 요청하세요.) | 링크가 사용되었거나, 취소되었거나, 7일이 지났습니다. | 새 링크를 만드십시오. |
| 로그인 시: "Another account of this identity provider is already linked to this user. Contact your administrator." (이 자격 증명 공급자의 다른 계정이 이미 이 사용자에게 연결되어 있습니다. 관리자에게 문의하세요.) | 해당 사람에게 이미 다른 공급자 계정이 연결되어 있습니다. | **연결된 계정**에서 이전 연결을 취소하십시오. |

## 관련 문서

**SAML을 통한 Single Sign-On**

설정 → 보안에서 SAML 2.0 자격 증명 공급자를 연결합니다.

[Open](https://docs.alforse.com/ko/docs/reference/single-sign-on.md)

**인원**

로그인할 사람들을 초대합니다.

[Open](https://docs.alforse.com/ko/docs/reference/people.md)

**2단계 인증**

다른 로그인 방법에 대한 Alforse 자체의 두 번째 인증 요소입니다.

[Open](https://docs.alforse.com/ko/docs/reference/two-factor.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.