콘텐츠로 이동

인가 코드와 사용자 토큰 받기

1. 인가 코드 받기

사용자 토큰을 발급 받기 위해서는 인가 코드(code)를 먼저 받아야 합니다.

  • 인가 코드 받기는 웹 브라우저를 통해 요청을 합니다.
  • redirect_uri로 전달된 code를 이용해 사용자 토큰과 교환 가능합니다.
  • 사용자 토큰 발급에 사용된 code는 재사용 할 수 없습니다.

1.1. 요청 정보

요청 형식

웹 브라우저를 통해서 요청을 합니다.

  • Request 형식
https://login.pre.wonders.app/wauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}&scope={scope}
  • Request 예제
https://login.pre.wonders.app/wauth/authorize?response_type=code&client_id=sampleClientId&state=dnjsejfhrmdls&redirect_uri=&scope=public_profile

요청 파라미터

파라미터 설명 필수 여부 고정값
response_type "code" 문자열 값으로 고정합니다. 필수 code
client_id 위메프로그인에서 제공한 Client ID 필수
redirect_uri 인가 코드를 리다이렉트 해줄 URI로 URL 인코딩을 적용해서 보냅니다. redirect_uri는 등록된 Redirect URI 중 하나와 일치해야 합니다. 필수
state 일반적으로 CSRF 공격을 방지하기 위해 임의로 생성된 고유 값을 입력합니다. 인가 코드를 리다이렉트시 해당 값이 전달됩니다. 권장
scope 정보의 접근 범위 지정이 가능합니다. 보낼 scope이 여러개인 경우는 ,(comma)를 구분자로 사용합니다. 옵션

scope 값을 보내지 않은 경우는 클라이언트에 할당 받은 scope으로 설정되며 scope 값을 보내는 경우는 보낸 scope으로 설정됩니다. 할당 받지 않은 scope 값을 보낸 경우는 에러(invalid_scope)가 발생합니다.

비 로그인 상태라면 로그인 창으로 리다이렉트 되고, 사용자가 로그인을 하면 사용자 동의를 얻기 위한 페이지가 나타납니다. 사용자가 동의 또는 거부를 선택하면 redirect_uri로 결과가 리다이렉트 됩니다.

1.2. 응답 정보

응답 형식 및 예제

  • Response 형식
{redirect_uri}?code={code}&state={state}
  • Response 예제
https://sample.com/oauth/callback?code=YgI2cr&state=dnjsejfhrmdls

응답 파라미터

파라미터 설명
code 인가 코드
state 인가 코드 요청 시 보낸 state 값

에러 응답 형식 및 예제

  • Error Response 형식
{redirect_uri}?error={error}&error_description={error_description}&state={state}
  • Error Response 예제
https://sample.com/oauth/callback?error=access_denied&error_description=User%20denied%20access&state=dnjsejfhrmdls

에러 응답 파라미터

파라미터 설명
error 인가 코드 요청 실패 시 전달되는 에러코드
error_description 인가 코드 요청 실패 시 전달되는 에러메시지
state 인가 코드 요청 시 보낸 state 값

에러 코드

error 설명 오류 해결 방법
invalid_scope 요청한 scope가 유효하지 않은 경우 "scope=public_profile"로 요청했는지 확인
access_denied 사용자가 정보 제공 동의를 거부한 경우 사용자가 정보 제공을 거부했기 때문에 적절한 페이지로 리다이렉트 처리
invalid_client Client ID가 유효하지 않은 경우 발급받은 ID가 정확한지 확인
invalid_grant error_description="Invalid redirect ...": redirect_uri가 유효하지 않은 경우 등록된 Redirect URI와 일치하는 확인

redirect_uri, client_id가 유효하지 않은 경우는 에러페이지가 출력됩니다. 화면에 나오는 응답메시지를 확인하고 오류를 해결합니다.

2. 사용자 토큰 받기

인가 코드를 사용하여 사용자 토큰을 받을 수 있습니다.

  • 사용자 토큰 발급에 앞서 인가 코드 발급이 반드시 선행되어야 합니다.
  • 요청 Header에는 Authorization 헤더를 반드시 포함해야 합니다. Authorization 요청 헤더 살펴보기

2.1. 요청 정보

Authorization 요청 헤더

  • 문법

    Authorization: {type} {credentials}

  • type

    • 인증 타입으로 "Basic"을 사용합니다.

  • credentials

    • 등록된 클라이언트 아이디와 시크릿 값 사이에 콜론(:) 값을 삽입한 문자열을 만듭니다. {client_id}:{client_secret}
    • 만든 문자열을 base64 인코딩하여 사용합니다.

  • 예제

Authorization: Basic c2FtcGxlXzJGSWp5aEZKNXg6bExrMW5mTnhPRkNETWJiVVRoVDk5REY3TzZ4Z0w0ekNBVjQ0ZVR4eU4xST0=

요청 형식 및 예제

  • 요청 형식
POST /wauth/token
Host: login.pre.wonders.app
Authorization: Basic {base64_encode({client_id}:{client_secret})}
  • 요청 예제
curl -i -X POST \
 'https://login.pre.wonders.app/wauth/token' \
 -H 'Authorization: Basic c2FtcGxlXzJGSWp5aEZKNXg6bExrMW5mTnhPRkNETWJiVVRoVDk5REY3TzZ4Z0w0ekNBVjQ0ZVR4eU4xST0=' \
 -d 'grant_type=authorization_code' \
 -d 'code=YgI2cr' \
 -d 'redirect_uri=https://sample.com/oauth/callback'

요청 파라미터

파라미터 설명 필수 여부 고정값
grant_type "authorization_code" 고정 필수 authorization_code
code 인가 코드 요청으로 받은 값 필수
redirect_uri 인가 코드 요청 시 사용한 redirect_uri 필수

2.2. 응답 정보

응답 형식 및 응답 예제

  • 응답 형식 응답 Body는 JSON 객체로 전달됩니다.

  • 응답 예제

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8
{
   "access_token":"14e2ac4d-de40-4e39-8bda-bd1e89d2815b",
   "token_type":"bearer",
   "refresh_token":"1d342133-6148-4223-9870-b08b4403197d",
   "expires_in":3599,
   "scope":"public_profile"
}

응답 파라미터

파라미터 설명
access_token 사용자 정보 조회와 같은 API 요청 시에 필요한 access_token 입니다.
token_type 토큰 타입으로 "bearer" 타입을 사용합니다.
refresh_token 만료된 access_token 재발급을 위해 사용합니다.
expires_in access_token 만료 시간으로 단위는 초(second) 입니다.
scope 토큰이 접근 가능한 리소스의 범위입니다.

에러 응답 형식 및 예제

HTTP/1.1 400
Content-Type: application/json;charset=UTF-8
{
   "error":"invalid_grant",
   "error_description":"Invalid authorization code: UkwB4b"
}

에러 응답 파라미터

파라미터 설명
error 사용자 토큰 요청 실패 시 전달되는 에러코드
error_description 사용자 토큰 요청 실패 시 전달되는 에러메시지

에러 코드

error error_description 설명 오류 해결 방법
invalid_request 필수 파라미터를 누락하여 요청한 경우 요청에 누락된 값이 없는지 확인합니다.
unsupported_grant_type Unsupported grant type: {요청한 grant_type 값} 요청한 grant_type이 유효하지 않은 경우 "grant_type=authorization_code"로 요청했는지 확인
invalid_grant Redirect URI mismatch. 요청한 redirect_uri가 유효하지 않은 경우 인가 코드 요청 시 사용한 redirect_uri와 일치하지 않은 경우로 동일한 값을 사용
invalid_grant Invalid authorization code 요청한 code가 유효하지 않은 경우 인가 코드 요청을 통해서 받은 code 인지 확인합니다. code는 발급 후 1분이 경과하면 만료되고, 사용자 토큰 발급에 사용된 code는 재사용 할 수 없습니다.

응답의 상태 코드가 401(Unauthorized)인 경우는 Authorization 헤더가 누락되거나 값이 정확하지 않은 경우입니다. Client ID와 Client Secret값이 정확한지 확인하거나 문자열 조합이나 Base64 인코딩을 제대로 했는지 확인합니다.