- 공통 가이드
- 개발 가이드
- 디자인 가이드
개발 가이드
연동 가이드
1. 휴대폰번호 로그인 인증 요청 (Authorization code 발급)1.1 설명
- 휴대폰번호 로그인은 OAuth2.0 프레임워크를 사용하여 PASS 사용자의 인증을 진행합니다.
- 개발자센터에 애플리케이션이 등록되어 있어야 합니다. (애플리케이션 등록하러 가기)
- 사용자가 PASS앱을 통해 인증에 성공하면 콜백 URL로 인증 코드(authorization code)를 반환받습니다.
- 사용자의 웹 브라우저에서 요청되어야 합니다.
- 이 요청으로 휴대폰번호 로그인 인증 요청 페이지가 호출됩니다.
- 처음 휴대폰번호 로그인 인증하는 사용자의 경우 제 3자 정보제공 동의 페이지가 노출됩니다. (여기서 애플리케이션 등록시 설정한 제공정보들이 노출됩니다)
- 인증 코드(Authorization Code)는 발급 후 1분동안 유효합니다.
[자동로그인 관련]
- SKT/KT 사용자에 한해서만 기능을 제공합니다.
- 휴대폰번호 로그인 SDK를 사용 할 경우 제휴사의 App.에서도 자동로그인 기능을 사용 할 수 있습니다.
- 사용자에게 발급 된 자동로그인 정보는 2주간 유효합니다.
- 자동로그인 해지는 PASS앱 내 자동로그인 설정 메뉴를 통해 제공됩니다.
- PASS 앱에서 휴대폰번호 로그인 서비스를 해지 할 경우 자동로그인 기능은 즉시 해지됩니다.
[WebView 관련]
- 제휴사 App.에서는 WebView를 활용하여 PASS 로그인 모바일 화면을 요청 할 수 있습니다.
- isHybrid 파라미터를 설정 할 경우 Native에서 처리 할 JavaScript Function을 최소화합니다.
- 하이브리드 환경에 제공되는 휴대폰번호 로그인 모바일 화면은 Mobile Browser를 통해 제공되는 화면과 차이가 있습니다.
- 하이브리드 환경에서는 자동로그인 기능을 제공하지 않습니다. (휴대폰번호 로그인 SDK 사용 시 사용 가능)
URL : //id.passlogin.com/oauth2/authorize?response_type=code&client_id={client_id}&redirect_uri={encoded_redirect_uri}&state={encoded_state}&prompt={prompt}&isHybrid=Y
1.3 프로토콜HTTPS
1.4 HTTP메서드- GET
- POST
파라미터에 대해서 파라미터, 타입, 필수여부, 설명으로 분류되어 내용을 제공하는 테이블
client_id | String | Y | 애플리케이션 등록시 발급받은 클라이언트 아이디. (클라이언트 아이디 확인 방법 링크) | ||||||
redirect_uri | String | Y | Authorization Code를 발급받은 후 요청될 Callback URL 으로 애플리케이션 등록시 등록된 Callback URI 중 하나와 일치하여야 한다. (URL 인코딩 필요) | ||||||
response_type | String | Y | 인증 과정에 대한 구분값으로 code 로 고정 | ||||||
state | String | Y | CSRF(Cross Site Request Forgery) 를 방지하기 위해 사용하는 클라이언트 측 인증값으로 결과가 리다이렉트 될 때 입력한 값이 그대로 전달됨 (URL인코딩 필요) | ||||||
prompt | String | N | 휴대폰번호 로그인 사용자 인증 시 자동로그인 기능을 제어 할 수 있다.
| ||||||
isHybrid | String | N |
WebView와 Mobile Web 간 차이점을 설명하는 테이블
|
[PC/Mobile Web]
//id.passlogin.com/oauth2/authorize?client_id=clientId2&redirect_uri=https%3A%2F%2Fwww.sample.com%2Flogin_callback&response_type=code&state=12345&prompt=select_account
[WebView]
//id.passlogin.com/oauth2/authorize?client_id=clientId2&redirect_uri=https%3A%2F%2Fwww.sample.com%2Flogin_callback&response_type=code&state=12345&isHybrid=Y
1.7 응답응답에 대해서 파라미터, 타입, 필수여부로 분류되어 제공되는 테이블
code | String | 휴대폰번호 로그인 인증에 성공하면 반환받는 인증 코드이며, 액세스 토큰(access token) 발급에 필수 값으로 사용 |
state | String | CSRF를 방지하기 위해 사용하는 클라이언트 측 인증값 |
정상 응답
HTTP/1.1 302 Found Location: //www.sample.com/login_callback?code=0fdVa6&state=12345
에러 응답
HTTP/1.1 400 { "error" : "invalid_request", "message" : "parameter error" }
2. 휴대폰번호 로그인 액세스 토큰 발급 요청 (Access Token 발급)2.1 설명
- 휴대폰번호 로그인 API를 사용하기 위한 액세스 토큰의 발급을 요청합니다.
- 휴대폰번호 로그인 API는 사용자의 기본 정보를 조회할 때 사용합니다.
- server-to-server 호출을 권장합니다.
- 액세스 토큰의 유효시간은 10분입니다.
URL : //id.passlogin.com/oauth2/token?grant_type={grant_type}&client_id={client_id}&client_secret={client_secret}&code={code}&state={encoded_state}
2.3 프로토콜HTTPS
2.4 HTTP메서드POST
2.5 요청헤더Authorization: Basic {base64_encode({client_id}:{client_Secret})} Content-Type: application/x-www-form-urlencoded
2.6 파라미터파라미터에 대해서 파라미터, 타입, 필수여부, 설명으로 분류되어 내용을 제공하는 테이블
grant_type | String | Y | 인증 과정에 대한 구분값으로 authorization_code 로 고정 |
client_id | String | N | 애플리케이션 등록 시 발급받은 클라이언트 아이디. (클라이언트 아이디 확인 방법 링크) Basic 방식의 Authorization 헤더를 사용할 수 없는 경우 요청 파라미터에 클라이언트 아이디를 셋팅한다. |
client_secret | String | N | 애플리케이션 등록 시 발급받은 클라이언트 Secret. (클라이언트 Secret 확인 방법 링크) Basic 방식의 Authorization 헤더를 사용할 수 없는 경우 요청 파라미터에 클라이언트 Secret을 셋팅한다. |
code | String | Y | 휴대폰번호 로그인 인증 요청 API 호출에 성공하고 리턴받은 인증코드(Authorization Code) 값 |
state | String | N | CSRF(Cross Site Request Forgery) 를 방지하기 위해 사용하는 클라이언트 측 인증값으로 결과가 리다이렉트 될 때 입력한 값이 그대로 전달됨 (URL인코딩 필요) |
curl -X POST '//id.passlogin.com/oauth2/token' -H 'Authorization: Basic Y2xpZW50SWQyOm1DbGllbnRTZWNyZXQ=' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=authorization_code' -d 'code=0fdVa6' -d 'state=12345'
2.8 응답응답에 대해서 파라미터, 타입, 설명으로 분류되어 내용을 제공하는 테이블
access_token | String | 액세스 토큰(access token) |
token_type | String | 토큰의 접근 타입 (Bearer) |
expires_in | Integer | 액세스 토큰(access token)의 만료 시간(초) |
state | String | CSRF를 방지하기 위해 사용하는 클라이언트 측 인증값(Optional) |
정상 응답
HTTP/1.1 200 OK { "access_token":"G/Tit+vKtqcj3rGTvqdGzWN5JskQuts5Tx4qGennVVxr/dNbRf88qBviQAWBtKDKnIeWM8Wca6XIO/H9MW1JYHaVXFqhQR8l9ezk8x+2XX8=", "token_type":"bearer", "expires_in":"3600", "state":"12345" }
에러 응답
HTTP/1.1 500 Internal Server Error { "error" : "server_error", "message" : "Invalid authorization code: 0fdVa6" }
에러코드 안내에러 코드 별 설명 및 조치 방안을 안내합니다.
에러코드에 대해서 에러코드, 에러 메시지, 조치방안으로 분류되어 내용을 제공하는 테이블
입력값을 확인해주세요. | 3개 통신사에서 확인되지 않은 이름과 전화번호이므로 입력값을 확인한다. |
필수항목 {요청항목}이 누락되었습니다. | 일반적인 오류로 API에 필요한 필수 파라미터명을 체크한다. |
{요청항목} 값이 유효하지 않습니다 | 파라미터의 값을 체크한다. |
Invalid redirect: {URL} does not match one of the registered values. | redirect_uri가 등록된 정보와 일치하지 않습니다. redirect_uri 값을 확인한다. |
Invalid authorization code | code 값을 확인한다. |
인증에 실패했습니다. | 헤더의 Authorization 토큰 값을 확인한다. |
A client id must be provided | 클라이언트 ID를 확인해주세요.(parameter is null) |
Bad client credentials | 클라이언트 ID를 확인해주세요.(DB에 없음) |
유효하지 않은 URL의 API를 요청하였습니다. | API URL을 확인한다. |
지원하지 않는 HTTP Method입니다. | 요청 HTTP Method를 확인한다 |
일시적인 오류가 발생했습니다. 잠시 후 다시 요청해 주세요. | 휴대폰번호 로그인 플랫폼에 문의한다. |