본문 바로가기 메뉴 바로가기

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

페이지 이동경로

Adapter API

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

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

getOrgLoginType

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

Request

Request Syntax

코드예제getOrgLoginType Request Syntax 

  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 필수 카카오 i 계정 관리자에서 생성한 Secret Key
ex) KAASK xxxxxxxxxx
Kep-OrgLoginType String 필수 Adapter Agent API Request Header로 전달된 API 조회 용 법인 별 고유 ID
ex) ID xxxxxxxxxx

Response

Response Syntax

코드예제getOrgLoginType Response Syntax 

{
        "_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[] 필수 카카오 i 계정 관리자의 계정 연동 설정에서 활성화된 동기화 옵션 목록
- active_option에 대한 자세한 설명은 개발 프로세스 참고
Object 선택 Login Capability 관련 정보
Object 선택 카카오 i 계정 관리자 사이트에 입력한 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 필수 카카오 i 계정 연동을 위한 Client ID
- 고객사 OAuth 2.0 서버에서 발급
client_secret String 필수 카카오 i 계정 연동을 위한 Client Secret
- 고객사 OAuth 2.0 서버에서 발급
scopes String[] 필수 고객사 OAuth 2.0 연동 시, 카카오 i 계정을 위한 권한 범위들
Object 선택 카카오 i 계정 관리자 사이트에 입력한 SAML 2.0 로그인 관련 정보
registration_id String 필수 카카오 i에서 발급한 고객사(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) 

{
  "_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) 

{
  "_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 

  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 필수 카카오 i 계정 관리자에서 생성한 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 요청 

{
  "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) 

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

uploadDecrypted

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

Request

Request Syntax

코드예제uploadDecrypted Request Syntax 

  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 필수 카카오 i 계정 관리자에서 생성한 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

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

...[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) 

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

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

더 자세한 의견은 contact.dkt@kakaocorp.com 으로 제보해주세요.