Adapter API

Adapter API는 카카오워크에서 제공하고 있으며, 해당 API를 통해서 Adapter Agent 서버를 구현한 고객사의 로그인 방식을 제공받을 수 있습니다.

표Adapter API 목록

구분	API 명	설명
Login	getOrgLoginType	Adapter Agent 서버를 구현한 고객사의 로그인 방식에 대한 정보를 제공 ex) LDAP, OAuth 2.0, SAML 2.0 등
DRM	uploadResult	DRM 해제 요청 결과를 제공
DRM	uploadDecrypted	DRM이 해제된 파일을 요청받은 카카오워크 서비스로 업로드

getOrgLoginType

getOrgLoginType API는 Adapter Agent 서버를 구현한 고객사의 로그인 방식에 대한 정보를 제공하는 API입니다.

Request

Request Syntax

코드예제getOrgLoginType Request Syntax

BASH

  curl -X GET 'http://adapter.kakaoi.ai/api/trust/login/v0/getOrgLoginType' \
    --header 'Authorization: KAASK {YOUR_SECRET_KEY}' \
    --header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}' \

표API 호출 방식

메서드	요청 URL
GET	`/api/trust/login/v0/getOrgLoginType`

Request Header

표getOrgLoginType Request Header

파라미터	타입	필수 여부	설명
Authorization	String	`필수`	카카오워크 계정 관리자에서 생성한 Secret Key ex) KAASK xxxxxxxxxx
Kep-OrgLoginType	String	`필수`	Adapter Agent API Request Header로 전달된 API 조회 용 법인 별 고유 ID ex) ID xxxxxxxxxx

Response

Response Syntax

코드예제getOrgLoginType Response Syntax

JSON

{
        "_code": 000,
        "_message": "string",
        "id": 0,
        "method": "string",
        "adapter_agent": "string",
        "data_model": {
                "user": {
                        "synchronization": {
                                "options": [
                                        "string",
                                        ...
                                ]
                        }
                },
                "login": {
                        "oauth2": {
                                "authorization_endpoint": "string",
                                "token_endpoint": "string",
                                "response_type": "string",
                                "client_id": "string",
                                "client_secret": "string",
                                "scopes": [
                                        "string",
                                        ...
                                ]
                        },
                        "saml2": {
                                "registration_id": "string",
                                "saml_metadata_fetching_type": "string",
                                "metadata_location": "string",
                                "entity_id": "string",
                                "verification_certificate": "string",
                                "encryption_certificate": "string",
                                "sso_service_location": "string",
                                "sso_service_binding": "string",
                                "want_authn_request_signed": boolean
                        }
                }
        }
}

Response Elements

표getOrgLoginType Response Elements

필드	타입	필수 여부	설명
_code	Integer	`필수`	HTTP 상태 코드 3자리 (공통 상태 코드 참고)
_message	String	`필수`	결과 메시지
id	Integer	`필수`	`orgLoginType` ID
method	String	`필수`	계정연동 및 로그인 방법
adapter_agent	String	`필수`	Agent Server Host 명
	Object	`선택`	각 Adapter Agent 별 정의된 User Capability 관련 정보
	Object	`선택`	User Capability 관련 정보
	Object	`선택`	동기화 관련 정보
active_options	String[]	`필수`	카카오워크 계정 관리자의 계정 연동 설정에서 활성화된 동기화 옵션 목록 - `active_option`에 대한 자세한 설명은 개발 프로세스 참고
	Object	`선택`	Login Capability 관련 정보
	Object	`선택`	카카오워크 계정 관리자 사이트에 입력한 OAuth 2.0 로그인 관련 정보
authorization_endpoint	String	`필수`	OAuth 2.0 연동에서 인증을 수행하기 위한 Authorization Endpoint - OAuth 2.0 서버 인증 API URL
token_endpoint	String	`필수`	OAuth 2.0 연동에서 토큰 관련 작업을 수행하기 위한 Token Endpoint - OAuth 2.0 서버 토큰 API URL
response_type	String	`필수`	고객사 OAuth 2.0 서버 인증 시 지원하는 응답 방식 ex) `code`
client_id	String	`필수`	카카오워크 계정 연동을 위한 Client ID - 고객사 OAuth 2.0 서버에서 발급
client_secret	String	`필수`	카카오워크 계정 연동을 위한 Client Secret - 고객사 OAuth 2.0 서버에서 발급
scopes	String[]	`필수`	고객사 OAuth 2.0 연동 시, 카카오워크 계정을 위한 권한 범위들
	Object	`선택`	카카오워크 계정 관리자 사이트에 입력한 SAML 2.0 로그인 관련 정보
registration_id	String	`필수`	카카오워크에서 발급한 고객사(IDP) ID
entity_id	String	`필수`	고객사(IDP) Entity ID
saml_metadata_fetching_type	String	`필수`	Metadata Fetch 방식 - `FROM_DATABASE` - `FROM_METADATA_LOCATION`
metadata_location	String	`선택`	고객사(IDP)의 메타 데이터를 제공하는 Endpoint URI
verification_certificate	String	`선택`	전자서명용 고객사(IDP) 인증서
encryption_certificate	String	`선택`	암호화용 고객사(IDP) 인증서
want_authn_request_signed	Boolean	`선택`	Request 전자 서명 필수 여부
sso_service_binding	String	`선택`	바인딩(Binding) 방식 - POST/REDIRECT
sso_service_location	String	`선택`	고객사(IDP) Web Login URI

Sample Code

코드예제OAuth 2.0 기반 로그인 연동 시 orgLoginType 정보(HTTP 상태 코드: 200)

JSON

{
  "_code": 200,
  "_message": "ok",
  "id": 3,
  "method": "OAUTH2",
  "adapter_agent": "http://example-adapter-agent.com",
  "data_model": {
    "user": {
      "synchronization": {
        "options": ["정직원", "계약직", "인턴"]
      }
    },
    "login": {
      "oauth2": {
        "authorization_endpoint": "/oauth/authorize",
        "token_endpoint": "/oauth/token",
        "response_type": "code",
        "client_id": "test_client_id_example",
        "client_secret": "test_client_secret_example",
        "scopes": ["admin", "public", "guest"]
      }
    }
  }
}

코드예제SAML 2.0 기반 로그인 연동 시 orgLoginType 정보(HTTP 상태 코드: 200)

JSON

{
  "_code": 200,
  "_message": "ok",
  "id": 3,
  "method": "SAML2",
  "adapter_agent": "http://example-adapter-agent.com",
  "data_model": {
    "user": {
      "synchronization": {
        "options": ["정직원", "계약직"]
      }
    },
    "login": {
      "saml2": {
        "registration_id": "1",
        "saml_metadata_fetching_type": "FROM_DATABASE",
        "metadata_location": "https://test-client.com/saml2/metadataLocation",
        "entity_id": "https://test-client.com/entityId",
        "verification_certificate": "-----BEGIN CERTIFICATE-----\nMIIDgjCCAmoCCQ ...\n-----END CERTIFICATE-----",
        "encryption_certificate": "-----BEGIN CERTIFICATE-----\nMIIDgjC5TvN7pE ...\n-----END CERTIFICATE-----",
        "sso_service_location": "https://test-client.com/saml2/SSOService",
        "sso_service_binding": "REDIRECT",
        "want_authn_request_signed": false
      }
    }
  }
}

uploadResult

uploadResult API는 파일의 DRM 해제 요청 결과를 제공하는 API입니다.

Request

Request Syntax

코드예제uploadResult Request Syntax

BASH

  curl -X POST http://adapter.kakaoi.ai/api/trust/drm/v0/uploadResult \
    -H "Authorization: KAASK {AGENT_SECRET_KEY}" \
    -H "Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}" \
    -H "Kep-AgentSession: DSID {SESSION_ID}" \
    -H "Kep-File-Id: xxxxxx" \
    -H "Kep-File-Type: DRM" \
    -d "{
			'result': 'SUCCESS',
			'reason': 'OK',
			'extra': { ... }
		}"

표API 호출 방식

메서드	요청 URL
POST	`/api/trust/drm/v0/uploadResult`

Request Header

표uploadResult Request Header

파라미터	타입	필수 여부	설명
Authorization	String	`필수`	카카오워크 계정 관리자에서 생성한 Secret Key ex) KAASK xxxxxxxxxx
Kep-OrgLoginType	String	`필수`	Adapter Agent API Request Header로 전달된 API 조회용 법인 별 고유 ID ex) ID xxxxxxxxxx
Kep-AgentSession	String	`필수`	Adapter Agent 서버에서 DRM 해제를 요청한 세션을 구분하는 세션 ID ex) DSID xxxxxx
Kep-File-Id	String	`필수`	DRM 권한을 확인하는 파일 ID ex) xxxxxx
Kep-File-Type	String	`필수`	해당 파일 type 고정값
			- `DRM`: DRM 해제가 필요한 파일 (DRM으로 암호화된 파일)
			- `PLAIN`: 일반 파일 (DRM으로 암호화되지 않은 파일)

Request Body

표uploadResult Request Body

파라미터	타입	필수 여부	설명
result	String	`필수`	결과 코드 고정값
			`DRM`(DRM 해제가 필요한 파일) - `SUCCESS`: 사용자가 파일 접근 권한이 있으며, decrypt API를 호출할 수 있음 - `FAILURE`: 사용자가 파일 접근 권한 없음
			`PLAIN`(일반 파일) - `FAILURE`: DRM 해제가 불필요한 일반 파일
reason	String	`필수`	`result`에 대한 원인(이유) 메시지
extra	Object	`선택`	추가 정보 - 사용자를 식별할 수 있는 추가 정보(ex. 사용자 IP 정보, 사용자 브라우저 정보)

Sample Code

코드예제uploadResult 요청

JSON

{
  "result": "SUCCESS",
  "reason": "OK",
  "extra": {
    "user_ip": "172.0.0.1",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; rv:11.0) like Gecko KakaoWork/windows/1.2.0.1476/-"
  }
}

Response

Response Header

표uploadResult Response Header

필드	타입	필수 여부	설명
X-Request-Id	String	`선택`	요청마다 고유한 Key 값으로 디버깅에 활용됨

Response Body

표uploadResult Response Body

필드	타입	필수 여부	설명
_code	Integer	`필수`	HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message	String	`필수`	응답 메시지

Sample Code

코드예제uploadResult Response (HTTP 상태 코드: 200)

JSON

{
  "_code": 200,
  "_message": "ok"
}

uploadDecrypted

uploadDecrypted API는 DRM 해제된 파일을 요청받은 카카오워크 서비스로 업로드하는 API입니다.

Request

Request Syntax

코드예제uploadDecrypted Request Syntax

BASH

  curl -X POST http://adapter.kakaoi.ai/api/trust/drm/v0/uploadDecrypted \
    -H "Content-Type: multipart/form-data" \
    -H "Authorization: KAASK {AGENT_SECRET_KEY}" \
    -H "Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}" \
    -H "Kep-AgentSession: DSID {이전 인증에서 요청한 SESSION ID}" \
    -H "Kep-File-Id: xxxxxx" \
    -H "X-Request-Id: xxxxxx" \
    -F "file=@'{FILE_PATH}'"

표API 호출 방식

메서드	요청 URL
POST	`/api/trust/drm/v0/uploadDecrypted`

Request Header

표uploadDecrypted Request Header

파라미터	타입	필수 여부	설명
Content-Type	String	`필수`	`multipart/form-data`
Authorization	String	`필수`	카카오워크 계정 관리자에서 생성한 Secret Key ex) KAASK xxxxxxxxxx
Kep-OrgLoginType	String	`필수`	Adapter Agent API Request Header로 전달된 API 조회용 법인 별 고유 ID ex) ID xxxxxxxxxx
Kep-AgentSession	String	`필수`	Adapter Agent 서버에서 DRM 해제를 요청한 세션을 구분하는 세션 ID ex) DSID xxxxxx
Kep-File-Id	String	`필수`	DRM 권한을 확인하는 파일 ID ex) xxxxxx

Request Body

표uploadDecrypted Request Body

파라미터	타입	필수 여부	설명
file	Binary	`필수`	DRM을 해제할 파일 스트림

Sample Code

코드예제카카오워크 서비스 시스템을 통한 uploadDecrypted 요청

JSON

...[FILE]...

Response

Response Header

표uploadDecrypted Response Header

필드	타입	필수 여부	설명
X-Request-Id	String	`선택`	요청마다 고유한 Key 값으로 디버깅에 활용됨

Response Body

표uploadDecrypted Response Body

필드	타입	필수 여부	설명
_code	Integer	`필수`	HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message	String	`필수`	응답 메시지

Sample Code

코드예제uploadDecrypted 정상 응답(HTTP 상태 코드: 200)

JSON

{
  "_code": 200,
  "_message": "ok"
}

카카오워크 기술문서

Kakao Work Account::API 레퍼런스::Adapter API

페이지 이동경로

Adapter API

getOrgLoginType

Request

Request Syntax

Request Header

Response

Response Syntax

Response Elements

Sample Code

uploadResult

Request

Request Syntax

Request Header

Request Body

Sample Code

Response

Response Header

Response Body

Sample Code

uploadDecrypted

Request

Request Syntax

Request Header

Request Body

Sample Code

Response

Response Header

Response Body

Sample Code