[코드스테이츠 PMB14] '카카오로 로그인하기' 절대 못 잃어(feat. 오픈 API 기능과 구조 이해하기)

 

예전... 아주 잠시 참여했던 사이드프로젝트에서 개발자와 PM의 대화에서 'API 확인해봐야할 것 같아요', '그 기능 오픈 API로 어떻게 될 것 같은데' 같이 API 라는 녀석이 자주 출몰했었습니다. 그땐 눈동자 👀 이리저리 👀 굴려가면서 무슨 말이지 이해하려고 여기저기 찾아보다가 어느정도 '아 이런거겠구나!' 대충 아는 척 했지만, 오늘 실제 Opne API 의 기능과 구조를 보면서 차근차근 이해해보려고 합니다.

 

먼저 개념부터 다시 살펴보면요.

API 란 Application Program Interface 로 어플리케이션을 프로그래밍하는데 필요한 인터페이스를 말합니다.

API 의 풀네임을 적으면서 더 헷갈리는데요. 쉽게 말하자면, 은행에서 돈을 입금하려고 합니다. 그러기위해 은행시스템을 다 이해해야할까요? 아닙니다! "먼저 대출창구가 아닌, 입출금 창구를 가는 것" > "입금을 위해 돈, 계좌번호, 신분증 등" 필요한 정보만 알고, 그에 맞춰 행동하면 됩니다. 

 

API는 백엔드에서 개발(혹은 오픈 API 활용)해 프론트엔드와 만나는 지점입니다. 프론트엔드가 요청하고, 백엔드가 응답할 때 그 오작교 다리 역할을 하는 게 API 입니다. 

 

출처: 카카오페이지 기술블로그 https://fe-developers.kakaoent.com/2022/220310-kakaopage-bff/

 

---

 

요즘 카카오톡, 구글, 페이스북과 같이 SNS 계정 로그인 API를 사용하는 서비스가 많습니다. 복잡하고 번거롭던 회원가입 과정을 버튼 몇 번 클릭으로 단축시켜주는 좋은 프로그램입니다. 

 

 

고객입장에서는 간편하게 회원가입/로그인으로 서비스를 이용할 수 있으며, 기업입장에서는 허들을 낮춘 회원가입 서비스로 신규유입을 좀 더 쉽게 유도할 수 있으며 제공되는 API 를 통해 회원 관리가 가능하도록 데이터가 제공됩니다. 

 

출처 : 스페셜경제( http://www.speconomy.com)

출처 : 스페셜경제( http://www.speconomy.com)

한국소비자연맹이 2020년 조사한 바로는 700명 중 93%가 소셜로그인을 사용한 경험한 적이 있다고 하네요. 간편 로그인을 사용하는 이유로는 ▲별도의 회원 가입 등 시간을 줄이기 위해서(51.6%) ▲ID와 비밀번호 등의 계정관리가 번거로워서(25.3%) 등 이용자의 77%는 편리함을 주 이유로 꼽았습니다. 간편로그인은 정말 필요한 필수 서비스인 듯 합니다. 

---

 

 

그렇다면 실제로 카카오톡 로그인 오픈 API 를 탐색해보고 그 기능과 구조를 살펴보며 이해해보려고 합니다. 카카오 디벨롭퍼스 페이지에서 오픈 API 에 대해 자세히 설명해주나 이번 포스팅에서는 기능과 구조, API 기본 정보, 입출력 구조를 정리하겠습니다. 

 

1️⃣ 먼저 developers.kakao.com 로 접속합니다. 

2️⃣ 카카오 로그인 API 를 살펴봅니다. 워낙 자주 사용되는 API 라 그런지 메인페이지에 노출되어있네요. (카카오싱크는 '카카오로그인(회원가입)' + '카카오채널추가' + '카카오 알림톡' 까지 연동해 구현하는 API 입니다.) 

 

카카오 로그인의 기능과 구조

 

출처: 카카오 디벨롭퍼스

 

카카오 로그인이 제공하는 핵심기능은 크게 세 가지 입니다. 

1) 카카오톡 또는 카카오계정으로 간편한 사용자 로그인

2) 사용자 로그인 시 서비스의 카카오톡 채널 추가 유도

3) 사용자 고유 식별자 및 인증 정보, 기본적인 사용자 정보인 프로필과 이메일 데이터 제공

 

 

카카오 로그인에서 사용자와 앱의 연결 과정은 아래와 같습니다. 

 

출처: 카카오 디벨롭퍼스

이때 많은 경우의 수가 있습니다. 가입/로그인 하고자 하는 서비스에 이미 입력된 사용자 정보가 중복되는 경우 카카오 로그인 연동 의사 여부를 물어봐야합니다. 기존 서비스에 가입한 전화번호/이메일을 전체 다 보여줄 것인가 일부만 보여줄 것인가 등 정책도 필요합니다. 만약 중복되는 경우가 없다면 신규 가입이 됩니다. 

 

카카오 로그인의 API 기본 정보, 입출력 구조

아래는 REST API 를 사용한 카카오 로그인 과정입니다. 크게 1️⃣ 인가 코드 받기 2️⃣ 토큰 받기 3️⃣ 사용자 로그인 처리(로그인 완료) 총 세 step 으로 나뉩니다. 

 

1️⃣ 인가 코드 받기

카카오 로그인 동의 화면을 호출하고, 사용자 동의를 거쳐 인가 코드를 발급합니다. <GET>으로 요청합니다. 

GET /oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code HTTP/1.1
Host: kauth.kakao.com

 

카카오톡으로 로그인 혹은 카카오계정 정보 입력 후 로그인 > 사용자 동의 > 인가 코드 발급 Redirect URI 로 302 Redirect 

 

1) 인가 코드 받기 요청의 매개변수

Name	Type	Description	Required
client_id	String	앱 REST API 키 [내 애플리케이션] > [앱 키]에서 확인 가능	O
redirect_uri	String	인가 코드를 전달받을 서비스 서버의 URI [내 애플리케이션] > [카카오 로그인] > [Redirect URI]에서 등록	O
response_type	String	code로 고정	O
scope	String	추가 항목 동의 받기 요청 시 사용 사용자에게 동의 요청할 동의 항목 ID 목록 동의 항목의 ID는 사용자 정보 또는 [내 애플리케이션] > [카카오 로그인] > [동의 항목]에서 확인 가능 쉼표(,)로 구분해 여러 개 전달 가능 주의: OpenID Connect를 사용하는 앱의 경우, scope 파라미터 값에 openid를 반드시 포함해야 함, 미포함 시 ID 토큰이 재발급되지 않음 (참고: scope 파라미터)	X
prompt	String	카카오톡에서 자동 로그인, 기존 로그인 여부와 상관없이 로그인 요청 시 사용 동의 화면 요청 시 추가 상호작용을 요청하고자 할 때 전달하는 파라미터 쉼표(,)로 구분된 문자열 값 목록으로 전달 다음 값 사용 가능: login: 기존 사용자 인증 여부와 상관없이 사용자에게 카카오계정 로그인 화면을 출력하여 다시 사용자 인증을 수행하고자 할 때 사용, 카카오톡 인앱 브라우저에서는 이 기능이 제공되지 않음 none: 사용자에게 동의 화면과 같은 대화형 UI를 노출하지 않고 인가 코드 발급을 요청할 때 사용, 인가 코드 발급을 위해 사용자의 동작이 필요한 경우 에러 응답 전달	X
service_terms	String	약관 선택해 동의 받기 요청 시 사용 동의받을 약관 태그 목록 약관 태그는 [내 애플리케이션] > [간편가입]에서 확인 가능 쉼표(,)로 구분된 문자열 값 목록으로 전달	X
state	String	카카오 로그인 과정 중 동일한 값을 유지하는 임의의 문자열(정해진 형식 없음) Cross-Site Request Forgery(CSRF) 공격으로부터 카카오 로그인 요청을 보호하기 위해 사용 각 사용자의 로그인 요청에 대한 state 값은 고유해야 함 인가 코드 요청, 인가 코드 응답, 토큰 발급 요청의 state 값 일치 여부로 요청 및 응답 유효성 확인 가능	X
nonce	String	OpenID Connect를 통해 ID 토큰을 함께 발급받을 경우, ID 토큰 재생 공격을 방지하기 위해 사용 ID 토큰 유효성 검증 시 대조할 임의의 문자열(정해진 형식 없음)	X

2) 인가 코드 받기 요청의 응답

Name	Type	Description	Required
code	String	토큰 받기 요청에 필요한 인가 코드	X
state	String	요청 시 전달한 state 값과 동일한 값	X
error	String	인증 실패 시 반환되는 에러 코드	X
error_description	String	인증 실패 시 반환되는 에러 메시지	X

3) 인가 코드 받기 요청 예시

 

요청(Request)

https://kauth.kakao.com/oauth/authorize?response_type=code&client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}

응답(Respond) - 1 : 사용자가 [동의하고 계속하기] 선택, 로그인 진행

HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?code=${AUTHORIZE_CODE}

응답(Respond) - 2 : 로그인 취소

HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?error=access_denied&error_description=User%20denied%20access

 

2️⃣ 토큰 받기

인가 코드로 토큰 발급을 요청합니다. 인가 코드 받기만으로는 카카오 로그인이 완료되지 않으며, 토큰 받기까지 마쳐야 카카오 로그인을 정상적으로 완료할 수 있습니다. <POST> 로 요청합니다.

POST /oauth/token HTTP/1.1
Host: kauth.kakao.com
Content-type: application/x-www-form-urlencoded;charset=utf-8

 

1) 토큰 받기 요청의 매개변수

Name	Type	Description	Required
grant_type	String	authorization_code로 고정	O
client_id	String	앱 REST API 키 [내 애플리케이션] > [앱 키]에서 확인 가능	O
redirect_uri	String	인가 코드가 리다이렉트된 URI	O
code	String	인가 코드 받기 요청으로 얻은 인가 코드	O
client_secret	String	토큰 발급 시, 보안을 강화하기 위해 추가 확인하는 코드 [내 애플리케이션] > [보안]에서 설정 가능 ON 상태인 경우 필수 설정해야 함	X

2) 토큰 받기 요청의 응답

Name	Type	Description	Required
token_type	String	토큰 타입, bearer로 고정	O
access_token	String	사용자 액세스 토큰 값	O
id_token	String	ID 토큰 값 OpenID Connect 확장 기능을 통해 발급되는 ID 토큰, Base64 인코딩 된 사용자 인증 정보 포함 제공 조건: OpenID Connect가 활성화 된 앱의 토큰 발급 요청인 경우 또는 scope에 openid를 포함한 추가 항목 동의 받기 요청을 거친 토큰 발급 요청인 경우	X
expires_in	Integer	액세스 토큰과 ID 토큰의 만료 시간(초) 참고: 액세스 토큰과 ID 토큰의 만료 시간은 동일	O
refresh_token	String	사용자 리프레시 토큰 값	O
refresh_token_expires_in	Integer	리프레시 토큰 만료 시간(초)	O
scope	String	인증된 사용자의 정보 조회 권한 범위 범위가 여러 개일 경우, 공백으로 구분 참고: OpenID Connect가 활성화된 앱의 토큰 발급 요청인 경우, ID 토큰이 함께 발급되며 scope 값에 openid 포함	X

3) 토큰 받기 요청 예시

 

요청(Request)

curl -v -X POST "https://kauth.kakao.com/oauth/token" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "grant_type=authorization_code" \
 -d "client_id=${REST_API_KEY}" \
 --data-urlencode "redirect_uri=${REDIRECT_URI}" \
 -d "code=${AUTHORIZE_CODE}"

응답(Respond) - 1 : 성공

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "token_type":"bearer",
    "access_token":"${ACCESS_TOKEN}",
    "expires_in":43199,
    "refresh_token":"${REFRESH_TOKEN}",
    "refresh_token_expires_in":25184000,
    "scope":"account_email profile"
}

응답(Respond) - 2 : 성공, OpenID Connect를 활성화한 앱, ID 토큰 포함

HTTP/1.1 200 OK
{
    "token_type": "bearer",
    "access_token": "${ACCESS_TOKEN}",
    "id_token": "${ID_TOKEN}",
    "expires_in": 7199,
    "refresh_token": "${REFRESH_TOKEN}",
    "refresh_token_expires_in": 86399,
    "scope": "profile_image openid profile_nickname"
}

응답(Respond) - 3 : ID 토큰 페이로드 예시

{
  "aud": "${APP_KEY}",
  "sub": "${USER_ID}",
  "auth_time": 1661967952,
  "iss": "https://kauth.kakao.com",
  "exp": 1661967972,
  "iat": 1661967952,
  "nickname": "JordyTest",
  "picture": "http://yyy.kakao.com/.../img_110x110.jpg",
  "email": "jordy@kakao.com"
}

 

---

 

카카오 디벨로퍼 페이지에서는 REST API 테스트 도구를 제공합니다. 도구로 요청과 응답 구성을 확인할 수 있네요! 카카오 로그인에서 확인이 가능한 요청과 응답은 아래와 같습니다.

 

▲로그아웃, ▲연결하기, ▲연결 끊기, ▲토큰 정보 보기, ▲사용자 정보 가져오기, ▲사용자 정보 저장하기, ▲사용자 목록 가져오기, ▲여러 사용자 정보 가져오기, ▲동의 내역 확인하기, ▲동의 철회하기, ▲OIDC: ID 토큰 정보 보기 로 요청할 수 있습니다. 정보를 생성하고, 읽어오는 요청은 <POST> 와 <GET> 명령으로 합니다.

 

<POST>: 로그아웃, 동의 철회하기
<GET>: 연결하기, 연결 끊기, 토큰 정보 보기, 사용자 정보 가져오기, 사용자 정보 저장하기, 사용자 목록 가져오기, 여러 사용자 정보 가져오기, 동의 내역 확인하기, OIDC: ID 토큰 정보 보기 

 

▲로그아웃이나 ▲동의 철회하기는 <PUT>이나 <DELETE>가 아니라 왜 <POST> 명령을 쓰는 걸지 궁금했는데 페어분들의 도움으로 조금 이해했답니다. 로그아웃 혹은 동의 철회하기는 기존 사용자 정보를 삭제하거나 수정(사용자 정보에 변동이 없음)이 아니며 상태의 변화이기 때문에 서버에 기록이 되어야합니다. 그렇기 때문에 <POST>로 명령해야하는 것입니다. 아래 댓글에 너무 찰떡같은 설명이 있어 본문에 박제합니다. 최고😉

 

 

로그아웃 및 동의 철회하기는 데이터가 아예 사라져선 안되기 때문에 DELETE는 적용이 안될 것 같아요. 로그아웃 되어도 데이터가 지워지는 것이 아닌 로그아웃 된 기록이 남아있는 것처럼요! (유어클래스에 입실/퇴실 기록이 모두 쌓여있듯)
로그인, 로그아웃, 동의 철회하기 등 사용자가 하는 행동 데이터가 모두 기록되어야 하기 때문에 POST가 쓰였을 것 같아요 :)
모든 기록이 축적되어야 데이터 분석시에도 용이하구요! PUT은 일부분 수정되는 것이기에 사용되지 않는 것 아닐까요? (PUT은 회원의 정보 일부분 수정에 적용될 것 같아요) ex. 어떤 USER가 언제 어떤 기기로 로그인/로그아웃 했는지

 

또 참고하기 좋은 자료도 이번주 페어님께서 첨부해주셨습니다.

로그아웃 처리 시 Post 를 쓰는 이유가 있을까요?

[Web] REST API 란? ( GET과 POST의 차이 )

 

 

 

카카오에서 아래 디자인 가이드도 제공하고 있습니다. 카카오의 BI(Brand Identity)를 해치지 않는 범위 내에서 제작도 가능하기도 합니다. 

 

 

---

카카오 로그인 API 활용방안

실은 소셜 네트워킹 서비스 로그인은 너무 일상화되어있으며, 사용자 유입의 허들을 낮추기 위해 꼭 필요한 API 입니다. 사용자의 편의를 고려한 로그인, 그리고 카카오에 기존 등록된 회원 정보를 활용해 다양한 서비스에 연계할 수 있다는 장점이 있습니다. 기본적인 사용자 정보(프로필, 이메일) 데이터를 토대로 고객 세그먼트를 나누어 마케팅 전략을 다르게 모색할 수 있을 듯 합니다. 

 

 

출처: 카카오 디벨롭퍼스

 

 

오픈 API가 제공하는 서비스의 범위와 한계

오픈 API 를 사용함으로써 API 을 개발하는 비용과 시간을 줄일 수 있습니다. 개발하고자 하는 환경에 맞춰 개발가이드를 제공합니다. 이렇게 개발할 때 편리하게 제공받고, 고객은 원하는 정보를 쉽게 얻을 수 있고 또 제공하는 공급자는 자사 제품을 쓰도록 유도하기에 모두 윈-윈-윈 인데요. 

 

하지만 API가 손상, 노출 혹은 해킹 시에 데이터가 유출될 리스크도 존재합니다. 개인 정보 노출은 심각한 이슈로 트래픽을 분석하고 신뢰할 수 있는 토큰을 사용해야합니다. 

 

 

---

나가며...

API 에 대해서 강의도 듣고, 이것저것 글도 찾아보았더니 이해에 어느정도 윤곽은 잡힌 듯 합니다. 요청에 있어서 입력값이 무엇이냐에따라 응답이 달라지는 것도 얼추 감을 잡았고요! 앞으로 실무에서 몸소 체득하는 과정이 기대가 됩니다! 

 

 

 

 

 

 

참고자료

https://www.youtube.com/watch?v=Re2R2rid1K4 

https://brunch.co.kr/@second-space/8

SNS 로그인 개발 알쓸신잡

https://shinetech.tistory.com/16

[잇잇 E.01] API(Application Programming Interface) | API 연동 개념 및 사용하는 이유, 장점&단점 / OpenAPI 호출

http://www.speconomy.com/news/articleView.html?idxno=230186 

소비자연맹 “간편한 ‘소셜로그인’…이용자 4명 중 3명 개인정보 유출 우려” - 스페셜경제