오픈API

IBK인증 (3-legged)

IBK인증 (3-legged)

  • 오픈API 포털에서 제공하는 잔액조회, 거래내역조회, 카드 승인내역 조회 등의 사용자 금융정보 조회 서비스 개발이 필요한 이용기관은 사용자 본인확인 및
    사용자 동의절차 등 사용자 인증 후 관련 API서비스를 제공해야 합니다.
  • 사용자 인증 방식은 IBK인증과, 자체인증으로 나뉩니다.

IBK인증 (3-legged)이란?

IBK인증(3-Iegged)은 Oauth 2.0의 Authorization Code Grant 절차를 준용한 인증절차입니다.
IBK가 제공하는 오픈API를 사용하기 위해서는 인증 토큰(Access Token)이 필요합니다.

IBK인증 이용절차

IBK인증 이용기관은 IBK에서 제공하는 웹뷰(WebView)를 통해 사용자의 본인확인 및 동의 절차를 진행합니다. 이 과정에서 휴대폰 본인확인과 전자서명과 같은
IBK의 인증수단을 사용하여 사용자 인증을 완료해야 합니다.

사용자가 IBK인증을 통해 정상적으로 인증(본인인증 및 계좌/카드 등록)을 완료하면, IBK는 이용기관에게 Authorization Code를 전달하고,
이용기관은 이 Authorization Code를 사용하여 IBK 서버로부터 Access Token과 Refresh Token을 발급 받습니다.

발급된 Access Token은 이용기관이 IBK API를 호출할 때 사용자(고객)의 인증을 확인하고, 해당 사용자(고객)의 거래를 안전하게 처리하기 위해 사용됩니다.

IBK인증 이용절차 설명 아래참고

1. 사용자 인증 (Authorization Code 발급) : IBK인증 Webview 요청

이용기관 서비스 앱에서 IBK인증을 요청하면 Webview를 통해 사용자가 인증 단계를 진행 후 이용기관 서비스를 이용할 수 있습니다.

Request

토큰(Access Token) 발급 Request(HTTP URL, HTTP Method, Content-Type) 표
HTTP URL https://devapiportal.ibk.co.kr:9443/ibk/biz/oauth/application/webview/authorize
HTTP Method GET
Content-Type application/x-www-form-urlencoded
사용자 인증(Authorization Code 발급) Request(항목, 값, 필수, 설명) 표
항 목 값 필 수 설 명
response_type 고정값 : code Y OAuth 2.0의 Code 방식
redirect_uri API 포털에서 APP 생성 시 Redirect_URL 정보
- Authorization Code 및 사용자 일련번호를 전달받을 URI 		Y 사용자 인증이 성공하면 이용기관으로 연결되는 URL
client_id 이용기관 Client_ID Y 이용기관 APP KEY 정보
scope 1: login(로그인)
2: inquiry(조회)
3: transfer(이체)
4: mask_inquiry(마스킹 조회) 		Y OAuth 2.0 Scope 정의
- Access Token 권한 범위(다중 scope 가능)
oap_cus_dcd 1: 개인, 2: 법인, 3: 중소개인 Y 사용자(고객) 구분코드
view_gubn 1: 최초동의, 2: 재동의, 3 : 철회
- 최초동의 : 최초 동의 필요한 경우
- 재동의 : 동의 기간만료 혹은 계좌/카드 동의 추가 시
- 철회 : 일부 계좌/카드 동의 철회 또는 전체 절회시		 Y 동의여부 구분코드 
### IBK인증 Webview 요청

curl -X GET \
https://devapiportal.ibk.co.kr:9443/ibk/biz/oauth/application/webview/authorize?response_type=code&redirect_uri={{이용기관 Redirect_URL}}&client_id={{이용기관 Client_ID}}&scope=login inquiry&oap_cus_dcd=1&view_gubn=1 \
 -H 'Content-Type: application/x-www-form-urlencoded'

Response

사용자 인증(Authorization Code 발급) Response(HTTP URL, HTTP Method) 표
HTTP URL https://{{이용기관 Redirect_URL}}
HTTP Method GET
Content-Type application/x-www-form-urlencoded
사용자 인증(Authorization Code 발급) Response(항목, 설명) 표
항 목 설 명
이용기관 Redirect_URL Authorization Code 수신할 이용기관 서비스 URL 정보
code Authorization Code 정보(465 byte)
oapiUserSrn 고객에 대한 사용자 일련번호
- 사용자 일련번호는 IBK의 모든 API 거래 유일한 고객의 KEY로 사용됨 
### Authorization Code 수신

http://{{이용기관 Redirect_URL}}?code=AAIh4oCeF9sZ87sXqAFNWuGecfmob498FPxN3iOqTOG3JHYmwXGKjUemRYYOXBBsrNmnB7JtoA8LByrvP5-KzTyRinM10jitNmh7AvqHyFcvOROry93qzS1iTN7FLI-TA8tDM1hu9mzAzz5pVKtY5_EK_xqdFBD_Y_DUN02aqGP7chBSd24JwpWOTQWQ0fdQLRBBPgsYXx94Xq3KJIciNlnaT1EX9eqzCMXhVbVPzbMnkA&encpCusCiIdntNo=ykffG5BsnToZpkL2iDfWiSAu0YRbeNfpdRWDWsCmVQpXnViabqGGTnHt8vnhvCe2yonjuabcHOcSAQ3XD%2Bld%2BA==&oapiUserSrn=11886540

사용자가 정상적으로 인증을 완료하면 IBK는 해당 사용자에 대한 Authorization Code를 이용기관에 전달합니다.
Authorization Code는 짧은 수명만 가지며, Access Token을 발급받기 위한 임시 코드입니다.

2. Access Token, Refresh Token 최초 발급/폐기/재발급

2-1. 토큰 최초 발급

이용기관은 IBK인증 요청 시, IBK로부터 받은 Authorization Code를 이용해 토큰(Access Token, Refresh Token)을 발급합니다.

Access Token: IBK API 호출 시 사용자(고객)를 인증하기 위한 짧은 수명의 토큰(유효기간 90일)
Refresh Token: Access Token이 만료된 경우 새로운 Access Token을 발급받기 위한 장기 수명의 토큰(유효기간 1년)

Request

토큰 최초 발급 Request(HTTP URL, HTTP Method, Content-Type) 표
HTTP URL https://devapiportal.ibk.co.kr:9443/ibk/biz/oauth/application/threeLeggedToken
HTTP Method POST
Content-Type application/x-www-form-urlencoded
토큰 최초 발급 Request(항목, 값, 필수, 설명) 표
항 목 값 필 수 설 명
Authorization: Basic 고정값 : OAuth 2.0 Basic Y Client_ID : IBK에서 발급한 이용기관 앱의 Client ID
Clent_Secret : IBK에서 발급한 이용기관 앱의 Client Secret
grant_type 고정값 : authorization_code Y OAuth 2.0 Token 방식 정의
code Authorization code Y IBK인증 후 수신된 Authorization code 값 
### 토큰(Accsess Token, Refresh Token) 발급

curl -X POST \
https://devapiportal.ibk.co.kr:9443/ibk/biz/oauth/application/threeLeggedToken \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic {{이용기관 Client_ID}}:{{이용기관 Client_Secret}}' \
-d 'grant_type=authorization_code&code={{인가코드}}'

Response

토큰 최초 발급 Response(항목, 설명) 표
항 목 설 명
token_type Access Token 유형
- 고정값 : Bearer
access_token IBK에서 발행한 사용자의 Access Token 값(670 Byte)
scope Access Token 권한 범위
expires_in Access Token 유효기간(초)
- 고정값 : 7776000 (90일)
consented_on Access Token과 Refresh Token 유효기간
- UNIX 시간 기준
refresh_token Refresh Token 값(670 Byte)
refresh_token_expires_in Refresh Token 유효기간(초)
- 58359660초 (1년)
metadata 사용자 일련번호 
### 토큰(Accsess Token, Refresh Token) 수신

"token_type": "Bearer",
"access_token": "AAIgZjM3ZGM0N2M1Zjk5Y2RjZDBiYWNhMzZlYmViOWU3NWG0rSQU6hJx_Nk6cT6NRGqxVhwHA6XlFPx-E383J634_oRHJwrBLh5veulnv9GeTH3t_Et5LLZrUpgrJVx3hO2oTGLd58elToLINdtKlnKxgepTJSaE4yiiSAKXTLgwEizlWWS4ayHubdyB4jgePleXNLAsnHKhji3Z4a8_m-1lGzqKBN9OR0IzWHbVb7RijcY",
"scope": "login",
"expires_in": 7776000,
"consented_on": 1625636276,
"refresh_token": "AAJ3RruKtKjMeHER4jbWw8nhD6nvkbqEaWoLq7M_hrNvfTOb5Wnfu4FgUSrbhc1L0Dn5arGArOtYw66APvO-bW4j0cq2B2yqQbPCXn5pOZWuyFUpx3lbMt4Q-S2cTXM3978AGjzWj6PeuEfCFhu6TcbjOYkTU5hU1K3xkf-cI4dhbK3FXcjU9AYgrhn3pVcU-npuimOCZC2NtOn4UmggIXvp",
"refresh_token_expires_in": 58359660,
"metadata": "a:6737110"

이용기관은 최초발급을 통해 응답받은Access Token 및 사용자 일련번호를 사용하여 IBK API를 정상 이용할 수 있습니다.

2-2. 토큰 폐기

발급받은 토큰(Access Token)을 유효기간이 만료되기 전에 폐기하고자 하는 경우 사용하는 API입니다.
사용자 토큰발급 API를 통한 토큰 폐기 시에는 갱신(Refresh) 토큰은 유지되며, 갱신 토큰으로 토큰 재발급이 가능합니다.

Request

토큰 폐기 Request(HTTP URL, HTTP Method, Content-Type) 표
HTTP URL https://devapiportal.ibk.co.kr:9443/ibk/biz/oauth/threeLeggedRevoke
HTTP Method POST
Content-Type application/x-www-form-urlencoded
토큰 폐기 Request(항목, 값, 필수, 설명) 표
항 목 값 필 수 설 명
client_id <Client_ID> 주1) Y IBK에서 발급한 이용기관 앱의 Client ID
client_secret <Client_Secret> 주1) Y IBK에서 발급한 이용기관 앱의 Client Secret
token_type_hint 고정값 : access_token Y OAuth 2.0 Token 방식 정의
token Access_Token Y 이용기관이 폐기할 토큰

주1) 포털에서 앱 등록 시 자동 발급

### 토큰(Accsess Token) 폐기

curl -X POST \
https://devapiportal.ibk.co.kr:9443/ibk/biz/oauth/threeLeggedRevoke \
-H 'Content-Type: application/x-www-form-urlencoded' \
-u '{{Cient_ID}}:{{Client_Secret}}' \
-d 'token_type_hint=access_token&token=AAIgZmJiYjlkODUyMDA2ZjgxNjljMmM0Njc3OTVmN2QzNzdZphzv3_ywq2d6kMzYK-WitHdwJkuz61bU6X_FIzDnMw9-C4Lo2ex961W6YOV-nOQnJV1_1vWfrEebUgVStSyq7-rcX42rqqmVk6WVO7RpflCLZKLuIYGlKBivh_ZeYGg&client_id={{Cient_ID}}&client_secret={{Client_Secret}}'

Response

토큰 폐기 Response(항목, 설명) 표
항 목 설 명
status 정상 처리 여부(success/failure)
- 폐기된 토큰을 재폐기시 failure
- 길이 STR(7) 
### 토큰(Access Token) 폐기 결과

“status”: “success”

2-3. 토큰 재발급

기존 토큰의 폐기 또는 Access Token 유효기간 만료인 경우 Refresh Token으로 Access Token을 재발급 합니다.

[참고] 사용자의 금융정보제공동의 기간이 경과(만료)된 경우 또는 Refresh Token의 유효기간 만료로 Access Token 재발급이 불가능한 경우에는 이미 등록된 계좌에 대한 재동의 및 사용자 인증을 통해 새로운 토큰을 발급받아야 합니다.

Request

토큰 재발급 Request(HTTP URL, HTTP Method, Content-Type) 표
HTTP URL https://devapiportal.ibk.co.kr:9443/ibk/biz/oauth/threeLeggedRenew
HTTP Method POST
Content-Type application/x-www-form-urlencoded
토큰 재발급 Request(항목, 값, 필수, 설명) 표
항 목 값 필 수 설 명
Authorization: Basic 고정값 : OAuth 2.0의 Basic Y Client_ID : IBK에서 발급한 이용기관 앱의 Client ID
Clent_Secret : IBK에서 발급한 이용기관 앱의 Client Secret
client_secret <Client_Secret> 주1) Y IBK에서 발급한 이용기관 앱의 Client Secret
grant_type 고정값 : refresh_token Y OAuth 2.0 Token 방식 정의
refresh_token Refresh_Token Y 사용자의 Refresh Token 값 
### 토큰(Accsess Token) 재발급

curl -X POST \
https://devapiportal.ibk.co.kr:9443/ibk/biz/oauth/threeLeggedRenew \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic {{Client_ID}}:{{Clent_Secret}}' \
-d 'grant_type=refresh_token&refresh_token={{Refresh_Token}}'

Response

토큰 재발급 Response(항목, 설명) 표
항 목 설 명
token_type Access Token 유형
- 고정값 : Bearer
access_token IBK에서 발행된 사용자의 Access Token 값(670 Byte)
scope Access Token 권한 범위
expires_in Access Token 유효기간(초)
- 고정값 : 7776000 (90일)
consented_on Access Token 유효기간
- UNIX 시간 기준		 
### 재발급된 토큰 수신

"token_type": "Bearer",
"access_token": "AAIgZjM3ZGM0N2M1Zjk5Y2RjZDBiYWNhMzZlYmViOWU3NWHsRwbWIg8cTgqHx0Kpy8VIT7uZZapY5hW7aMPM8-kQPQEehBvJhsVi-ShwN44EtWWngpKqDqGUK3N9Vc-PAdHq3NqHy0kobK_F1haNW-26F4G_WLYLwqfAaf-LgmjkErMfEQoSsx6b7rvwZRTCk01MYk1bzQsz1Xlob1vMmr1ffY6qoYjsWeVFpfBEP30tWSc",
"scope": "login",
"expires_in": 7776000,
"consented_on": 1625637740