Lark와 Guance (SaaS) OIDC 설정 설명¶

이 문서는 두 부분으로 구성됩니다.

• Lark 통합 플랫폼(Anycross)과 Guance 연동 설명
• Lark 네이티브 플랫폼과 Guance 연동 설명

Lark 측에서 애플리케이션을 생성한 방식에 따라 해당 섹션의 설정 단계와 JSON 템플릿을 사용하세요.

1. Lark 통합 플랫폼(Anycross) 연동 설명¶

사용 사례¶

Lark 통합 플랫폼을 통해 https://anycross.feishu.cn）创建的应用与Guance (SaaS)와 OIDC로 SSO 연동할 때 사용합니다.

핵심 규칙¶

• Lark 애플리케이션의 Token 인증 방식이 client_secret_basic인 경우: Guance UI에서 직접 clientId/clientSecret를 입력할 수 있으며 JSON 템플릿을 가져올 필요가 없습니다(권장).
• Token 인증 방식이 client_secret_post인 경우: Guance의 '비OIDC 표준 설정'에서 JSON 템플릿을 가져와야 합니다.

고객이 준비해야 할 정보¶

고정된 claimMapping:

{
  "email": "enterprise_email",
  "mobile": "mobile",
  "username": "email",
  "exterId": "enterprise_email"
}

설명: Lark OIDC가 반환하는 enterprise_email는 회사 이메일로, 일반적으로 항상 존재하며 고유합니다. Guance의 email를 이 필드에 매핑하는 것을 권장합니다.

Lark 통합 플랫폼 측 확인 항목¶

• App ID, App Secret이 유효한지 확인합니다.
• 서비스 검색 주소(서비스 검색 URL, 템플릿 필드는 wellKnowURL)를 가져옵니다.
• 인증 방식은 authorization_code여야 합니다. Scope에 openid, profile, email, phone, offline_access가 포함되어 있는지 확인합니다.
• Token 교환 시 인증 방식(client_secret_basic 또는 client_secret_post)을 확인합니다.

Guance 측 설정¶

시나리오 1 - client_secret_basic(권장)

1. Guance에 로그인하여 SSO 설정 → OIDC 페이지로 이동한 후 서비스 검색 주소, clientId 및 clientSecret를 입력합니다.
2. 저장하고 SSO 로그인을 테스트합니다.

시나리오 2 - client_secret_post

1. Guance 공식 문서의 'OIDC 비표준 설정' 섹션을 참조하여 아래 JSON 템플릿에서 clientId, clientSecret, wellKnowURL를 입력합니다.
2. Guance의 OIDC 비표준 설정 페이지에서 이 JSON 템플릿을 가져와 저장한 후 SSO 로그인을 테스트합니다.

JSON 템플릿(client_secret_post 시나리오 전용)¶

{
  "scope": ["openid","profile","email"],
  "authSet": {
    "url": "",
    "verify": true,
    "paramMapping": {
      "scope": "$scope",
      "state": "$state",
      "client_id": "$client_id",
      "redirect_uri": "$redirect_uri",
      "response_type": "$response_type"
    }
  },
  "clientId": "<填写 App ID>",
  "clientSecret": "<填写 App Secret>",
  "modeType": "expert",
  "grantType": "authorization_code",
  "sslVerify": true,
  "getTokenSet": {
    "url": "",
    "method": "post",
    "verify": true,
    "authMethod": "none",
    "paramMapping": {
      "code": "$code",
      "state": "$state",
      "grant_type": "$grant_type",
      "redirect_uri": "$redirect_uri",
      "client_id": "$client_id",
      "client_secret": "$client_secret"
    }
  },
  "wellKnowURL": "<填写飞书服务发现地址>",
  "claimMapping": {
    "email": "enterprise_email",
    "mobile": "mobile",
    "username": "email",
    "exterId": "enterprise_email"
  },
  "getUserInfoSet": {
    "url": "",
    "method": "get",
    "source": "origin",
    "authMethod": "bearer",
    "paramMapping": {},
    "responseInfoPath": ""
  },
  "verifyTokenSet": {"url": "", "keys": [], "method": "get", "verify": true}
}

템플릿 입력 설명: clientId, clientSecret, wellKnowURL만 수정하면 됩니다. 나머지 필드는 기본값을 유지합니다(모든 url 필드는 비워두며, 서비스 검색 주소가 자동으로 인터페이스를 인식합니다).

2. Lark 네이티브 플랫폼 연동 설명¶

Lark 네이티브 플랫폼에서 생성한 애플리케이션과 Guance (SaaS)를 OIDC로 연동하는 시나리오에 사용합니다. 이 섹션의 설정을 '통합 플랫폼' 설정과 혼용하지 마세요.

비호환 지점 및 적용 이유¶

• Lark 네이티브 플랫폼은 Code를 Token으로 교환할 때 Basic 인증을 지원하지 않으며, client_secret_post(POST body로 매개변수 전달)만 지원합니다.
• Lark가 반환하는 사용자 정보에 data 중첩 레이어가 포함되어 있으므로, 템플릿에서 responseInfoPath를 data로 지정해야 합니다.

고객이 준비해야 할 정보¶

고정된 claimMapping:

{
  "email": "enterprise_email",
  "mobile": "mobile",
  "username": "email",
  "exterId": "enterprise_email"
}

고정된 scope 목록 예시(반드시 Lark에서 실제로 활성화한 권한과 일치해야 함):

["component:user_profile","contact:user.employee_id:readonly","contact:user.email:readonly"]

Lark 측 확인 항목¶

• client_id(App ID)와 client_secret(App Secret)가 올바른지 확인합니다.
• 권한 관리에서 템플릿에 나열된 scope 권한이 활성화되어 있고 애플리케이션이 게시되었는지 확인합니다.
• 콜백 주소 예약: Guance에서 콜백 주소가 생성되며, 이 주소를 Lark 애플리케이션의 콜백 주소에 설정하고 게시해야 합니다.

Guance 측 설정 및 콜백 설정¶

1. Guance의 OIDC 비표준 설정 페이지에서 아래 템플릿을 사용하고 clientId와 clientSecret만 교체하며, 다른 필드는 변경하지 않습니다.
2. getUserInfoSet.responseInfoPath가 data인지 확인합니다(Lark 반환 구조에 맞게 조정).
3. 템플릿을 가져와 저장하고, Guance에서 생성된 콜백 주소를 복사하여 Lark 애플리케이션 개발 설정 → 콜백 주소에 입력한 후 애플리케이션을 게시합니다.
4. SSO 로그인을 테스트합니다.

JSON 템플릿(Lark 네이티브 플랫폼 전용)¶

{
  "scope": [
    "component:user_profile",
    "contact:user.employee_id:readonly",
    "contact:user.email:readonly"
  ],
  "authSet": {
    "url": "https://accounts.feishu.cn/open-apis/authen/v1/authorize",
    "verify": true,
    "paramMapping": {
      "scope": "$scope",
      "state": "$state",
      "client_id": "$client_id",
      "redirect_uri": "$redirect_uri",
      "response_type": "$response_type"
    }
  },
  "clientId": "<填写 App ID>",
  "clientSecret": "<填写 App Secret>",
  "modeType": "expert",
  "grantType": "authorization_code",
  "sslVerify": true,
  "getTokenSet": {
    "url": "https://open.feishu.cn/open-apis/authen/v2/oauth/token",
    "method": "post",
    "verify": true,
    "authMethod": "none",
    "paramMapping": {
      "code": "$code",
      "state": "$state",
      "grant_type": "$grant_type",
      "redirect_uri": "$redirect_uri",
      "client_id": "$client_id",
      "client_secret": "$client_secret"
    }
  },
  "wellKnowURL": "",
  "claimMapping": {
    "email": "enterprise_email",
    "mobile": "mobile",
    "username": "email",
    "exterId": "enterprise_email"
  },
  "getUserInfoSet": {
    "url": "https://open.feishu.cn/open-apis/authen/v1/user_info",
    "method": "get",
    "source": "origin",
    "authMethod": "bearer",
    "paramMapping": {},
    "responseInfoPath": "data"
  },
  "verifyTokenSet": {"url": "", "keys": [], "method": "get", "verify": true}
}

템플릿 설명: clientId, clientSecret만 수정하면 됩니다. 다른 필드는 Lark 공식 고정 설정이므로 변경하지 마세요.

자주 묻는 질문 및 문제 해결¶

문제 1: 콜백 주소가 올바르지 않음(오류 코드: 20029)¶

현상: SSO 로그인 시 redirect_uri가 올바르지 않다는 메시지가 표시됩니다.

해결 방법: Guance SSO 설정 페이지에서 시스템에서 생성된 콜백 주소를 복사하여(수동으로 변경하지 마세요) Lark 애플리케이션의 콜백 주소 설정에 붙여넣고 게시한 후, Guance에서 설정을 새로고침하고 다시 시도합니다.

문제 2: 인증 실패(메시지: SSO 계정 이메일을 찾을 수 없음)¶

현상: 로그인 시 SSO 계정 이메일을 찾을 수 없다는 오류가 발생합니다.

해결 방법: Lark가 반환한 사용자 정보(오류의 trace_id를 통해 확인)를 확인하고 getUserInfoSet.responseInfoPath의 설정을 확인합니다.

• 사용자 정보가 data 중첩 레이어에 있는 경우 responseInfoPath = "data"를 유지합니다.
• 플랫 구조로 반환되는 경우 responseInfoPath = ""(빈 문자열)로 설정합니다.

수정 후 템플릿을 다시 가져와 테스트합니다.

문제 3: 권한 부족(Scope 설정 이상)¶

해결 방법: Lark 애플리케이션에서 템플릿에 나열된 scope 권한이 활성화되어 있고 게시되었는지 확인합니다. JSON 템플릿의 scope 목록이 Lark 측과 완전히 일치하는지 확인한 후 다시 가져와 저장합니다.