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는 총 여섯 개의 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 계정(account.kakaoi.ai) 사이트에 접속합니다.
- [관리자 서비스] 버튼을 클릭한 후, 로그인을 수행합니다.
- 접근 권한이 없을 경우에는 고객사의 카카오 i 계정 조직 Owner에게 권한 부여를 요청합니다.
안내
카카오 i 계정 관리자 사이트에 관련된 자세한 설명은 카카오 i 계정 관리자 문서를 참고하시기 바랍니다.
OrgLoginTypeId에 따른 분기 처리
OrgLoginType은 법인의 로그인 방식별 정보를 의미합니다. 그리고 orgLoginTypeId는 orgLoginType을 구분하는 고유한 값(ID)입니다. 정의된 의미에서 유추할 수 있듯이 orgLoginTypeId는 법인의 로그인 방식별로 고유합니다.
법인의 로그인 방식별로 OrgLoginTypeId를 부여하는 예시는 다음과 같습니다.
| OrgLoginTypeId | 법인명 | 계정 타입(인증 방식) |
|---|---|---|
| 1 | AA 전자 | LDAP |
| 2 | BB 화학 | OAuth 2.0 |
| 3 | CC 기술 | SAML 2.0 |
| 10 | CC 기술 | OAuth 2.0 |
- AA 전자, BB 화학, CC 기술은 모두 다른 법인이므로 서로 다른 OrgLoginTypeId가 부여됩니다.
- 즉, 각각 다른 OrgLoginTypeId를 갖습니다.
- CC 기술은 카카오 i 서비스 시스템과의 로그인 연동 시, 두 가지 방식(SAML 2.0, OAuth 2.0)을 지원합니다.
- 그러므로 두 개의 OrgLoginTypeId가 부여됩니다.
- BB화학과 CC 기술은 같은 로그인 방식을 지원하지만, 서로 다른 법인이므로 OrgLoginTypeId가 다릅니다.
Adapter API
Adapter API는 카카오 i 서비스 시스템의 Adapter 서버가 제공하는 API입니다. 이 API는 Adapter Agent 서버가 Adapter Agent API의 로직을 실행하는 도중 필요할 수도 있는 정보를 제공합니다. Adapter API가 제공하는 정보는 다음과 같습니다.
표Adapter API 목록
- 카카오 i 계정 서버에 저장된 고객사 조직 정보
- 고객사 담당자가 카카오 i 계정 관리자 사이트에 입력한 계정 연동 및 로그인 관련 정보
| 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 카카오 i 계정 관리자 Kakao i Account