> For the complete documentation index, see [llms.txt](https://tech.x2bee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tech.x2bee.com/api-guide/store-front/member/undefined-4.md).

# 로그인

가입한 회원이 X2BEE 쇼핑몰에 로그인하여 계정에 액세스할 수 있는 인증 기능을 제공합니다. 이를 통해 회원은 개인 정보를 입력하고 로그인하여 개인화된 쇼핑 경험을 누릴 수 있습니다. 로그인은 일반적인 로그인과 간편 로그인(카카오, 네이버) 기능을 지원하며, 휴면 회원이 로그인 시 본인인증을 통해 로그인한 경우 휴면 회원 복원 처리 기능도 포함됩니다.

***

## 주요 기능

* **일반 로그인**
  * 회원 가입이 완료된 회원은 아이디와 비밀번호를 입력하여 로그인할 수 있습니다.
* **간편 로그인**
  * 카카오, 네이버 인증을 통해 회원가입이 완료된 회원은 해당 소셜 채널을 통한 간편 로그인이 가능합니다.
* **휴면 회원 복원**
  * 휴면 회원이 로그인 시 본인인증을 통해 로그인한 경우, 휴면 회원 복원 처리가 가능합니다.
* **토큰 발급**
  * 로그인 성공 시, 액세스 토큰(AccessToken)과 리프레시 토큰(RefreshToken)을 발급합니다.
* **토큰 종류**
  * **액세스 토큰(AccessToken)**: 사이트 이용을 위해 발급되는 토큰으로 2시간 동안 유효합니다.
  * **리프레시 토큰(RefreshToken)**: 액세스 토큰의 유효기간이 종료된 경우 액세스 토큰을 갱신하는 토큰으로 3시간 동안 유효합니다.
* **accessToken에 포함된 정보**
  * **mbrNo:** 회원번호
  * **langCd**: 회원의 가입 사이트 국가 및 로그인 위치
* **Redis 저장소 등록**
  * 로그인 시 각 모듈에서 권한 확인 및 UserDetail(회원 기본 정보)을 사용하기 위해 Redis 저장소에 등록합니다.
* **캡차코드 검증**
  * 로그인 오류 3회 초과 시 무차별 대입 공격을 방지하기 위해 캡차코드 검증을 진행합니다.

## 프로세스 정의

<figure><img src="/files/iiyDXjuEWeSa7pxjuvaa" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

### 로그인 요청

사용자는 클라이언트 애플리케이션에서 로그인 페이지를 통해 사용자 이름과 비밀번호를 입력하여 로그인을 시도합니다. 고객이 로그인할 때 회원ID 와 비밀번호를 입력하여 서버로 인증요청을 전달하여 신원을 검증한 후 사이트를 이용할 수 있습니다.
{% endstep %}

{% step %}

### 간편 로그인

간편로그인은 소셜 미디어 계정으로 연동하여 웹사이트를 간편하게 로그인하여 사용할 수 있습니다.\
소셜 로그인을 구현할 때에는 OAuth 2.0과 OpenID Connect와 같은 인증 프로토콜을 사용하여 소셜 미디어 플랫폼과 통합하고, 사용자의 권한을 획득하여 로그인 프로세스를 완료할 수 있습니다. 이를 통해 사용자는 소셜 미디어 계정을 사용하여 서비스에 간편하게 로그인할 수 있습니다.
{% endstep %}

{% step %}

### 토큰 발급

토큰 발급은 주로 사용자 인증 후에 클라이언트에게 액세스 토큰(access token)과 리프레시 토큰(refresh token)을 제공하는 프로세스를 의미합니다. \
액세스 토큰의 유효시간은 2시간이며, 2시간 이후에는 토큰의 권한을 상실하여 사이트 이용이 불가능합니다. \
리프레시 토큰의 유효시간은 3시간이며, 3시간 이후에는 토큰의 권한을 상실하여 액세스 토큰 재갱신이 불가능합니다.
{% endstep %}

{% step %}

### 소셜 계정 인증

소셜 계정 인증 과정을 통해 소셜 채널로부터 받은 개인정보를 검증합니다. 검증 과정에서 X2BEE 쇼핑몰의 회원 여부를 판단하고, 회원가입 혹은 로그인 처리로 분기 처리 합니다.
{% endstep %}

{% step %}

### 캡차코드 생성

캡차코드는 웹사이트나 애플리케이션에서 자동 가입, 스팸 전송, 봇에 의한 공격을 방지하기 위한 보안 방법입니다. \
비밀번호 3회 오류 시 활성화되어 봇인지 사람인지 판별합니다.
{% endstep %}
{% endstepper %}

## API 기능 목록

<table><thead><tr><th width="111.2222900390625">API</th><th width="372.3333740234375">설명</th><th width="98">Server</th><th width="90.22216796875">메소드</th><th>비고</th></tr></thead><tbody><tr><td>로그인</td><td>로그인 시 사이트 이용에 필요한 accessToken과 refreshToken 두 가지 토큰이 생성됩니다. accessToken은 각 모듈에 요청 시 정상적으로 로그인 됐음을 확인하는 토큰이며, refreshToken은 accessToken의 유효기간이 만료 되었을 경우 새 accessToken을 생성하기 위한 토큰입니다.</td><td>Member</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=member&#x26;depth=%EB%A1%9C%EA%B7%B8%EC%9D%B8&#x26;path=login">🔗API 확인하기></a></td></tr><tr><td>로그아웃</td><td>로그인 시 생성된 refreshToken의 토큰정보를 데이터베이스에서 삭제합니다.</td><td>Member</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=member&#x26;depth=%EB%A1%9C%EA%B7%B8%EC%9D%B8&#x26;path=logout">🔗API 확인하기></a></td></tr><tr><td>소셜 로그인 처리</td><td>소셜 계정으로 로그인을 진행합니다. 소셜계정이 연동되어 있거나, 가입 당시 소셜 계정으로 가입했을 경우 지원 됩니다.</td><td>Member</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=member&#x26;depth=%EB%A1%9C%EA%B7%B8%EC%9D%B8&#x26;path=connect">🔗API 확인하기></a></td></tr><tr><td>토큰정보 <br>갱신</td><td>로그인 시 생성된 accessToken의 유효기간이 만료된 경우 refreshToken을 사용하여 accessToken을 새로 생성하고, 유효기간을 연장 합니다.</td><td>Member</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=member&#x26;depth=%EB%A1%9C%EA%B7%B8%EC%9D%B8&#x26;path=refreshToken">🔗API 확인하기></a></td></tr><tr><td>소셜 계정 인증</td><td>소셜 계정 정보 및 본인인증 CI 값을 활용하여 회원 여부 및 소셜 연동 여부를 판단하고 소셜 계정이 연동된 계정이면 로그인 처리, 소셜 계정이 연동되어 있지 않은 회원이면 연동을 위한 권한 메세지, 비회원일 경우 회원가입 페이지를 이동하는 서비스를 지원합니다.</td><td>Member</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=member&#x26;depth=%EB%A1%9C%EA%B7%B8%EC%9D%B8&#x26;path=check">🔗API 확인하기></a></td></tr><tr><td>토큰 로그인</td><td>자동로그인 및 생체인증 로그인용 토큰을 사용하여, 사이트 이용이 가능한 accessToken 및 refreshToken을 생성합니다.</td><td>Member</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=member&#x26;depth=%EB%A1%9C%EA%B7%B8%EC%9D%B8&#x26;path=tokenlogin">🔗API 확인하기></a></td></tr><tr><td>토큰정보 <br>발급</td><td>자동로그인 및 생체인증 로그인을 위해 토큰을 생성하며, 해당 토큰은 토큰 자체의 유효기간과 서버의 데이터 베이스에서 관리됩니다. 해당 토큰의 유효기간은 10년입니다.</td><td>Member</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=member&#x26;depth=%EB%A1%9C%EA%B7%B8%EC%9D%B8&#x26;path=saveAutoToken">🔗API 확인하기></a></td></tr><tr><td>토큰정보 <br>삭제</td><td>자동로그인 및 생체인증 로그인을 위해 생성된 토큰정보를 데이터베이스에서 삭제합니다.</td><td>Member</td><td>DELETE</td><td><a href="http://api.x2bee.com/content?msa=member&#x26;depth=%EB%A1%9C%EA%B7%B8%EC%9D%B8&#x26;path=deleteAutoToken">🔗API 확인하기></a></td></tr><tr><td>휴면회원 <br>해제 처리</td><td>휴면 처리가 된 회원의 분리보관된 개인정보를 복원 처리하여 정상회원 상태로 복원합니다.<br>api/goods/v1/qnaWithdraw/updateRecoveryQna api/order/v1/member/restoreMemberOrderInfo api/order/v1/customerservice/restoreMember api/event/v1/common/undoSeparate api/event/v1/common/mergeMbrBase api/event/v1/common/mergeMbrDlvp</td><td>Member</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=member&#x26;depth=%EB%A1%9C%EA%B7%B8%EC%9D%B8&#x26;path=stopMemberCancel">🔗API 확인하기></a></td></tr><tr><td>캡차 코드 음성 변환</td><td>생성된 캡차코드의 식별이 어려운 경우 생성된 숫자를 음성으로 변환하여 출력합니다.</td><td>Member</td><td>GET</td><td><a href="http://api.x2bee.com/content?msa=member&#x26;depth=%EB%A1%9C%EA%B7%B8%EC%9D%B8&#x26;path=createCaptchaTextToAudio">🔗API 확인하기></a></td></tr><tr><td>캡차 코드 생성</td><td>로그인 3회 초과 오류 시, 6자리의 digit number를 무작위로 생성하여 무차별 대입 공격 등 보안 이슈를 방지합니다.</td><td>Member</td><td>GET</td><td><a href="http://api.x2bee.com/content?msa=member&#x26;depth=%EB%A1%9C%EA%B7%B8%EC%9D%B8&#x26;path=createCaptchaImg">🔗API 확인하기></a></td></tr></tbody></table>

## 용어 정의

<table><thead><tr><th width="192.888916015625">명칭</th><th>설명</th><th data-hidden>비고</th></tr></thead><tbody><tr><td>캡챠(CAPTCHA)코드</td><td>웹사이트나 애플리케이션에서 자동 가입, 스팸 전송, 봇에 의한 공격을 <br>방지하기 위한 보안 메커니즘 중 하나입니다. CAPTCHA 코드는 사용자가 사람인지 로봇인지 판별할 수 있도록 하는 테스트로, 주로 왜곡된 글자나 숫자를 보여주고 사용자에게 이를 인식하도록 요청하는 방식으로 구현됩니다.</td><td></td></tr><tr><td>액세스 토큰(Access token)</td><td>클라이언트가 서버 리소스에 접근하기 위한 권한을 부여 받은 후, 그 권한을 증명하는데 사용되는 문자열입니다. 액세스 토큰은 일정 기간 동안만 <br>유효하며, 필요에 따라 재발급이나 취소될 수 있습니다.</td><td></td></tr><tr><td>리프레시 토큰(Refresh token)</td><td>OAuth 2.0 프로토콜에서 사용되는 보안 토큰 중 하나입니다. 주로 액세스 토큰(access token)의 만료 시간이 지날 경우 새로운 액세스 토큰을 얻기 위해 사용됩니다.</td><td></td></tr><tr><td>간편로그인</td><td>소셜 미디어 계정 또는 기타 온라인 서비스 계정을 사용하여 다른 웹사이트나 앱에 로그인할 때 사용하는 기능입니다.</td><td></td></tr><tr><td>휴면회원</td><td>일정 기간 동안 로그인을 하거나 서비스를 이용하지 않은 회원을 나타냅니다. 사용자가 1년간 로그인을 하지 않거나 서비스를 이용하지 않으면 휴면 상태로 간주됩니다.</td><td></td></tr></tbody></table>

## 기타 참고사항

* **인증 및 인가**
  * 로그인 시 JWT 인증 방식을 통해 생성된 토큰인 accessToken과 refreshToken은 토큰 자체에 유효기간이 설정되어 있으며, 해당 유효기간이 지났을 경우 인증에 실패합니다.
  * 로그인을 통해 생성된 토큰은 Server-Side의 ET\_MBR\_CERTI\_TKN\_ISSU\_INFO 테이블에 저장됩니다.
  * 리프레시 토큰과 자동로그인 혹은 생체인증 토큰으로 로그인 및 갱신 과정을 진행할 때, 토큰 자체의 유효기간과 ET\_MBR\_CERTI\_TKN\_ISSU\_INFO 테이블에 토큰의 존재 여부를 통해 이중 체크하여 인증 및 인가 합니다.
* **회원 정보 Redis Cache 등록**
  * 로그인 성공 시 생성된 UserDetail 정보를 Redis 저장소에 등록하며, 로그인 시 발급된 accessToken으로 API 요청 시 각 모듈에 UserDetail 정보를 조회 하여 제공합니다.
  * UserDetail에는 회원명, 회원번호, 회원관리코드(ME002), 회원구분코드(ME001), 로그인아이디, 회원등급코드(ME008), 임직원여부, 성별별구분코드(ME017), 성인인증여부, 나이, 국가코드, 회사구분코드(ME038)의 정보가 기록됩니다.
* **휴면회원 해제**
  * 비밀번호를 입력하여 계정의 소유주를 확인하고, 비밀번호가 일치하는 경우 별도로 분리되어 있는 분리보관 데이터 베이스에 저장된 데이터를 일반 데이터 베이스로 정보를 이관합니다.
  * 휴면회원 해제 시 api-member의 데이터를 선 복구하고, 복구가 성공 되었을 경우 각 모듈에 휴면회원 복원 처리에 대한 API를 요청 및 전송 합니다.
  * 각 모듈에서 복원 과정 중 실패하는 모듈이 존재 할 경우, ET\_STP\_MBR\_FAIL\_INFO 테이블에 실패한 모듈 정보를 기록 후 추후 reTrySeparateJob 배치를 통해 재실행 됩니다.
* **캡차코드**
  * 캡차코드의 경우 SimpleCaptcha 라이브러리를 사용합니다.
* **로그인 제한**
  * 로그인 시 로그인을 시도한 사이트의 국가코드와 가입 시 진행한 국가코드를 비교하여 일치하지 않을 경우 로그인이 제한됩니다.
* **토큰로그인은 자동로그인과 생체인증 로그인 지원**
  * 자동로그인 활성화를 위해서는, 로그인 시 자동로그인 체크박스를 활성화 후 로그인을 진행해야 하며, 자동로그인의 토큰 유효기간은 10년으로 설정되어 있습니다.
  * 생체인증 로그인의 경우 앱 전용 서비스로 앱에서 로그인 후 마이페이지 설정을 통하여 활성화 후 로그인이 가능합니다. 생체인증 로그인의 토큰 유효기간은 10년으로 설정되어 있습니다.
* **소셜로그인**
  * 소셜로그인은 최초 소셜 채널을 통한 회원가입 혹은 일반회원으로 로그인 후 마이페이지 설정에서 소셜 채널 계정 연동 과정을 진행 후 이용 가능합니다.
  * 현재, X2BEE 쇼핑몰은 카카오와 네이버 소셜 계정 로그인을 지원하고 있습니다.
* **본인인증서비스 설정 및 개발방법**
  * 자동로그인 활성화를 위해서는, 로그인 시 자동로그인 체크박스를 활성화 후 로그인을 진행해야 하며, 자동로그인의 토큰 유효기간은 10년으로 설정되어 있습니다.
  * 생체인증 로그인의 경우 앱 전용 서비스로 앱에서 로그인 후 마이페이지 설정을 통하여 활성화 후 로그인이 가능합니다. 생체인증 로그인의 토큰 유효기간은 10년으로 설정되어 있습니다.

### 네이버 / 카카오 설정 예시

### 네이버로그인

* 모듈: API-MEMBER
* 설정 파일: `application-local.properties`, `application-dev.properties`
* application properties:

```properties
social.login.naver.clientId=발급받은 clientId
social.login.naver.clientSecret=발급받은 clientSecret
```

* 네이버 로그인 관련 API: [네이버 개발자 링크 >](https://developers.naver.com/main)
  * 사용자조회 토큰 발급 URL: <https://nid.naver.com/oauth2.0/token>
  * 사용자조회 URL: <https://openapi.naver.com/v1/nid/me>
* 모바일 환경(env.local, env.dev) 환경변수:

```env
NAVER_LOGIN_KEY=발급받은 Key
```

***

### 카카오로그인

* 모듈: API-MEMBER
* 설정 파일: `application-local.properties`, `application-dev.properties`
* application properties:

```properties
social.login.kakao.clientId=발급받은 clientId
```

* 카카오 로그인 관련 API: [카카오 개발자 링크 >](https://developers.kakao.com/)
  * 사용자조회 토큰 발급 URL: <https://kauth.kakao.com/oauth/token>
  * 사용자조회 URL: <https://kapi.kakao.com/v2/user/me>
* 모바일 환경(env.local, env.dev) 환경변수:

```env
KAKAO_LOGIN_KEY=발급받은 Key
```

<br>

* **로그아웃**
  * 로그아웃을 진행하게 될 경우 refreshToken과 자동로그인 및 생체인증 토큰을 삭제하여 이후 해당 토큰으로 인증 요청이 들어왔을 경우 제한합니다.