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

본문

표준 API 기본 규격

1. 공통

1.1 API 관련 기술 표준

표준 연결 방식

HTTP을 기반으로 참여기관 간 안전한 통신을 위해 TLS기반 상호인증(이하 mTLS)을 전송 구간 암호화에 적용한다.

mTLS (Mutual Transport Layer Security)
전송(Transport) 계층과 응용(Application) 계층 사이에서 종단 간 인증, 전송 데이터의 암호화, 무결성을 보장하는 표준 프로토콜
API를 호출하는 클라이언트와 API 제공자 간 양방향 인증으로 신뢰성 있는 통신을 지원
SSL/TLS 인증서 적용

참여기관 간 상호인증, 암호화된 정보의 송·수신을 위해 인증기관(CA, Certificate Authority)으로부터 OV등급 또는 EV등급 SSL/TLS 인증서를 발급받아 적용한다.

OV(Organization Validated) 등급 TLS 인증서
인증기관(CA)이 도메인 소유권과 조직의 실재 여부를 검증한 뒤 발급되는 인증서
와일드카드 도메인에 대한 인증서 발급이 가능 (예시: *.domain.com)
EV(Extended Validation) 등급 TLS 인증서
도메인 소유권과 조직의 실재 여부, 법적 존재 및 운영 여부를 인증기관(CA)이 검증 후 발급하는 인증서
특정 단일 도메인에 대한 인증서 발급 가능 (예시: mydata.domain.com)
인증서 시리얼 번호에 사업자 번호 혹은 법인 번호를 명시하여 발급 가능
SSL/TLS 인증서 정보 배포

CA 인증서 및 참여기관별 인증서 정보는 마이데이터 플랫폼에서 제공하는 전송지원 API를 통해 수신할 수 있다.

TLS인증서 갱신 순서
마이데이터 플랫폼에서는 인증서 지문 정보를 기관당 최대 세개 까지 등록
갱신 시 폐기된 인증서 지문 정보를 삭제하고 갱신된 인증서 정보 등록
각 참여기관은 기관정보 조회 API(전송지원-002)를 통해 매일 인증서 지문 정보를 갱신
  • 1. [만료일 30일 전] 갱신된 TLS인증서 다운로드
  • 2. [만료일 30일 전~10일 전] 마이데이터 플랫폼에 갱신된 TLS인증서 지문 정보 등록
  • 3. [만료일 7일 전~만료일] 시스템에 실제 TLS 인증서 교체 작업 수행
  • 4. [교체작업 이후] 갱신된 인증서로 통신 가능
SSL/TLS 인증서 검증

mTLS를 이용하는 API 호출 시 API제공자는 마이데이터 플랫폼에 등록된 인증서 지문 정보와 API 요청자로부터 전달받은 인증서의 지문 정보가 동일한지 확인한다.

인증서 지문 정보 예시
인증서 지문 정보 예시

[인증서 지문 정보 예]

데이터 표현 형식

API 요청·응답 메시지 형식은 JSON을 사용하며, 분야별·산업별로 사용하는 표현방식을 적용한 경우는 예외로 한다.

JSON(JavaScript Object Notation)
속성·값(Key:Value)의 집합으로 이루어진 데이터 객체를 표현하기 위한 개방형 표준 메시지 형식
국제표준(ECMA-404)로 채택되어 있으며, 웹서비스에서의 사실상 표준 데이터 형식으로 사용됨
데이터 인코딩

메시지 전송을 위한 인코딩 방식는 UTF-8을 사용한다.

UTF-8
ASCII 코드를 확장하여 전 세계의 모든 문자코드를 표현할 수 있는 표준인코딩 방식으로써 범용성이 높아 호환성이 우수
웹 서비스 표준으로 ASCII와 호환되어 다양한 시스템에서 지원
데이터 길이

API규격 내 항목별 길이는 UTF-8 인코딩 시 byte 수를 의미하며, 그 외 특수문자는 유니코드 문자 테이블을 참고한다.

Character Bytes
0~9 1
A~Z 1
a-z 1
한글 3
? 1
/ 1
~ 1
Character Bytes
= 1
! 1
- 1
$ 1
% 1
^ 1
¢ 2
시지 길이 계산 예시 : “마이데이터A-1“의 UTF-8 byte 길이
(‘마이데이터’ 각 3byte(한글) 총 15 bytes) + ('A' 1byte) + ('-' 1byte) + ('1' 1byte) = 총 18 bytes
명명 규칙

URI, 파라미터, JSON 메시지 속성(key) 명명법으로 스네이크 케이스 표기법을 사용한다.

스네이크 케이스(Snake Case) 표기법
모든 문자를 소문자로 표기하고 단어들 사이는 _(언더바)로 연결 (예시 : snake_case, is_active_member)
대소문자를 구분하지 않는 시스템에서도 일관되게 사용 가능
단, OAuth 2.0과 같이 별도 표준에서 정의한 URI나 파라미터 명명 규칙이 존재하는 경우는 해당 표준을 따름
통화 코드

ISO4217 표준을 사용한다.

ISO4217 표준 규격
국제표준화 기구(ISO)에서 제정한 통화 코드로 세 글자 알파벳으로 구성됨(예시 : 한국원화 KRW, 미국달러 USD)

메시지 교환 방식

API 요청·응답 교환방식은 REST를 사용한다.

REST(REpresentational State Transfer)
HTTP 기반으로 데이터를 전달하는 프레임워크로써, URI로 정보의 자원을 표현하고 자원에 대한 행위를 HTTP 메소드(GET, POST 등)로 표현
NULL값 처리

NULL은 값이 존재하지 않음을 의미하는 표현이나, API 요청·응답 시에는 어떠한 경우라도 NULL의 사용을 금한다.

URI 계층 구조

분야별 정보 전송 대상 정보를 고유하게 식별하고, 위치를 표현할 수 있도록 URI를 설계한다.

분류 URI 계층 구조
정보요청 API <base path> / <version> / <industry> / <resource>
전송지원 API <base path> / <version> / <resource>
전송요구 API <base path> / oauth / 2.0 / [authorize | token | revoke]
HTTP 헤더

HTTP 헤더 정보 표기는 다음을 따라 정의한다.

application/x-www-form-urlencoded
HTML 폼 데이터를 서버에 전송할 때 주로 사용하는 Content-type으로써 GET, POST 메소드 둘다 사용 가능하며 OAuth 2.0 표준에서 사용
※ 문자 인코딩 방식은 UTF-8이므로 application/x-www-from-urlencoded; charset=utf-8 또한 허용
application/json
웹에서 JSON 데이터를 전송할 때 사용되며 HTTP 요청 본문에만 포함되는게 일반적이므로 POST 메소드에서만 주로 사용
※ 국제 표준(RFC 8259)에 따라 JSON의 경우 Contnent-type이 반드시 UTF-8이나 명시적으로 Content-type을 표기하는 application/json; charset=utf-8 또한 허용
참여기관 정보

API 요청자와 API 응답자를 구분하여 헤더에 표기한다.

처리고유번호
  • API를 송·수신한 기관 간 처리내역 추적을 위해 API 요청과 응답 시 처리고유번호를 생성하여 'X-Api-Tx-Id'에 설정하여 송·수신한다.
  • 참여기관은 API 호출 시 시계열성 확보 및 유일성을 보장하기 위해 UUID v7 표준을 따라 생성한 값을 설정
UUID v7 (Universally Unique Identifier Version 7)
시간 기반(타임스탬프 기반)으로 고유한 식별자를 생성하는 방식
시계열 값의 이점인 삽입 정렬, 데이터베이스 인덱싱에서 유리
동일한 시간에 생성된 UUID도 고유성 보장
UUID생성 시 MAC주소나 서버이름과 같은 식별정보를 포함하지 않아 보안성 우수
IETF에 의해 지정된 표준으로 RFC 9562에 명세(예시 : 018f8401-55ac-7ba4-b3f6-45ca5fa453e4)
응답 코드 및 메시지

표준 HTTP 응답 코드만으로 다양한 상태를 표현하는데 한계가 있으므로, 상황별 세부 응답 코드 및 메시지를 별도로 정의하여 사용한다.

페이지네이션

이력정보 등 한 번의 응답으로 전송이 불가능한 경우는 부분 범위 조회 기법(Cursor-Based Pagnination)을 적용하여, 응답 메시지 당 전송하는 데이터 크기를 조절하여 응답할 수 있다.

Cursor-Based Pagination
대량의 데이터를 페이지라는 단위로 나누어 처리하는 방식으로 페이지를 탐색하여 효율적인 메시지 반환이 가능
웹 서비스와 모바일 어플리케이션에서 데이터를 동적으로 로드하거나 표시할 때 주로 사용
[부분범위 조회 요청/응답 파라미터 규격]
구분 이름 타입 (길이) 설명
요청 limit String(3) 목록 내 반환될 객체의 개수
(최대 500까지 설정 가능)
next_page String(1000) 다음 페이지 요청을 위한 기준객체
(설정 시 해당 객체를 포함한 limit 개 반환)
응답 next_page String(1000) 다음 페이지 요청을 위한 기준객체
(다음 페이지 존재하지 않는 경우 미회신)
기준객체 식별자의 생성규칙은 정보전송자가 자율적으로 정함. 다만, 특수문자를 포함하여 기준객체 식별자를 생성하는 정보전송자의 경우 URL safe한 방식 (URL encoding, URL Safe BASE64 등)을 적용하여 생성 및 응답

단, limit을 최대 500까지 설정하더라도 정보전송자의 환경에 따라 페이지 당 반환되는 객체의 개수는 변경가능 (0 ≤ 반환되는 객체 개수 ≤ limit)

2. 전송요구 적용 기술·보안 표준

정보주체가 자신의 정보를 전송요구하는 경우, 마이데이터 서비스를 통해 자신이 정보주체임을 입증하고, 정보접근 권한을 발급받는 인증과 인가 절차를 거쳐야 한다.

2.1. 인증(authentication)

OAuth 2.0

정보주체의 개인정보 전송요구에 따른 업권별 정보요청 API 호출(정보주체의 개인정보 전송요구)을 위한 인가‧인증 또는 전송지원 API 호출/제공을 위한 인증 절차는 표준 규격인 OAuth 2.0을 준용한다.

OAuth 2.0 (Open Authorization 2.0)
사용자가 제 3자인 다른 웹 및 어플리케이션을 안전하게 인증하고 권한을 부여할 수 있도록 하는 개방형 표준 인증 프로토콜
웹 및 모바일 서비스에서 가장 많이 사용되는 인증 프로토콜로, IETF에서 표준으로 공식화하여 채택
영국, EU의 Openbanking, paypal, 금융결제원의 Openbanking에서 채택하여 인증 규격으로 사용
IETF RFC 6749 (The OAuth 2.0 Authorization Framework)
OAuth 2.0 프로토콜의 공식적인 명세서로 설계, 기능 및 동작에 대한 상세내용을 제공
본 명세서에서의 인증 프로토콜로 OAuth 2.0을 사용하면서 인증 기능과 동작은 해당 RFC 문서를 참고로 함
IETF RFC 7009 (OAuth 2.0 Token Revocation)
OAuth 2.0 프로토콜의 접근 토큰 및 리프레시 토큰의 취소 및 무효화 프로세스 내용 제공
본 명세서의 인증 프로토콜 중 토큰 revocation에 대한 명세는 해당 RFC문서를 참고함

공동인증서를 이용한 전자서명·검증의 경우 KISA의 「공동인증서를 이용한 본인확인 서비스 가이드라인」, X.509 v3 및 CMS등 표준규격을 준용한다.

인증서

디지털 인증서의 형식을 정의하는 규격은 X.509를 표준으로 따른다.

2.1.1.1. 사전 절차
참여기관 절차 상세 비고
공통 인증절차와 관련된 참여기관 간 통신은 표준 API는 mTLS, 인증기관과의 통신은 각 기관에서 정한 방식 적용
인증기관
  • - 마이데이터 플랫폼에 기관정보 등록(IP주소 및 포트, 인증기관 식별값, 허용 인증서 종류 식별값 등)
  • - 마이데이터 플랫폼으로부터 정보수신자, 정보전송자, 중계 전문기관 정보를 조회 후 저장하는 기능 개발
정보수신자
  • - 전자서명 모듈 설치
  • - 서비스 내 전자서명 생성 및 본인확인 동의 메시지 생성 기능 개발
  • - 마이데이터 플랫폼으로부터 인증기관 정보를 조회 후 저장하는 기능 개발
 tx_id를 생성하여 전송요구 API호출 시 설정
중계 전문기관
  • - 인증서 폐기 목록(CRL) 확인가능한 인증서 검증 모듈 설치
  • - 전자서명 검증 및 본인확인(UCPID) 모듈 설치
  • - 마이데이터 플랫폼으로부터 정보수신자, 정보전송자, 중계 전문기관 정보를 조회 후 저장하는 기능 개발
2.1.1.2. 전자서명 및 서명검증 상세
공동인증서 기반 인증 시퀀스 다이어그램
공동인증서 기반 인증 시퀀스 다이어그램

[위 그림에서 마이데이터 서비스와 정보수신자 서버는 유사한 컬러로 수정하여 같은 기관임을 표현]

정보주체

전송요구서 및 본인확인 동의서 확인을 수행한다.

정보수신자

정보수신자 서버는 「표준 API 규격 및 명세」의 ‘정보요청용 접근토큰 발급(인증서 본인확인 기관) API(전송요구-002)’에 포함되는 Nonce값＊을 생성하여 마이데이터 서비스에 전송한다.
＊전송요구서의 재전송 방지를 위한 consentNonce와 본인확인 서비스 이용에 사용되는 ucpidNonce를 생성하여 전송

정보수신자

전송요구서 및 본인확인 이용 동의서에 대해 정보주체가 전자서명할 수 있도록 인증기관에서 제공하는 전자서명 생성 모듈을 호출한다.

정보수신자

전자서명값과 Nonce 값을 이용하여 선택된 각 정보전송자들에 대해서 「표준 API 규격 및 명세」의 '정보요청용 접근토큰 발급(인증서 본인확인 기관) API(전송요구-002)'를 병렬적으로 호출한다.

중계 시스템

전자서명 검증모듈을 통해 전자서명 검증 및 허용된 인증서 서명 여부 등을 확인한다.

중계 시스템

정보주체의 정보전송자 회원가입여부를 재확인한다.

중계 시스템

인증기관에서 제공하는 본인확인 요청 모듈을 이용하여 정보주체 본인 확인을 수행한다.

2.1.2.1. 사전 절차
참여기관 절차 상세 비고
공통 인증기관과 연결이 필요한 기관은 인증기관이 정하는 절차에 따라 연계 준비
  • - 기관 정보 등록
  • - 자격증명 발급 신청 (클라이언트ID, 클라이언트 시크릿, 마스터 시크릿)
  • - 인증기관 제공 API 호출을 위한 접근토큰 발급 요청 개발
 「간편인증 인터페이스 가이드라인」 참조
정보수신자
  • - 마이데이터 플랫폼에 기관정보 등록(IP주소 및 포트, 인증기관 식별값, 허용 인증서 종류 식별값 등)
  • - 마이데이터 플랫폼으로부터 정보수신자, 정보전송자, 중계 전문기관 정보를 조회 후 저장하는 기능 개발
정보수신자 전자서명 생성 요청 및 전자서명 결과 조회 API 연동 개발 간편인증-002, 간편인증-003 API 연계 개발
중계 전문기관 전자서명 위임 검증 API 연동 개발 간편인증-004 API 연계 개발
2.1.2.2. 전자서명 및 서명검증 상세
간편인증서 기반 인증 시퀀스 다이어그램
간편인증서 기반 인증 시퀀스 다이어그램
정보주체

대상 정보전송자와 전송요구서 내용을 확인한다.

마이데이터 서비스

전송요구내역과 고객정보를 정보수신자 서버에 전달한다.

정보수신자 서버

전송요구내역의 해시값, 고객 디바이스 정보, 전자서명 완료 후 전환될 마이데이터 서비스 앱의 URL을 요청 메시지에 포함하여 간편인증기관에 전자서명 생성을 요청한다.

간편인증기관

간편인증기관은 정보수신자가 전달한 디바이스 형태에 맞게 간편인증 앱 호출 Scheme＊을 회신한다.
＊정보주체의 디바이스 타입, 디바이스 OS, 디바이스 브라우저 launcher 정보를 확인해 기기에 적합한 형태로 간편인증 앱 호출 Scheme을 제공

간편인증앱

정보수신자는 전달받은 앱 URL을 이용하여 간편인증 앱을 호출하고 정보주체는 인증앱을 통해 전자서명 생성을 위한 인증정보 입력한다.

정보수신자 서버

정보수신자는 간편인증기관에 「표준 API 규격 및 명세」의 ‘전자서명 생성 결과 요청 API(간편인증-003)’를 요청한다.

정보수신자 서버

정보수신자 서버는 마이데이터 서비스를 통해 전달받은 전자서명 값과 고객정보를 기반으로 중계시스템에 「표준 API 규격 및 명세」의 '정보요청용 접근토큰 발급(간편인증기관) API(전송요구-003)'를 호출하여 접근토큰 발급을 요청한다.

중계 시스템

정보주체의 정보전송자 회원가입여부를 확인한다.

중계 시스템

정보수신자가 전달한 전자서명 값을 이용해 인증기관에 「표준 API 규격 및 명세」의 '전자서명 검증 및 서명자 확인요청 API(간편인증-004)'를 요청한다.

개발식별자 기반 인증 시퀀스 다이어그램
개발식별자 기반 인증 시퀀스 다이어그램
OpenID Connect
OAuth 2.0의 개념을 확장하여 사용자의 인증 및 정보를 처리하는 방법 정의
OpenID Foundation에서 정의한 개방형 인증표준으로, IDP 공급자의 기존 사용자 정보를 재사용하여 클라이언트 어플리케이션에서 로그인 할 수 있도록 지원
Microsoft, Paypal, EU의 Openbanking에서 채택하여 사용자 인증 규격으로 사용
본 명세서에서의 개별인증 과정에서 사용자 정보 취득과정은 OpenID Connect를 사용하면서 인증 기능과 동작은 해당 문서를 참고로 함
정보주체

개별식별자 기반 정보전송자를 선택한다.

정보수신자

정보주체 개별인증수단 인증을 위한 인증 화면과 「표준 API 규격 및 명세」의 '개별인증 인가코드 발급 요청 API(전송요구-004)'를 요청한다.

정보주체

정보주체 개별인증수단 인증 화면과 추가 인증 정보 입력 화면을 통해 본인인증과 추가인증을 수행한다.

정보전송자

정보주체 인증이 성공하면 정보수신자에게 인가코드를 발급하여 Redirect URI로 이동할 수 있도록 응답하고, 전달받았던 CI해시값과 nonce값을 인가 코드와 함께 임시 보관한다.

정보수신자

인가코드를 이용하여 「표준 API 규격 및 명세」의 '개별인증 ID토큰 발급 요청 API(전송요구-005)'를 요청한다.

정보전송자

인가코드를 검증한 뒤 정보주체 식별자로서 ID토큰을 발급하여 정보수신자에게 전달한다.

ID토큰 서명
(서명키 공유) 정보전송자는 별도 배포된 중계 시스템 연동 가이드에 기술된 API로 서명에 사용한 비밀키와 짝을 이후는 공개키 정보 공유 ※ ID토큰 헤더내 kid값을 공개키 식별자로 사용
(서명 생성) 정보선송자는 로그인 성공 후 ID토큰 발급 시 비밀키로 JWS 서명을 생성하고 ID토큰 내에 서명검증을 위한 공개키 kid를 헤더에 포함
(서명 검증) 중계 시스템은 ID토큰 내에 kid 값에 해당되는 공개키를 정보전송자로부터 수신하여 JWS 서명을 검증하고, 해당 정보전송자가 생성하고 변조되지 않은 ID토큰임을 확인한다.

ID토큰의 유효기간은 전송요구 최대 유효기간인 1년에 맞추어 발급

정보수신자

정보수신자는 전자서명된 전송요구서와 정보전송자로부터 발급받은 ID토큰을 중계 시스템에 같이 전달하여 「표준 API 규격 및 명세」의 '접근토큰 발급 요청 API(전송요구-002∙003)'를 호출한다.

중계전문기관

중계 시스템은 ID토큰의 서명을 검증하고, 본인확인 또는 전자서명 검증 시 인증기관으로부터 획득한 CI를 정보수신자와 동일한 방식으로 CI해시값을 만들어 ID토큰 내부의 CI해시값과 일치하는지 확인 후 정보수신자에게 접근토큰을 발급한다.

2.2. 인가(authorization)

전송요구를 통한 정보요청 또는 전송요구와 관련한 전송지원 API 등의 정보 접근 권한을 부여한 증표로서 접근토큰을 발행하는 과정이다.