From 4f9fbefbcc90e2fa06fa032e09ef69349f9c114f Mon Sep 17 00:00:00 2001 From: Rinjae Date: Wed, 1 Jul 2026 15:58:21 +0900 Subject: [PATCH] =?UTF-8?q?OAuth2=20=EA=B0=80=EC=9D=B4=EB=93=9C=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8:=20-?= =?UTF-8?q?=20=EC=9D=B8=EC=A6=9D=20=ED=97=A4=EB=8D=94=20`X-AUTH-TOKEN`?= =?UTF-8?q?=EC=9C=BC=EB=A1=9C=20=EB=B3=80=EA=B2=BD=20-=20`scope`=20?= =?UTF-8?q?=ED=95=84=EC=88=98=EA=B0=92=20"api"=EB=A1=9C=20=EC=88=98?= =?UTF-8?q?=EC=A0=95=20-=20=EC=98=A4=EB=A5=98=20=EC=BD=94=EB=93=9C=20?= =?UTF-8?q?=EB=B0=8F=20=EC=84=A4=EB=AA=85=20=ED=91=9C=EC=A4=80=ED=99=94=20?= =?UTF-8?q?(`E.GW.AUTH=5FFAIL`)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../views/apps/service/oauth2-guide.html | 96 +++++++++++-------- 1 file changed, 54 insertions(+), 42 deletions(-) diff --git a/src/main/resources/templates/views/apps/service/oauth2-guide.html b/src/main/resources/templates/views/apps/service/oauth2-guide.html index 237c0a5..0a96db3 100644 --- a/src/main/resources/templates/views/apps/service/oauth2-guide.html +++ b/src/main/resources/templates/views/apps/service/oauth2-guide.html @@ -123,7 +123,7 @@ { access_token, token_type:"bearer", expires_in:86400, scope, jti } - ③ GET /api/v1/... · Authorization: Bearer <access_token> + ③ GET /api/v1/... · X-AUTH-TOKEN: Bearer <access_token> ④ 검증 후 API 응답 @@ -139,7 +139,7 @@

ClientID/Secret 으로 토큰 엔드포인트에 POST 합니다.

- POST + GET · POST https://openapi.djbank.co.kr/dj/oauth/token x-www-form-urlencoded
@@ -173,8 +173,8 @@ scope - 선택 - 호출 권한 범위 (공백 구분) + 필수 + 고정값 "api" @@ -189,7 +189,7 @@ curl -X POST 'https://openapi -d 'grant_type=client_credentials' \ -d 'client_id=YOUR_CLIENT_ID' \ -d 'client_secret=YOUR_CLIENT_SECRET' \ - -d 'scope=read.accounts' + -d 'scope=api' # 응답: 200 OK + JSON @@ -208,8 +208,8 @@ curl -X POST 'https://openapi 
{
   "access_token": "eyJhbGciOiJSUzI1NiJ9...",
   "token_type": "bearer",
-  "expires_in": 86400,
-  "scope": "read.accounts",
+  "expires_in": 86399,
+  "scope": "api",
   "jti": "f47ac10b-58cc-4372-..."
 }
 
@@ -245,7 +245,7 @@ curl -X POST 'https://openapi
                             
                                 scope
                                 string
-                                실제 부여된 권한 범위
+                                부여된 권한 범위 (api)
                             
                             
                                 jti
@@ -262,13 +262,13 @@ curl -X POST 'https://openapi
         

             STEP 3
             
발급 토큰으로 API 호출

-            
Authorization 헤더에 Bearer 토큰을 실어 보호 자원 API 를 호출합니다.

+            
X-AUTH-TOKEN 헤더에 Bearer 토큰을 실어 보호 자원 API 를 호출합니다.

 
             

                 

                     
필수 헤더

                     

-                        Authorization:
+                        X-AUTH-TOKEN:
                         Bearer eyJhbGciOiJSUzI1NiJ9...
                     

 
@@ -277,7 +277,7 @@ curl -X POST 'https://openapi
                         
  • 동일 토큰은 expires_in(기본 86400초) 동안 재사용
    • 
                         
  • 만료 임박 시 재발급 후 교체 (예: TTL의 80% 시점)
    • 
                         
  • 매 호출마다 토큰을 새로 발급하지 마세요
    • 
-                        
  • 권한이 다른 API 는 scope 별로 토큰을 분리 발급
    • 
+                        
  • 401 "Access token expired" 응답 시 재발급 후 재호출
    • 
                     
                 
    
 
@@ -286,7 +286,7 @@ curl -X POST 'https://openapi
 
    # 보호 자원 API 호출
 curl -X GET \
   'https://openapi.djbank.co.kr/api/v1/accounts' \
-  -H 'Authorization: Bearer eyJhbGciOiJSUzI..' \
+  -H 'X-AUTH-TOKEN: Bearer eyJhbGciOiJSUzI..' \
   -H 'Accept: application/json'
 
 # 응답
@@ -313,28 +313,52 @@ HTTP/1.1 200 OK
                     
                     
                         
-                            400
-                            invalid_request
-                            필수 파라미터 누락/형식 오류
-                            grant_type, client_id, client_secret 확인
+                            401
+                            E.GW.AUTH_FAIL
+                            client not found (client_id 오류)
+                            client_id 확인
                         
                         
                             401
-                            invalid_client
-                            자격증명 불일치 / 미승인
-                            ClientID·Secret 재확인, 앱 상태 점검
+                            E.GW.AUTH_FAIL
+                            Bad client credentials (client_secret 불일치)
+                            client_secret 확인
                         
                         
                             401
-                            invalid_token
-                            만료/위·변조된 토큰
+                            E.GW.AUTH_FAIL
+                            Include unacceptable scope (허용되지 않은 scope)
+                            scope 를 api 로 설정
+                        
+                        
+                            401
+                            E.GW.AUTH_FAIL
+                            Access token expired (토큰 만료)
                             토큰 재발급 후 재시도
                         
                         
-                            403
-                            insufficient_scope
-                            scope 권한 부족
-                            필요 scope 추가 신청 후 재발급
+                            400
+                            E.GW.AUTH_FAIL
+                            Invalid Mandatory Field {grant_type} (누락)
+                            grant_type 포함 여부 확인
+                        
+                        
+                            400
+                            E.GW.AUTH_FAIL
+                            Invalid Mandatory Field {client_id} (누락)
+                            client_id 포함 여부 확인
+                        
+                        
+                            400
+                            E.GW.AUTH_FAIL
+                            Invalid Mandatory Field {client_secret} (누락)
+                            client_secret 포함 여부 확인
+                        
+                        
+                            400
+                            E.GW.AUTH_FAIL
+                            Invalid Mandatory Field {scope} (누락)
+                            scope=api 포함 여부 확인
                         
                     
                 
@@ -351,11 +375,9 @@ HTTP/1.1 200 OK
                 
    
                     401 Unauthorized · JSON
 
    {
-  "error": "invalid_client",
+  "error": "E.GW.AUTH_FAIL",
   "error_description":
-    "Client authentication failed",
-  "status": 401,
-  "timestamp": "2026-06-10T11:23:45Z"
+    "Unauthorized. [Bad client credentials(Client Secret is not match)]"
 }
 
 # 처리: ClientID·Secret 확인 후 재시도
    
@@ -375,26 +397,16 @@ HTTP/1.1 200 OK
                             
                                 error
                                 string
-                                에러 코드 (예: invalid_client)
+                                에러 코드 (예: E.GW.AUTH_FAIL)
                             
                             
                                 error_description
                                 string
-                                사람이 읽을 수 있는 설명
-                            
-                            
-                                status
-                                int
-                                HTTP 상태 코드
-                            
-                            
-                                timestamp
-                                string
-                                에러 발생 시각 (ISO 8601)
+                                오류 상세 설명 (사람이 읽을 수 있는 형태)
                             
                         
                     
-                    
    ⚠ error 코드는 RFC 6749 표준 코드 또는 DJBank 확장 코드
    
+                    
    ⚠ error 코드는 게이트웨이 표준 코드 (E.GW.AUTH_FAIL)