Kakao i Account::개발 프로세스

페이지 이동경로

Adapter Agent 서버 구축

카카오 i 서비스 시스템과 고객사의 계정 및 조직도 시스템을 연동하기 위해서는 Adapter Agent API를 구현한 Adapter Agent 서버를 반드시 구축해야 합니다.

주의
본 가이드에서 정의한 API 구현과 다른 방식으로 카카오 i 서비스 시스템을 구현하게 되면, 고객사의 API를 제어하기 어렵습니다. 따라서 본 가이드에서 제시하는 API 구현 방식을 준수하여 주시기 바랍니다.

Adapter Agent 서버 구축 시 고려해야 할 사항은 다음과 같습니다.

  • 고객사는 Adapter Agent API 중에 원하시는 Capability만 선택하여 구현할 수 있습니다.
  • 카카오 i 계정 관리자 화면에서 고객사 조직 정보 및 계정 연동 설정 정보를 입력해야 합니다.
  • 하나의 Adapter Agent 서버에서 여러 개의 법인을 처리하거나, 하나의 법인에서 여러 개의 로그인 방식을 지원할 경우에는 orgLoginTypeId에 따른 분기가 필요할 수 있습니다.
  • 카카오 i 계정 관리자 화면의 정보가 필요할 때, Adapter API를 호출해야 합니다.

Adapter Agent API Capability

Capability는 Adapter Agent API를 호출 목적에 따라 분류하는 기준입니다. Adapter Agent API는 총 5개의 Capability로 분류됩니다.

Capability 목록
목록 필수 구현 설명
Agent Capability 필수 Adapter Agent 서버의 메타정보 또는 공통정보 관련 API 목록
User Capability 선택 사용자 정보 동기화 및 사용자 메타정보 관련 API 목록
Login Capability 선택 로그인 관련 API 목록
OrgUnit Capability 선택 조직도 및 직위/직책 관련 API 목록
SSO Capability 선택 Single Sign-On 관련 API 목록
DRM Capability 선택 DRM 권한 확인 및 해제 요청 API 목록

고객사는 필요에 따라 원하는 Capability만 구현할 수 있습니다. 예를 들면, 계정 동기화와 로그인 기능을 연동하고 싶은 경우에는 Agent Capability와 User Capability, Login Capability를 구현한 Adapter Agent 서버를 구축해야 합니다.

주의
Agent Capability는 카카오 i 서비스 시스템과 연동하기 위해 반드시 구현해야 합니다.
고객사 구현 목록
Capability API 명 분류 설명 비고
Agent Capability getAgentCapabilities 필수 Adapter Agent 서버에 구현된 Capability 정보를 카카오 i 서비스 시스템에 제공
reportError 선택 카카오 i 서비스 시스템으로부터 오류 정보를 수신
User Capability getValidUsers 필수 API 호출 시점을 기준으로 카카오 i 서비스 시스템을 사용할 수 있는 사용자 목록을 제공
getChangedUsers 필수 정보 변경, 활성화 및 비활성화가 일어난 사용자 목록 제공
- 특정 시점부터 API 호출 시점까지
getUserMetadata 필수 사용자 정보의 메타데이터와 사용자 정보 동기화에 대한 옵션 정보 제공
Login Capability identifyUser 선택 입력받은 아이디(ID)와 패스워드(PW) 등이 올바른지 확인 둘 중 하나를 반드시 구현
extractUser 선택 사용자에 대한 추가 정보를 카카오 i 서비스 시스템에 제공
Orgunit Capability getPositions 선택 직위 정보 제공
getResponsibilities 선택 직책 정보 제공
getChangedOrgunits 선택 특정 시점부터 API 호출 시점까지의 추가, 변경, 비활성화가 일어난 조직도 목록 제공
getValidOrgunits 선택 API 요청 시점에서 유효한 조직도 전체 목록 제공 getChangedOrgunits를 구현한 경우 반드시 구현
SSO Capability generateSsoUrl 선택 SSO URL 제공 identifyUser API 또는 extractUser API 중 하나를 필수 구현 필요
- 구현 시, user_principal 필수로 반환
DRM Capability authenticate 선택 파일 타입 확인 후 DRM 파일인 경우, 사용자의 접근 권한 확인 identifyUser API 또는 extractUser API 중 하나를 필수 구현 필요
- 구현 시, user_principal 필수로 반환
decrypt 선택 파일 타입 확인 후 DRM 파일인 경우, 사용자의 접근 권한 확인 및 DRM 해제 요청 identifyUser API 또는 extractUser API 중 하나를 필수 구현 필요
- 구현 시, user_principal 필수로 반환
주의
Capability 별로 필수로 분류된 API는 반드시 구현이 필요합니다.

카카오 i 계정 관리자 화면

카카오 i 계정 관리자 화면은 고객사의 담당자가 조작하는 화면입니다. 해당 화면은 고객사의 카카오 i 계정 조직 Owner(카카오 i 계정에 조직을 최초로 생성한 사용자) 및 카카오 i 계정 조직 Owner가 권한을 부여한 사용자만 접속할 수 있습니다.
해당 관리자 화면에서 Adapter Agent 서버 정보를 입력하고, 계정 연동 설정을 해주셔야만 Adapter Agent API 연동이 정상적으로 이뤄집니다.

카카오 i 계정 관리자 화면 그림카카오 i 관리자 화면

카카오 i 계정 관리자 화면에 접근하는 방법은 다음과 같습니다.

  1. 카카오 i 계정 사이트(account.kakaoi.ai)에 접속합니다.

  2. 카카오 i 계정 사이트의 우측 상단에 [관리자 서비스] 버튼을 클릭합니다.

  3. 로그인을 수행합니다.

  4. 접근 권한이 없을 경우에는 고객사의 카카오 i 계정 조직 Owner에게 권한 부여를 요청합니다.

안내
카카오 i 계정 관리자 화면의 상세 사용 가이드는 카카오엔터프라이즈의 담당자에게 요청하시기 바랍니다.

OrgLoginTypeId에 따른 분기 처리

orgLoginType은 법인의 로그인 방식별 정보를 의미합니다. 그리고 orgLoginTypeIdorgLoginType을 구분하는 고유한 값(ID)입니다. 정의된 의미에서 유추할 수 있듯이 orgLoginTypeId는 법인의 로그인 방식별로 고유합니다.
법인의 로그인 방식별로 orgLoginTypeId를 부여하는 예시는 다음과 같습니다.

법인의 로그인 방식별 orgLoginTypeId 예시
orgLoginTypeId 법인명 계정 타입(인증 방식)
1 AA 전자 LDAP
2 BB 화학 OAuth2
3 CC 기술 SAML2
10 CC 기술 OAuth2
  • AA 전자, BB 화학, CC 기술은 모두 다른 법인이므로 서로 다른 orgLoginTypeId가 부여됩니다.
    • 즉, 각각 다른 orgLoginTypeId를 갖습니다.
  • CC 기술은 카카오 i 서비스 시스템과의 로그인 연동 시, 두 가지 방식(SAML2, OAuth2)을 지원합니다.
    • 그러므로 두 개의 orgLoginTypeId가 부여됩니다.
  • BB화학과 CC 기술은 같은 로그인 방식을 지원하지만, 서로 다른 법인이므로 orgLoginTypeId가 다릅니다.

Adapter API

Adapter API는 카카오 i 서비스 시스템의 Adapter 서버가 제공하는 API입니다. 이 API는 Adapter Agent 서버가 Adapter Agent API의 로직을 실행하는 도중 필요할 수도 있는 정보를 제공합니다. Adapter API가 제공하는 정보는 다음과 같습니다.

  • 카카오 i 계정 서버에 저장된 고객사 조직 정보
  • 고객사 담당자가 카카오 i 계정 관리자 화면에 입력한 계정연동 및 로그인 관련 정보
Adapter API 목록
Capability API 명 설명
Login Capability getOrgLoginType 카카오 i 계정 관리자 화면의 계정 연동 설정 화면에 입력한 정보를 제공
DRM Capability uploadResult Adapter서버가 Adapter Agent 서버로부터 해당 파일에 대한 사용자의 DRM 권한 확인 결과를 전달
uploadDecrypted Adapter서버가 Adapter Agent 서버에게 DRM 해제된 파일을 전달

Adapter API를 호출할 때 고려해야 하는 사항은 다음과 같습니다.

  • Adapter Agent API의 어떤 Capability를 구현했는지와 상관없이 모든 Adapter API를 호출할 수 있습니다.
  • 카카오 i 계정 관리자 화면에서 Adapter Agent 서버 IP 정보를 입력하고 Secret Key를 발급한 뒤, 이 값을 API 호출에 사용해야 합니다.

관련 문서

Adapter Agent Kakao i Account 개발 프로세스 Kakao i Account API 레퍼런스 Kakao i Account

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.