Web 애플리케이션에 다음과 같은 Google 연동을 구현할 기회가 있었습니다.

• Google 계정을 통한 로그인
• Google Calendar에서 일정 가져오기
• 가져온 데이터를 애플리케이션으로 가져오기

설정을 진행하는 과정에서 다음과 같은 점들이 고민되었습니다.

• Google Cloud Console에서는 무엇을 설정해야 하는가
• OAuth의 「내부(Internal)」와 「외부(External)」 중 어느 것을 선택해야 하는가
• OAuth 클라이언트 ID(Client ID)와 클라이언트 시크릿(Client Secret)은 어디에 사용하는가
• 로컬 환경에서는 어떤 URL을 등록해야 하는가
• Google Calendar API나 Google Sheets API는 어떻게 설정하는가
• 운영 환경으로 이전할 때는 무엇을 변경해야 하는가

본 기사에서는 우선 로컬 환경에서 Google 연동을 작동시키는 것을 목적으로 하여, 다음 순서로 설정을 진행합니다.

Google Cloud 프로젝트를 생성
↓
Google Auth Platform에서 OAuth 인증을 설정
...

또한, 이번에는 Google 로그인 구현까지를 범위로 하여 기재하겠습니다.

• 서론
• 이 기사에서 실현하는 것
• 전제 환경
• 1. Google Cloud 프로젝트를 생성한다
• 2. Google Auth Platform에서 OAuth 인증을 설정한다
• 3. OAuth 클라이언트 ID를 생성한다
• 4. 로컬 환경에서의 구현
• 5. 로컬 환경에서 동작 확인을 한다
• 요약

이 기사에서는 다음 처리를 다룹니다.

• Google Cloud 프로젝트를 생성한다
• Google Auth Platform의 초기 설정을 수행한다
• OAuth 클라이언트 ID를 생성한다
• Client ID와 Client Secret을 확인한다
• Google 인증 화면으로 이동한다
• 인가 코드(Authorization Code)를 액세스 토큰(Access Token)으로 교환한다
• Google 계정 정보를 가져온다

본 기사에서는 다음 구성을 예로 듭니다.

먼저, Google 연동 설정을 관리하는 Google Cloud 프로젝트를 생성합니다.

Google Cloud Console을 열고, 화면 상단의 프로젝트 선택 메뉴에서 「새 프로젝트」를 선택합니다.

새 프로젝트 생성 화면에서는 다음 항목을 설정합니다.

sample-google-integration

프로젝트 ID는 입력한 프로젝트 이름을 바탕으로 자동 생성됩니다.

sample-google-integration-123456

프로젝트 ID는 생성 후에 변경할 수 없습니다.

변경하고 싶은 경우에는 프로젝트 생성 전에 「편집」에서 수정합니다.

화면 상단에 프로젝트 수의 상한에 관한 경고가 표시될 수 있습니다.

할당량 내 남은 프로젝트 수는 22개입니다.

이는 Google Cloud 계정 또는 조직에 할당된 프로젝트 수의 상한에 관한 안내입니다.

상한에 도달하지 않았다면 그대로 프로젝트를 생성할 수 있습니다.

상한에 도달한 경우에는 다음과 같은 대응이 필요합니다.

• 불필요한 프로젝트를 삭제한다
• 프로젝트 수 상한 완화를 신청한다
• 다른 조직이나 폴더에서 생성이 가능한지 확인한다

Google Workspace 조직에 소속되어 있는 경우에는 생성할 프로젝트를 연결할 조직을 선택합니다.

부모 리소스에는 프로젝트를 생성할 조직 또는 폴더를 지정합니다.

설정 후 「생성」을 선택합니다.

Google Cloud 프로젝트를 생성했다면, Google Auth Platform 설정을 수행합니다.

Google Auth Platform에서는 Google 로그인이나 Google API 연동에 사용하는 OAuth 인증의 기본 정보를 설정합니다.

최초 설정 시에는 다음 순서로 프로젝트 구성을 진행합니다.

• 앱 정보
• 대상
• 연락처 정보
• 종료

먼저, Google 인증 화면에 표시되는 앱 정보를 입력합니다.

주요 설정 항목은 다음과 같습니다.

앱 이름에는 사용자가 보고 용도를 판단할 수 있는 명칭을 설정합니다.

사내 예약 관리 시스템

개발 중이더라도 test나 sample뿐만 아니라, 어떤 애플리케이션인지 알 수 있는 명칭으로 설정해 두면 관리가 용이해집니다.

개발 중에는 자신의 Google 계정 이메일 주소를 선택해도 문제없습니다.

운영 환경(Production)에서는 다음과 같은 문의용 주소를 설정하면 관리가 쉬워집니다.

support@example.com
system@example.com

입력 후, "다음"을 선택합니다.

다음으로, 애플리케이션을 이용할 수 있는 Google 계정의 범위를 선택합니다.

선택지는 다음 두 가지입니다.

• 내부 (Internal)
• 외부 (External)

동일한 Google Workspace 조직에 소속된 사용자만 이용할 수 있습니다.

다음 조건에 해당한다면 '내부'가 후보가 됩니다.

• 사내용 애플리케이션이다
• 이용자가 전원 동일한 Google Workspace 조직에 소속되어 있다
• 개인 Gmail 계정을 사용하지 않는다
• 사외 사용자에게 공개하지 않는다

내부를 선택한 경우, 조직 외의 Google 계정으로는 원칙적으로 이용할 수 없습니다.

Google 계정을 가진 조직 외의 사용자도 이용할 수 있습니다.

다음과 같은 경우에는 '외부'를 선택합니다.

• 개인 Gmail 계정으로 개발·테스트한다
• 사외 사용자도 이용한다
• 여러 Google Workspace 조직에서 이용한다
• 향후 일반 공개할 가능성이 있다

외부를 선택한 경우, 개발 중에는 테스트 모드(Test mode)로 동작하며, 등록된 테스트 사용자만 이용할 수 있는 설정이 됩니다.

선택 후, "다음"을 누릅니다.

다음으로, Google로부터 OAuth 프로젝트에 관한 연락을 받을 이메일 주소를 입력합니다.

최소 1개의 이메일 주소를 등록해야 합니다.

developer@example.com

사용자 지원 이메일과는 용도가 다릅니다.

개발 중에는 자신의 이메일 주소로 문제없습니다.

운영 시에는 담당자 변경을 고려하여, 관리용 공유 주소를 설정하는 방법도 있습니다.

마지막으로, Google API 서비스의 사용자 데이터에 관한 정책을 확인합니다.

체크박스를 선택하고 "계속"을 누릅니다.

설정 내용에 문제가 없다면 "만들기"를 선택합니다.

이것으로 Google Auth Platform에서의 OAuth 인증 초기 설정이 완료되었습니다.

설정이 완료되면 "OAuth 개요" 화면이 표시됩니다.

초기 상태에서는 다음과 같이 표시됩니다.

이 프로젝트의 OAuth 클라이언트는 아직 구성되지 않았습니다.

이 시점에서는 OAuth 인증의 기본 정보를 등록했을 뿐입니다.

애플리케이션에서 이용할 Client ID와 Client Secret은 아직 발행되지 않았습니다.

이어서 "OAuth 클라이언트 만들기"를 선택합니다.

OAuth 클라이언트 ID는 Google의 OAuth 서버가 애플리케이션을 식별하기 위한 정보입니다.

기사 내에서는 "OAuth 계정"이 아니라, Google Cloud Console의 표기에 맞춰 다음 표현을 사용합니다.

• OAuth 클라이언트
• OAuth 클라이언트 ID
• OAuth 클라이언트 ID 만들기

"애플리케이션 유형"에서 생성할 애플리케이션의 형식을 선택합니다.

백엔드를 가진 Web 애플리케이션의 경우, 다음을 선택합니다.

웹 애플리케이션

React, Next.js, Express, NestJS 등으로 구축한 Web 애플리케이션은 기본적으로 이 유형을 선택합니다.

OAuth 클라이언트를 Google Cloud Console 상에서 식별하기 위한 이름을 입력합니다.

기본값으로 다음과 같은 명칭이 표시될 수 있습니다.

웹 클라이언트 1

그대로 사용할 수도 있지만, 환경을 알 수 있는 명칭으로 변경하면 관리가 용이해집니다.

sample-app-local

운영용 OAuth 클라이언트 (OAuth client)를 별도로 생성하는 경우에는 다음과 같이 구분합니다.

sample-app-local
sample-app-production

이 이름은 Google Cloud Console 상의 관리용이며, 애플리케이션 사용자에게는 표시되지 않습니다.

「승인된 JavaScript 원본 (Authorized JavaScript origins)」에는 브라우저에서 Google 인증을 시작하는 웹 애플리케이션 (Web application)의 URL을 등록합니다.

로컬 환경의 프론트엔드 (Frontend)가 다음 URL인 경우,

[IMG:1]

동일한 URL을 등록합니다.

[IMG:2]

「승인된 리디렉션 URI (Authorized redirect URIs)」에는 Google 인증 완료 후 돌아올 URL을 등록합니다.

백엔드 (Backend)를 3001번 포트에서 실행하는 경우에는 다음과 같이 설정합니다.

[IMG:3]

Next.js나 Auth.js 등을 사용하는 경우에는 다음과 같은 URL이 될 수도 있습니다.

[IMG:4]

사용 중인 인증 라이브러리 (Authentication library)나 애플리케이션 구성에 맞춰 설정합니다.

Google Cloud Console에 등록하는 URI와 프로그램에서 Google로 전송하는 redirect_uri는 완전히 일치시켜야 합니다.

설정이 일치하지 않는 경우, 다음과 같은 에러가 발생합니다.

redirect_uri_mismatch

필요한 항목을 입력했다면 화면 하단의 「만들기」를 선택합니다.

설정 예시는 다음과 같습니다.

설정이 반영되기까지 5분에서 수 시간이 걸릴 수 있습니다.

OAuth 클라이언트를 생성하면 생성 완료 후의 창에 클라이언트 ID (Client ID)가 표시됩니다.

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com

클라이언트 ID는 이후의 애플리케이션 구현에서 사용합니다.

표시된 값을 복사하여 따로 기록해 둡니다.

웹 애플리케이션으로 OAuth 클라이언트를 생성한 경우에는 클라이언트 시크릿 (Client secret)도 발행됩니다.

클라이언트 시크릿은 백엔드에서 Google의 OAuth 서버로 접속할 때 사용하는 비밀 정보입니다.

생성 완료 후의 창에 클라이언트 시크릿이 표시되는 경우가 있습니다.

GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx

단, 생성 완료 창 내에 클라이언트 시크릿이 표시되지 않는 경우도 있습니다.

그 경우에는 생성한 OAuth 클라이언트의 상세 화면에서 확인합니다.

Google Cloud Console
↓
Google Auth Platform
...

OAuth 클라이언트 목록에서 대상 클라이언트를 선택하면 화면 오른쪽 또는 상세 화면에 다음 정보가 표시됩니다.

클라이언트 ID
클라이언트 시크릿

생성 완료 창에 표시되지 않았다면 상세 화면에 표시된 클라이언트 시크릿을 사용합니다.

클라이언트 시크릿은 외부에 공개해서는 안 됩니다.

다음 장소에는 기재하지 않도록 주의하십시오.

• GitHub의 공개 리포지토리 (Public repository)
• React 등의 프론트엔드 코드
• 브라우저에서 확인할 수 있는 환경 변수 (Environment variable)
• API 응답 (API response)
• 애플리케이션 로그 (Application log)

로컬 환경에서는 백엔드의 .env 파일에 설정합니다.

GOOGLE_CLIENT_ID=xxxxxxxxxxxxxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx

.env는 Git 관리 대상에서 제외합니다.

.env
.env.*

Google Cloud Console에서 클라이언트 ID와 클라이언트 시크릿을 확인했다면, 로컬 환경에서 Google 로그인 기능을 구현합니다.

구현 작업은 AI에게 다음과 같이 요청합니다.

다음 정보를 바탕으로 Google 로그인 기능을 구현해 주세요.
【전제】
・프론트엔드는 React 또는 Next.js를 사용하고 있습니다.
...

AI에게 요청할 때는 다음 구현 내용도 함께 지정합니다.

• Google OAuth 연동에 필요한 의존성 패키지(dependency package)를 설치한다
• 환경 변수(environment variables)를 관리하기 위한 패키지를 도입한다
• .env에 클라이언트 ID(Client ID)와 클라이언트 시크릿(Client Secret)을 등록한다
• .env를 .gitignore에 추가한다
• Google OAuth 클라이언트를 초기화한다
• Google 인증 화면으로 전환하는 API를 작성한다
• Google 인증 후의 콜백(callback) API를 작성한다
• 인가 코드(authorization code)를 액세스 토큰(access token)으로 교환한다
• Google 계정의 사용자 정보를 취득한다
• 취득한 이메일 주소, 이름, 프로필 이미지를 애플리케이션 측에서 사용할 수 있는 형태로 정돈한다
• Google 인증 후 자사 애플리케이션의 로그인 상태를 생성한다
• 인증 성공 후 프론트엔드로 리다이렉트(redirect)한다
• 인증 실패 시의 에러 처리를 구현한다
• 클라이언트 시크릿이나 토큰을 로그(log)에 출력하지 않는다
• 클라이언트 시크릿을 프론트엔드로 전달하지 않는다
• 여러 사용자의 인증 정보가 공유되지 않도록 한다
• 필요에 따라 액세스 토큰과 리프레시 토큰(refresh token)을 저장한다
• 로컬 환경에서 Google 로그인 동작 확인을 수행한다

GOOGLE_CLIENT_ID=xxxxxxxxxxxxxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx
GOOGLE_REDIRECT_URI=http://localhost:3001/auth/google/callback
...

Google Cloud Console에 등록한 리다이렉트 URI와 환경 변수의 GOOGLE_REDIRECT_URI는 완전히 일치시켜야 합니다.

Google Cloud Console

GOOGLE_REDIRECT_URI=http://localhost:3001/auth/google/callback

구현 내용을 확인하고, 문제가 없다면 환경을 실행하여 실제로 로그인이 가능한지 확인합니다.

npm run dev

브라우저에서 다음 URL로 접속합니다.

실제로 로그인이 된다면 구현은 완료되었습니다.

외부 테스트 상태에서 구동 중인 경우에는 로그인에 사용하는 Google 계정이 테스트 사용자(test user)로 등록되어 있는지 확인해 주세요.

이번 기사에서는 Google 로그인 구현을 위한 설정 방법을 소개했습니다.

작성하는 애플리케이션의 규모나 대상, 용도에 따라 입력하는 내용이 달라질 가능성이 있으므로, 설정 시에는 자신의 상황에 맞춰 변경해 주시기 바랍니다.

여기까지 읽어주셔서 감사합니다!