[API] 금융결제원 오픈 API 활용하기
목차
1. 금융결제원 오픈뱅킹 API 요청 흐름
2. Callback URL 이란
나는 금융결제원이 제공하는 API 중 '오픈뱅킹 API' 를 활용하려 한다.
https://developers.kftc.or.kr/dev
금융결제원 오픈API 개발자사이트
TESTBED FOR DEVELOPERS 오픈 API를 이용하여 창의적인 어플리케이션을 제작해 보세요.
developers.kftc.or.kr
🐋 금융결제원 오픈뱅킹 API 요청 흐름 정리
: OAuth 2.0 Authorization Code Grant 방식으로 동작한다.
1) 클라이언트 → 금융결제원 인가 요청
내 서버( spring /api/auth/login) → 금융결제원의 인가 앤드포인트 (https://testapi.openbanking.or.kr/oauth/2.0/authorize)로 리다이렉트 시킴.
이때 요청 파라미터에 여러 정보를 담고 요청을 하게된다.
client_id : 내 앱을 구분하는 ID
redirect_uri : 인증이 끝난 뒤, 금융결제원이 결과(code, state)를 돌려줄 주소
scope : 어떤 권한을 요청하는지 (login inquiry transfer 등)
*
login
: 사용자 본인확인 후 서비스에 연결(동의) 받는 권한
완료 시 "사용자가 동의한 연결"이 생성되고, 코드- 토큰 발급이 가능해진다.
최초 연결(auth_type=0) 일 때 필수!
inquiry
: 조회 권한
연결된 계좌의 목록, 잔액, 거래내역 등을 읽을 수 있게 해준다.
transfer
: 이체 권한
사용자의 동의 범위 내에서 오픈뱅킹의 출금이체 API를 호출해서
실제송금을 수행할 수 있다.
state : CSRF 방지 토큰
response_type = code : Authorization Code 발급 요청
/api/auth/login
1. 서버에서 state 난수 생성 -> 세션 저장
2. 금융 결제원의 인가 URL 로 리다이렉트
3. 쿼리 파라미터로 붙여준다
/api/auth/callback
1. 금융결제원의 인증 후 code와 state를 callback URL로 되돌려줌
2. 세션에 저장해둔 state와 일치하는지 확인하도록 해줌.
일치 -> 토큰 발급 단계 진행
불일치 -> 403 에러
2) 금융결제원 → 사용자 인증 페이지 표시
사용자는 휴대폰 본인인증 + 은행 선택 + 계좌 연결을 진행.
이 부분에서 금융결제원의 권한 승인이 필요함. (이메일로 요청 후 승인 받을 수 있다.)
성공하면, 금융결제원이 Authorization Code를 발급해서 redirect 시킴.
3) 금융결제원 → Callback URL 로 리다이렉트
금융결제원은 내가 요청할 때 넣었던 redirect_uri로 이동시키면서,
URL에 다음 파라미터를 붙여서 보낸다.
* redirect_uri : 인증이 끝난 뒤, 금융결제원이 결과(code, state)를 돌려줄 주소
http://localhost:8080/api/auth/callback?code=XXXXXX&state=YYYYYY
여기서 code는 1회용 토큰으로, 액세스 토큰(Access Token) 교환에 사용된다.
state는 요청할 때 보낸 값과 일치해야한다. → CSRF 방지 위해!
Q. state가 CSRF를 어떻게 막아주나?
만약 state가 없는 경우
공격자가 사용자의 브라우저를 금융결제원 인가 URL로 몰아 보낸 뒤,
자신이 의도한 세션/파라미터로 내 콜백을 때리도록 하면,
내 서버는 누가 시작했는지 구분을 하지 못하고 code를 받아 토큰을 교환하게 된다.
이 경우, 세션주입 or 인가 응답 바꿔치기 위험이 존재한다..
🌱state 를 사용하는 이유
내 서버는 state를 생성한다 ( 32자리 난수) 그리고 서버측 세션에 저장한다.
인가 요청에도 같은 state를 포함시켜 금융결제원으로 보낸다.
금융결제원이 인증완료하면 이 state를 그대로 callback에 실어서 내 서버로 돌려준다.
callback에서 세션에 저장해둔 값과 일치하는지 비교한다.
같으면 - 내가 시작한 요청의 응답! 안전하다!! = 토큰 교환 진행
다르거나 없는 경우 - 이거 위조다. 가로챘다. = 즉시 거절 ^^
즉 state라는 서버가 사전에 발급해둔 '고유 토큰'을 맞춰오지 못하면 인증을 못하게 됨.
→ 교차 사이트에서 임의로 온 인가 응답 차단 가능 = CSRF 방지
4) 내 서버 → 금융결제원 토큰 교환 요청
/api/auth/callback 컨트롤러에서 받은 code를 가지고,
금융결제원의 토큰 발급 API(POST /oauth/2.0/token)에 다음과 같이 요청한다.
client_id ,
cilent_secret
code
redirect_uri
grant_type=authorization_code
성공 시 access_token과 refresh_token을 받는다!
5) 내 서버 → 오픈뱅킹 API 호출
받은 access_token을 Authorization 헤더(Bearer)에 넣어서,
계좌 목록 조회나 거래내역 조회 API를 호출하여 사용하는 원리이다!
🐋 Callback URL 란?
: 금융결제원이 인증 절차를 끝낸 후, 인증 결과를 전달하기 위해 사용자 브라우저를 리다이렉트하는 네 서버의 엔드포인트 주소.
한마디로, 금융결제원 인증센터에서 "오키. 인증 끝났으니까 결과를 너가 적어둔 주소로 돌려줄게~ " 에서의 '적어둔 주소'
그리고 내 서버는 이 곳에서 code를 받아,
다시 금융결제원에게 진짜로 API를 쓸 수 있는 열쇠인 "Access Token"을 받아오는 것!
* callback URL 의 권장 혹은 필수사항
1) 보안 상 이유로 금융결제원 개발자 포털에 사전 등록해야한다.
2) 또, 요청할 때 넣은 redirect_uri 와 등록된 값이 일치해야한다.
3) 개발환경에서는 상관없지만, 운영 환경에서는 HTTPS 환경을 권장.