Lark와 Guance(SaaS) OIDC 구성 안내¶

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

Lark 통합 플랫폼(Anycross)과 Guance 연동 안내
Lark 네이티브 플랫폼과 Guance 연동 안내

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

1. Lark 통합 플랫폼(Anycross) 연동 안내¶

사용 사례¶

Lark 통합 플랫폼(https://anycross.feishu.cn)에서 생성한 애플리케이션과 Guance(SaaS) 간 OIDC 기반 SSO 연동에 적용됩니다.

핵심 규칙¶

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

고객이 준비해야 할 정보¶

정보 항목	설명
clientId	애플리케이션의 클라이언트 ID(App ID)
clientSecret	애플리케이션의 클라이언트 시크릿(App Secret)
scope	요청할 권한 범위로, 애플리케이션에 개설된 권한 및 실제 용도와 일치해야 합니다
claimMapping	계정 정보 매핑으로, 실제 userinfo 필드와 일치해야 합니다

claimMapping 예시:

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

설명: 템플릿은 로그인 이메일을 enterprise_email로 매핑합니다. 애플리케이션이 해당 필드를 가져올 권한이 있고 대상 사용자의 실제 userinfo에서 유효한 이메일이 반환되는지 확인하세요. 해당 필드가 항상 존재한다고 가정할 수 없습니다. 다른 이메일 필드를 사용하려면 먼저 계정 신원 요건에 부합하는지 확인한 후 claimMapping.email을 조정하세요.

현재 로그인은 email, name, username, mobile 매핑을 읽으며, 유효한 이메일이 필수입니다. exterId 매핑은 이 로그인 흐름에 참여하지 않으므로 템플릿에 입력할 필요가 없습니다.

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

App ID와 App Secret이 유효한지 확인합니다.
서비스 디스커버리 주소(서비스 디스커버리 URL, 템플릿 필드: wellKnowURL)를 확인합니다.
인가 모드는 authorization_code여야 합니다. 템플릿은 openid, profile, email을 기본으로 하므로 서비스 디스커버리 정보 및 실제 개설된 권한을 기준으로 확인하세요.
휴대폰 번호 또는 오프라인 인증이 필요하면 애플리케이션이 해당 phone, offline_access scope를 지원하고 요청이 승인되었는지 먼저 확인한 후 필요에 따라 템플릿에 추가하세요. 이 두 scope를 모든 로그인 시나리오의 필수 항목으로 설정하지 마세요.
토큰 교환 인증 방식(client_secret_basic 또는 client_secret_post)을 확인합니다.

Guance 측 구성¶

시나리오 1 — client_secret_basic(권장)

Guance에 로그인하여 SSO 구성 → OIDC 페이지로 이동한 후 서비스 디스커버리 주소, clientId, clientSecret을 입력합니다.
저장하고 SSO 로그인을 테스트합니다.

시나리오 2 — client_secret_post

Guance 공식 문서의 '비표준 OIDC 설정' 섹션을 참조하여 아래 JSON 템플릿에 clientId, clientSecret, wellKnowURL을 입력합니다.
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"
  },
  "getUserInfoSet": {
    "url": "",
    "method": "get",
    "source": "origin",
    "authMethod": "bearer",
    "paramMapping": {},
    "responseInfoPath": ""
  },
  "verifyTokenSet": {"url": "", "keys": [], "method": "get", "verify": true}
}

템플릿 입력 설명: clientId, clientSecret, wellKnowURL을 입력하고 scope와 claimMapping을 확인하세요. 각 API의 url 필드를 비워 두면 서비스 디스커버리 정보로 API 주소를 식별합니다.

2. Lark 네이티브 플랫폼 연동 안내¶

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

비호환 항목 및 적용 이유¶

Lark 네이티브 플랫폼은 코드를 토큰으로 교환할 때 Basic 인증을 지원하지 않으며 client_secret_post(POST 본문으로 매개변수 전달)만 지원합니다.
Lark가 반환하는 사용자 정보에 data 중첩 계층이 포함되므로 템플릿의 responseInfoPath를 data로 지정해야 합니다.

고객이 준비해야 할 정보¶

정보 항목	설명
clientId	App ID
clientSecret	App Secret
scope	권한 목록 예시로, Lark 측 실제 개설 권한 및 실제 용도와 일치해야 합니다
claimMapping	계정 매핑으로, 실제 userinfo 필드와 일치해야 합니다

claimMapping 예시:

{
  "email": "enterprise_email",
  "mobile": "mobile",
  "username": "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 측 구성 및 콜백 설정¶

Guance의 비표준 OIDC 설정 페이지에서 아래 템플릿을 사용하여 clientId와 clientSecret을 입력하고 실제 개설된 권한과 계정 필드 매핑을 확인합니다.
getUserInfoSet.responseInfoPath가 data인지 확인합니다(Lark 응답 구조 적용).
템플릿을 가져와 저장한 후, Guance이 생성한 콜백 주소를 복사하여 Lark 애플리케이션 개발 구성 → 콜백 주소에 입력하고 애플리케이션을 게시합니다.
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"
  },
  "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을 입력한 후 scope 및 실제 반환되는 claimMapping.email 필드를 확인하세요. getTokenSet은 POST 본문으로 클라이언트 자격 증명을 전송하며, responseInfoPath=data는 사용자 정보를 추출하는 데 사용됩니다. 연동하는 API의 프로토콜 및 응답 구조와 일치해야 합니다.

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

문제 1: 콜백 주소가 유효하지 않음(오류 코드: 20029)¶

증상: SSO 로그인 시 redirect_uri가 유효하지 않다는 메시지가 표시됩니다.

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

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

증상: 로그인 시 SSO 계정 이메일을 찾을 수 없다는 오류가 표시됩니다.

해결: 오류 메시지의 trace_id를 통해 Lark가 반환한 사용자 정보를 확인하고 getUserInfoSet.responseInfoPath 구성을 확인합니다.

사용자 정보가 data 중첩 계층에 있으면 responseInfoPath = "data"를 유지합니다.
반환 구조가 평면 구조이면 responseInfoPath = ""(빈 문자열)로 설정합니다.
해당 계층을 추출한 후 claimMapping.email이 가리키는 필드가 실제로 존재하고 유효한 이메일인지 확인합니다.
이메일 필드가 반환되지 않으면 애플리케이션 권한, 사용자 승인, 사용자 이메일 정보를 확인합니다. responseInfoPath만 수정해서는 이메일 필드 누락을 해결할 수 없습니다.

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

문제 3: 권한 부족(Scope 구성 오류)¶

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

Lark와 Guance(SaaS) OIDC 구성 안내¶

1. Lark 통합 플랫폼(Anycross) 연동 안내¶

사용 사례¶

핵심 규칙¶

고객이 준비해야 할 정보¶

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

Guance 측 구성¶

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

2. Lark 네이티브 플랫폼 연동 안내¶

비호환 항목 및 적용 이유¶

고객이 준비해야 할 정보¶

Lark 측 확인 항목¶

Guance 측 구성 및 콜백 설정¶

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

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

문제 1: 콜백 주소가 유효하지 않음(오류 코드: 20029)¶

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

문제 3: 권한 부족(Scope 구성 오류)¶

이 페이지가 도움이 되었나요? ×

이 페이지가 도움이 되었나요?