> For the complete documentation index, see [llms.txt](https://workspace-help.nhn-commerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://workspace-help.nhn-commerce.com/aurora-guide/api-1/open-id.md).

# 간편 로그인

* 🅐 간편 로그인 연동 프로세스
* 🅑 간편 로그인 회원가입
* 🅒 카카오 싱크 

<div align="left"><figure><img src="/files/5zNbwxGKaODKKYhjcSwm" alt="" width="563"><figcaption></figcaption></figure></div>

간편 로그인 연동 로직에 대해 소개합니다.\
OAuth 프로토콜 중 간편회원 로그인 기능을 통해 accessToken을 획득하는 방식입니다.

기본 스킨에서 간편 로그인을 구현한 연동 시나리오는 위 다이어그램과 같습니다.\
이를 아래 문서에서 각 프로세스 별 상세 설명합니다.&#x20;

***

### 🅐 간편 로그인 연동 프로세스

### ⓐ 간편 회원 로그인 버튼&#x20;

<div align="left"><figure><img src="/files/pRFYd04XV47WjKXuMOdy" alt="" width="375"><figcaption></figcaption></figure></div>

회원가입 페이지, 로그인 페이지 등에서 노출되는 간편 로그인 기능입니다.\
현재 제공하는 간편 로그인은 페이코, 네이버, 카카오, 페이스북 총 4개 입니다.&#x20;

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

어드민에서 각 간편 로그인 제공사 개발자 센터에서 발급 받은 Client ID와 Client Secret 키를 입력합니다.&#x20;

```
shop by basic/pro : 설정 > 기본정책 > 외부서비스 설정
shop by premium : 서비스관리 > 쇼핑몰 관리
```

어드민에서 연동 설정된 제공사에 한해, 회원가입 페이지 및 로그인 페이지에서 간편 로그인 기능이 제공됩니다.

> [GET /malls](https://docs.shopby.co.kr/?url.primaryName=admin/#/Mall/get-malls)\
> ► 몰 정보 조회하기\
> 쇼핑몰 전반에 대한 기본 정보와 설정 데이터를 조회할 수 있습니다.&#x20;

어드민에 연동 설정이 되어 있는 간편 로그인 제공사 정보를 조회합니다. \
연동되어 있지 않은 간편 로그인 제공사의 로그인 버튼은 노출되지 않습니다.

해당 API 응답 값 중 <mark style="background-color:yellow;">openIdJoinConfig</mark> 내  <mark style="background-color:yellow;">providers</mark> 값을 통해 확인 가능합니다.

### ⓑ 간편 로그인 연동 URI 획득

간편 로그인 제공사(provider)이 각각 다르므로, \
provider 별 일부 화면을 노출하기 위해서는 먼저 아래 API를 호출하여 간편 로그인 연동 URI를 조회합니다.&#x20;

> [GET /oauth/login-url](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/get-oauth-login-url)
>
> ► Openid 로그인 URI 조회하기\
> OpenID 로그 URI를 조회합니다.&#x20;

해당 API 호출 시 3개의 파라미터가 필요하며 각 파라미터에 대한 설명은 아래와 같습니다.

* **provider**
  * 간편 로그인 제공사
  * 각 제공사 id 앞에 'ncp\_' 를 추가 (ex. ncp\_payco, ncp\_naver, ncp\_kakao, ncp\_facebook)
* **state**&#x20;
  * CSRF 공격 방지용 토큰
  * client 에서 생성한 숫자, 영문 대소문자로 이루어진 6자리의 random string
* **redirectUri**
  * 인증 성공 후 이동할 쇼핑몰의 리다이렉트 URI (인코딩 필수)
  * 형식 : {location.origin}/callback/auth-callback.html
    * 참고) 모바일 도메인에 /m 을 추가해서 사용하는 경우 \
      {location.origin}/m/callback/auth-callback.html

### ⓒ 간편 로그인 제공사 (Provider) 화면 노출

획득한 간편 로그인 연동 URI를 통해 각 간편 로그인 제공사 화면을 노출합니다.

<div><figure><img src="/files/KCYoz8M6vHNib3DW0B1V" alt=""><figcaption></figcaption></figure> <figure><img src="/files/rcxGSmm4iNuboUsLlAJQ" alt=""><figcaption></figcaption></figure> <figure><img src="/files/a0AskYUx34y3XZL4uUSY" alt=""><figcaption></figcaption></figure> <figure><img src="/files/hV2J0js3cgfBkxf4XfZS" alt=""><figcaption></figcaption></figure></div>

### ⓓ 쇼핑몰 redirectURI로 이동

간편 로그인 제공사 화면에서 인증에 성공 후, code 값과 함께 쇼핑몰 redirecURI로 이동합니다.\
이를 통해 프론트 화면에도 각 간편 로그인 제공사에서의 인증 성공 여부를 전달합니다.&#x20;

#### <mark style="color:purple;">✓ 예시 코드</mark>

```
https://{쇼핑몰 도메인}/callback/auth-callback?code=XXXXXXXXXX
```

### ⓔ accessToken 획득

쇼핑몰 redirectURI에서 아래 API를 호출하여 accessToken과 refrehshToken을 획득합니다.

> [POST /oauth2/openid](https://docs.shopby.co.kr/?url.primaryName=auth/#/OAUTH2/post-oauth2-openid-token)
>
> ► OpenId AccessToken/RefreshToken 발급하기\
> OpenId 회원의 액세스 토큰 (accessToken) / 리프레시 토큰 (refreshToken)을 발급합니다.

액세스 기반의 로그인 방식을 사용하는 경우 아래 API를 호출하여 accessToken을 획득합니다.

> [POST /oauth/openid](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/post-oauth-openid)
>
> ► OpenId AccessToken 발급하기\
> OpenId 엑세스 토큰(accessToken)을 발급합니다.

### ⓕ 회원가입 여부 확인

해당 간편 로그인 계정이 현재 쇼핑몰에 가입한 상태인지 아닌지 여부를 확인합니다.

> [GET /profile](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/get-profile)
>
> ► 회원정보 조회하기\
> 회원정보를 조회합니다.&#x20;

응답 값 중 memberStatus 값이 WAITING 인 경우 쇼핑몰 미가입 상태로 판단합니다.

* **간편 로그인 회원인 경우**\
  해당 간편 로그인 계정으로 로그인합니다.
* **간편 로그인 회원이 아닌 경우 (미가입 상태)**\
  아래 문서에서 소개 드릴, 간편 로그인 회원가입 로직을 진행합니다.

***

### 🅑 간편 로그인 회원가입

간편 로그인 회원가입에 대해 소개합니다.\
간편 로그인을 통해 신규 가입을 하는 회원의 경우, 아래 화면을 통해 회원가입을 진행합니다.

<div align="left"><figure><img src="/files/aFQMAdkyzZdt7adncExk" alt="" width="375"><figcaption></figcaption></figure></div>

### ⓐ 간편로그인 회원가입 팝업

이전 단계에서 이미 호출한 GET /profile 응답 값을 활용하여 memberName, email, id, 휴대폰번호, 성별, 생일 등을 화면에 노출합니다.

### ⓑ 약관 데이터 호출

약관 내용은 아래 어드민 경로에서 설정할 수 있습니다.&#x20;

```
shop by basic/pro : 설정 > 기본정책 > 약관/개인정보처리방침
shop by premium : 서비스관리 > 약관/개인정보처리방침
```

> [GET /terms](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/search-used-terms)
>
> ► 적용 중인 몰 약관 조회하기\
> 해당 쇼핑몰에 적용 중인 약관을 조회합니다.

> [POST /terms/custom](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/post-search-used-terms)
>
> `약관/개인정보처리방침`에서 `추가 동의 항목`을 추가할 수 있습니다.\
> 추가된 동의항목은 [POST /terms/custom 추가 약관 조회하기](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/post-search-used-terms) API를 통해 확인할 수 있습니다.&#x20;

► 적용 중인 몰 약관 조회하기\
해당 쇼핑몰에 적용 중인 약관을 조회합니다.

아래 약관 데이터를 불러와서 약관 사용 여부가 <mark style="background-color:yellow;">true</mark> 인 항목들에 한하여 화면에 노출합니다.&#x20;

* \[필수] 이용약관 USE
* \[필수] 개인정보 수집 및 이용동의 PI\_COLLECTION\_AND\_USE\_REQUIRED
* \[필수] 만 14세 이상 가입 동의 PI\_14\_AGE
* \[선택] 개인정보 수집 및 이용동의 PI\_COLLECTION\_AND\_USE\_OPTIONAL
* \[선택] 개인정보 처리/위탁에 대한 동의 PI\_PROCESS\_CONSIGNMENT
* \[선택] 개인정보 제 3자 제공에 대한 동의 PI\_THIRD\_PARTY\_PROVISION

### ⓒ 회원가입

해당 버튼 클릭 시 아래 API를 호출하여 간편 로그인 회원가입을 완료합니다.

> [POST /profile/openid](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/post-profile-openid)
>
> ► 오픈 아이디 회원가입 처리하기\
> OpenID 회원 프로필이 등록됩니다.&#x20;

***

### 🅒 카카오 싱크

#### ◼︎ 카카오 싱크 세팅 방법

* [shop by basic/pro 카카오 싱크 신청 가이드](https://workspace.nhn-commerce.com/support/recommendedContents/189897)
* [shop by premium 카카오 싱크 신청 가이드](https://workspace.nhn-commerce.com/support/recommendedContents/186321)