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

페이지 이동경로

Adapter API

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

Adapter API 목록
구분 API 명 설명
Login getOrgLoginType Adapter Agent 서버를 구현한 고객사의 로그인 방식에 대한 정보를 제공
ex) LDAP, OAuth2, SAML2 등
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 계정 관리자 화면에 입력한 OAuth2 로그인 관련 정보
authorization_endpoint String 필수 OAuth2 연동에서 Authorize를 수행하기 위한 Authorization Endpoint
- OAuth2 서버 인증 API URL
token_endpoint String 필수 OAuth2 연동에서 Token 관련 작업을 수행하기 위한 Token Endpoint
- OAuth2 서버 토큰 API URL
response_type String 필수 고객사 OAuth2 서버 인증 시 지원하는 응답 방식
ex) code
client_id String 필수 카카오 i 계정 연동을 위한 Client ID
- 고객사 OAuth2 서버에서 발급
client_secret String 필수 카카오 i 계정 연동을 위한 Client Secret
- 고객사 OAuth2 서버에서 발급
scopes String[] 필수 고객사 OAuth2 연동 시, 카카오 i 계정을 위한 권한 범위들
Object 선택 카카오 i 계정 관리자 화면에 입력한 SAML2 로그인 관련 정보
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) Metadata를 제공하는 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

코드예제OAuth2 기반 로그인 연동 시 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"
                ]
            }
        }
    }
}

코드예제SAML2 기반 로그인 연동 시 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"
}

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

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