통합인증 API
-
접근토큰 발급 요청(정보제공자 제공) v1 2021-10-18
기본 정보API ID 통합인증-002 HTTP Method POST API 제공자 정보제공자, 중계기관 API 요청자 마이데이터사업자 API 명 (URI) /oauth/2.0/token 설명 마이데이터사업자는 고객이 선택한 정보제공자를 대상으로 통합인증을 요청(전자서명 전송)
- 마이데이터 서버는 1개 이상의 정보제공자에게 해당 기관을 대상으로 하는 전자서명을 각각 전송
- 요청메시지 내 auth_type, consent_type 항목 설정 방식
＊ 공동인증서(본인확인기관) 기반 통합인증 : auth_type : 0, consent_type : 0
＊ 사설인증서(전자서명인증사업자) 기반 통합인증 : auth_type : 1, consent_type : 1기준시점 Content-Type(요청) application/x-www-form-urlencoded Content-Type (응답) application/json; charset=UTF-8 요청 메세지 명세HTTP 항목명 항목설명 필수 타입(길이) 설명(비고) Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호 Body tx_id 트렌잭션 ID Y aNS(74) 마이데이터 사업자가 생성
‘MD’_‘마이데이터사업자 기관코드(10)’_‘정보제공자 기관코드(10)’_‘중계기관 기관코드(10)’_‘인증기관 기관코드(10)’_’통합인증 요청 시간/전자서명 요청 시간(YYYYMMDDHHMMSS)(14)‘_’일련번호(12)‘org_code 기관코드 Y aN(10) 통합인증을 수행할 정보제공자 코드
(종합포털에 기관 등록시 할당된 코드)grant_type 권한부여 방식 Y aN(8) 권한부여 방식
- 'password' 고정값client_id 클라이언트 ID Y aN(50) 종합포털에 마이데이터 서비스 등록 시 발급받은 클라이언트 식별값 client_secret 클라이언트 Secret Y aN(50) 종합포털에 마이데이터 서비스 등록 시 발급받은 클라이언트 Secret값(보안을 강화하기 위해 추가 확인하기 위한 코드) ca_code 통합인증기관 코드 Y aN(10) 통합인증수단을 발급한 통합인증기관 기관코드
(종합포털에 등록시 할당된 기관코드(org_code))username 고객 CI 정보 Y B64(100) 고객 CI 정보 request_type 전송요구 타입 Y aN(1) - 자산목록조회 전송요구(1차) : 0 (전송요구내역의 scope에 xxx.list만 존재하는 경우)
- 고객선택자산에 대한 세부 전송요구(2차) : 1password_len password 항목 길이 Y N(5) 전송요구내역 전자서명(signedData) 길이 password 전송요구내역 전자서명(signedConsent) Y aNS(10000) 전송요구내역 전자서명(CMS SignedData, Base64 url-safe 인코딩)
※ 항목명 password는 OAuth 표준 준용함auth_type 본인확인 이용 여부 Y aN(1) - 본인확인기관 이용 : 0
- 전자서명인증사업자 이용 : 1consent_type 전자서명 유형 Y aN(1) - 전송요구내역 원문에 서명 : 0(본인확인기관 기본값)
- 전송요구내역 해시값에 서명 : 1(전자서명인증 사업자 기본값)consent_len consent 항목 길이 N N(5) consent_type이 1인 경우에만 세팅
전송요구내역 원문의 길이consent 전송요구내역 Y AH(7000) consent_type이 1인 경우에만 세팅
전송요구내역 원문(UTF-8 인코딩)signed_person_info_req_len 본인확인 이용동의 전자서명 항목 길이(signedPersonInfoReq의 길이) N N(5) auth_type가 0인 경우에만 세팅
signed_person_info_req의 길이 적용signed_person_info_req 본인확인 이용동의 전자서명(signedPersonInfoReq) N aNS(10000) auth_type가 0인 경우에만 세팅
본인확인 이용동의 전자서명(CMS SignedData, Base64 url-safe 인코딩)
※ UCPID 가이드라인의 signedPersonInfoReqconsent_nonce 재전송공격 방지정보 1(consentNonce) N aNS(30) auth_type가 0인 경우에만 세팅
전송요구내역 전자서명(signedConsent)에 포함된 Nonce 값(Base64 url-safe 인코딩)ucpid_nonce 재전송공격 방지정보 2(ucpidNonce) N aNS(30) auth_type가 0인 경우에만 세팅
본인확인 이용 동의내역 전자서명(signedPersonInfoReq)에 포함된 Nonce 값(Base64 url-safe 인코딩)cert_tx_id 인증사업자 트랜잭션 아이디 N aNS(40) auth_type가 1인 경우에만 세팅
전자서명 요청 응답으로 받은 cert_tx_idservice_id 서비스번호 N AN(22) '금융분야 개인신용정보 전송요구 표준API규격'에 따른 기관 간 전송요구시에만 세팅
정보수신자가 종합포털에 서비스 등록 시 발급받은 서비스번호
- 기관코드(10자리) + 등록일자(8자리) + 순번(4자리)
- 예시) ORG00000001202105200001응답메세지 명세HTTP 항목명 항목설명 필수 타입(길이) 설명(비고) Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호 Body tx_id 인증 요청 번호 Y aNS(74) API 요청시 포함되어 있던 tx_id token_type 접근토큰 유형 Y aN(6) 접근토큰 유형
- 'Bearer' 고정값access_token 접근토큰 Y aNS(1500) 발급된 접근토큰 expires_in 접근토큰 유효기간 Y N(9) 접근토큰 유효기간(단위: 초) refresh_token 리프레시 토큰 Y aNS(1500) 접근토큰 갱신을 위한 토큰 refresh_token_expires_in 리프레시 토큰 유효기간 Y N(9) 리프레시 토큰 유효기간(단위: 초) scope 권한 범위 Y aNS(128) 접근토큰 권한 범위 (다중 scope 가능) -
접근토큰 발급 요청(통합인증기관 제공) v1 2023-01-12
기본 정보API ID 통합인증-101 HTTP Method POST API 제공자 인증기관 API 요청자 마이데이터사업자 API 명 (URI) /oauth/2.0/token 설명 각 인증기관이 사전에 발급한 통합인증 API용 자격증명을 이용하여 접근토큰 발급
- 중계기관을 이용하는 기관의 경우, 중계기관이 본 API를 호출하여 접근토큰을 대표로 발급 받음기준시점 현재 시점 Content-Type(요청) application/x-www-form-urlencoded Content-Type (응답) application/json; charset=UTF-8 요청 메세지 명세HTTP 항목명 항목설명 필수 타입(길이) 설명(비고) Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호 Body grant_type 권한부여 방식 Y aNS(18) 권한부여 방식
- 'client_credential' 고정값client_id 클라이언트 ID Y aN(50) 각 인증기관이 발급한 클라이언트 ID 값 client_secret 클라이언트 Secret Y aN(50) 각 인증기관이 발급한 클라이언트 Secret 값 scope 권한 범위 Y a(6) 고정값: 'ca' 응답메세지 명세HTTP 항목명 항목설명 필수 타입(길이) 설명(비고) Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호 Body token_type 접근토큰 유형 Y a(6) 접근토큰 유형
- 'Bearer' 고정값access_token 접근토큰 Y aNS(1500) 발급된 접근토큰 expires_in 접근토큰 유효기간 Y N(9) 접근토큰 유효기간(단위: 초) scope 권한 범위 Y a(6) 고정값: 'ca' -
전자서명 요청 v2 2023-01-12
기본 정보API ID 통합인증-102 HTTP Method POST API 제공자 인증기관 API 요청자 마이데이터사업자 API 명 (URI) /ca/sign_request 설명 마이데이터사업자가 인증기관에게 전송요구내역에 대한 전자서명을 요청 기준시점 현재 시점 Content-Type(요청) application/json; charset=UTF-8 Content-Type (응답) application/json; charset=UTF-8 요청 메세지 명세HTTP 항목명 항목설명 필수 타입(길이) 설명(비고) Header Authorization 접근토큰 Y aNS(1500) 통합인증기관이 발급한 접근토큰
- 접근토큰 유형(Bearer)을 명시
예) Authorization: Bearer 접근토큰x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호 Body sign_tx_id 서명 요청 트랜잭션 ID Y aNS(49) 마이데이터 사업자가 생성
'마이데이터사업자 기관코드(10)'_'인증기관 기관코드(10)'_'전자서명 요청 시간(YYYYMMDDHHMMSS)(14)'_'dlffusqjsgh(12)'user_ci 정보주체 식별값 Y B64(100) 정보주체 식별을 위한 연계정보 (Connection Information) real_name 정보주체 이름 N AH(30) 정보주체 식별을 위한 이름 phone_num 정보주체 휴대폰 번호 N aNS(15) 정보주체 식별을 위한 휴대폰 번호(E.164 표준 준용, 예시: '+821034959954') request_title 인증요청 제목 N AH(120) 인증요청 제목 / 인증앱에서 사용자에 노출 device_code 디바이스 코드 Y AN(2) - PC : PC권한부여 방식
- TB : Tablet
- MO : Mobile(기본값)device_browser 브라우져 Y AN(2) - WB : 웹브라우져
- NA : Native App(기본값)
- HY : Mobilereturn_app_scheme_url 마이데이터 서비스의 app scheme URL Y AH(1000) device_code가 'MO'이고, device_browser : 'NA' 또는 'HY'인 경우에만 세팅
인증앱에서 인증 완료 후 이동할 마이데이터 서비스 앱의 app scheme URL (화이트리스트로 관리 해야함)consent_type 전자서명 유형 Y aN(1) - 전송요구내역 원문에 서명 : 0
- 전송요구내역 해시값에 서명 : 1(기본값)consent_cnt 전송요구내역 개수 Y N(4) 전자서명을 요청하는 전송요구내역의 개수 consent_list 전송요구내역 목록 Y Object 순서를 보장해야 한다.
통합인증-103 API를 통한 전자서명 결과 조회시 본 순서와 동일한 순서로 결과 응답--consent_len consent 항목 길이 Y N(5) consent 항목 길이
consent_type이 0인 경우 : 전송요구내역 원문(UTF-8 인코딩)의 길이
consent)type이 1인 경우 : 전송요구내역 원문(UTF-8 인코딩)의 해시값(SHA-256)의 길이--consent_title 각 원문의 타이틀 N AH(120) 인증앱에서 각 전송요구에 대해 표시할 요약 정보 --consent 전송요구내역 Y N(Y) 전자서명 대상 원문
consent_type이 0인 경우 : 전송요구내역 원문(UTF-8 인코딩)
consent)type이 1인 경우 : 전송요구내역 원문(UTF-8 인코딩)의 해시값(SHA-256)
※ 전송요구내역 규격은 '인증서 본인확인 기반 통합인증 절차 및 규격'의 첨부[6] 준용--tx_id 전송요구내역 트렌잭션 ID Y aNS(74) 마이데이터 사업자가 생성
‘MD’_‘마이데이터사업자 기관코드(10)’_‘정보제공자 기관코드(10)’_‘중계기관 기관코드(10)’_‘인증기관 기관코드(10)’_’통합인증 요청 시간/전자서명 요청 시간(YYYYMMDDHHMMSS)(14)‘_’일련번호(12)‘
※ 전송요구내역 규격은 '인증서 본인확인 기반 통합인증 절차 및 규격'의 첨부[6] 준용응답메세지 명세HTTP 항목명 항목설명 필수 타입(길이) 설명(비고) Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호 Body rsp_code 세부 응답코드 Y aN(5) 표준API 규격 - [별첨1]-3 참조 rsp_msg 세부 응답메시지 Y AH(450) 표준API 규격 - [별첨1]-3 참조 sign_ios_app_scheme_url iOS 인증앱의 app scheme Y AH(1000) iOS 단말에서 마이데이터 서비스 앱이 호출할 인증앱 Custom Scheme Url sign_aos_app_scheme_url AOS 인증앱의 app scheme Y AH(1000) AOS(안드로이드) 단말에서 마이데이터 서비스 앱이 실행할 인증앱 Scheme Url(인증기관에 따라 intent 형태의 scheme Url로 제공 가능) sign_web_url 인증 웹의 url Y AH(1000) 마이데이터 서비스 앱에서 실행할 인증 웹 Url cert_tx_id 인증기관 트랜잭션 ID Y aNS(40) 전자서명 결과 조회시 사용할 트랜잭션ID -
전자서명 결과 조회 v2 2023-01-12
기본 정보API ID 통합인증-103 HTTP Method POST API 제공자 인증기관 API 요청자 마이데이터사업자 API 명 (URI) /ca/sign_result 설명 마이데이터사업자가 인증기관에게 전자서명 결과를 요청 기준시점 현재 시점 Content-Type(요청) application/json; charset=UTF-8 Content-Type (응답) application/json; charset=UTF-8 요청 메세지 명세HTTP 항목명 항목설명 필수 타입(길이) 설명(비고) Header Authorization 접근토큰 Y aNS(1500) 통합인증기관이 발급한 접근토큰
- 접근토큰 유형(Bearer)을 명시
예) Authorization: Bearer 접근토큰x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호 Body cert_tx_id 인증기관 트랜잭션 ID Y aNS(40) 전자서명 요청 응답으로 받은 cert_tx_id sign_tx_id 서명요청 트랜잭션 ID Y aNS(49) 전자서명 요청 시 사용했던 sign_tx_id 응답메세지 명세HTTP 항목명 항목설명 필수 타입(길이) 설명(비고) Header x-api-tran-id 거래고유번호 Y AN(25) 거래고유번호 Body rsp_code 세부 응답코드 Y aN(5) 표준API 규격 - [별첨1]-3 참조 rsp_msg 세부 응답메시지 Y AH(450) 표준API 규격 - [별첨1]-3 참조 signed_consent_cnt signed_consent 개수 Y N(4) 전자서명 결과의 개수 signed_consent_list 전송요구내역 목록 Y Object 순서를 보장해야 한다.
통합인증-103 API를 통한 전자서명 결과 조회시 본 순서와 동일한 순서로 결과 응답--signed_consent_len consent 항목 길이 Y N(5) 전자서명 결과의 길이 --signed_consent 전송요구내역 전자서명(SignedConsent) Y aNS(10000) 전송요구내역 전자서명(CMS SignedData, Base64 url-safe 인코딩 --tx_id 전송요구내역 트렌잭션 ID Y aNS(74) 마이데이터 사업자가 생성했던 tx_id
전자서명 위임 검증 시 사용
통합인증 API