전체 스택 인증 앱을 만드는 방법

대부분의 웹 애플리케이션에는 회원가입 및 로그인 기능이 필요합니다. 하지만 초보자에게는 이 작업이 어려울 수 있습니다. 심지어 전문 개발자들도 처음부터 인증을 처리하기 위해 외부 서비스를 사용하는 것을 선호합니다. 풀스택 인증 흐름에 대해 이야기할 때, 이는 프론트엔드에서 사용자 로그인 및 등록을 설정하고 백엔드 API를 보호하는 것을 의미합니다. 따라서 두 부분 모두 작업해야 합니다.

이 게시물은 Apache APISIX, Authgear, 그리고 OpenID Connect (OIDC)를 사용하여 풀스택 인증 앱을 구축하는 방법을 안내합니다. 프로젝트의 소스 코드는 GitHub에서 찾을 수 있습니다. 앱을 빠르게 시작하려면 저장소를 클론하고 README.md 파일에 제공된 단계에 따라 코드 샘플을 실행하면 됩니다.

학습 목표

이 콘텐츠는 백엔드와 프론트엔드 모두에서 인증을 설정하는 방법을 모두에게 보여주기 위한 것입니다. 또한 초보자와 경험 많은 개발자 모두가 풀스택 개발자가 되고자 할 때 도움을 주기 위해 설계되었습니다.

APISIX, Authgear, OIDC의 인증에서의 역할

가이드를 시작하기 전에 사용할 도구들을 간단히 소개하겠습니다.

**OIDC (OpenID Connect)**는 OAuth 2.0 프로토콜 위에 구축된 간단한 ID 계층입니다. 이를 통해 타사 애플리케이션은 사용자를 확인하고 기본 프로필 정보를 표준화된 방식으로 얻을 수 있습니다.
APISIX는 가장 인기 있는 오픈소스 API 게이트웨이 중 하나입니다. 이는 API 관리뿐만 아니라 이러한 API의 보안과 보호를 보장하기 위해 설계되었습니다. 보안 아스날에서 가장 두드러진 기능 중 하나는 플러그인을 사용한 OIDC 지원입니다.
Authgear는 웹 및 모바일 애플리케이션을 위한 매우 적응 가능한 IDaaS(Identity-as-a-Service) 플랫폼입니다. 사용자는 내장된 UI 인터페이스를 통해 애플리케이션에 로그인할 수 있습니다(사용자 등록 및 로그인 흐름을 위한 UI를 구축할 필요가 없음). 이는 사용자에게 안전하고 표준 기반의 로그인 경험을 제공하며, 이를 통해 자신의 브랜딩과 다양한 인증 방법(이메일, 소셜 로그인, 패스워드리스, 생체 인증, 일회용 비밀번호(OTP)를 SMS/WhatsApp로, 그리고 다중 인증(MFA) 등)을 사용자 정의할 수 있습니다. 이는 OpenID Connect(OIDC)와 OAuth 2.0을 사용하여 사용자를 식별하고 보호된 리소스에 대한 권한을 부여합니다.

인증 워크플로우

다음은 인증 프로세스의 상위 수준 아키텍처 다이어그램입니다:

OIDC, APISIX 및 Authgear를 사용한 인증 워크플로우

다이어그램에 표시된 단계는 아래에 자세히 설명되어 있습니다:

위 다이어그램에서 클라이언트는 모든 웹 애플리케이션, API 게이트웨이는 APISIX, ID 제공자는 Authgear, 업스트림은 백엔드 API입니다.

웹 앱은 React, Vue 또는 Angular로 구축된 단일 페이지 앱(SPA)부터 Express, NextJS 및 유사한 플랫폼을 사용하여 제작된 표준 웹 애플리케이션까지 다양한 형태를 취할 수 있습니다. 웹 앱은 프론트엔드가 있는 클라이언트 앱으로, 클라이언트 ID와 클라이언트 비밀을 포함한 요청을 ID 제공자(Authgear)에 보내 JSON Web Tokens (JWT)와 같은 액세스 토큰을 수집합니다.
제공된 자격 증명이 올바르면 Authgear는 웹 앱에 JWT 토큰으로 응답합니다. Authgear 포털에서 앱을 위한 사용자를 원하는 만큼 생성할 수 있으며, 사용자는 Authgear가 호스팅하는 UI 페이지를 사용하여 로그인할 수 있습니다.
JWT 토큰을 획득한 후, 클라이언트는 액세스 토큰과 함께 API 게이트웨이(APISIX)에 요청을 보내고, 백엔드 API는 게이트웨이에 의해 보호됩니다.
요청을 처리하기 전에 APISIX는 제공된 토큰이 유효하고 만료되지 않았으며 요청된 데이터 또는 서비스에 대한 올바른 범위를 가지고 있는지 확인해야 합니다. APISIX가 토큰을 로컬에서 검증할 수 없는 경우, 토큰 인트로스펙션 요청을 Authgear 인증 서버에 보냅니다. 이 요청은 일반적으로 서버의 introspection 엔드포인트에 이루어집니다.
Authgear는 인트로스펙션 요청을 받아 처리합니다. 서버는 토큰의 유효성, 만료 및 관련 범위를 확인하기 위해 기록을 검사하고, 토큰의 상태를 결정한 후 APISIX에 응답합니다.
Authgear의 토큰 인트로스펙션 응답을 기반으로 APISIX는 정보에 입각한 결정을 내릴 수 있습니다. 토큰이 유효하면 요청을 백엔드 API로 전달하고, 그렇지 않으면 클라이언트의 요청을 거부하고 권한 없는 HTTP 상태 코드를 반환합니다.
APISIX는 백엔드 API의 응답을 요청된 리소스와 함께 전송합니다.

APISIX, Authgear, OIDC를 사용한 풀스택 인증 앱

데모 프로젝트를 위해 Docker를 사용하여 단일 명령으로 3가지 구성 요소(백엔드, API 게이트웨이, 프론트엔드)를 설치하고 실행했습니다. 프론트엔드 웹 앱을 위해 ExpressJS를 사용하여 단일 페이지 앱을 localhost:3000에서 호스팅했습니다. APISIX 게이트웨이는 localhost:9080에서 접근할 수 있으며, 백엔드 API(Python, Java, NodeJS 등으로 구축한 모든 API가 될 수 있음)는 localhost:9081에 설정되었습니다.

사전 요구 사항

시작하기 전에 다음이 필요합니다:

무료 Authgear 계정. 아직 계정이 없다면 가입하세요.
모든 서비스를 설치하기 위해 Docker가 사용됩니다.

Authgear 구성

Authgear 서비스를 사용하려면 Authgear 대시보드에서 애플리케이션을 설정하고 Authgear OIDC 클라이언트 정보를 얻어야 합니다. 이 설정을 통해 Authgear의 사용자는 Authgear에 의해 인증된 후 웹 애플리케이션에 자동으로 로그인할 수 있습니다.

1단계: Authgear에서 애플리케이션 생성

애플리케이션을 설정하려면 Authgear 포털 UI로 이동하여 왼쪽 탐색 바에서 애플리케이션을 선택하세요. 인터랙티브 선택기를 사용하여 새로운 Authgear OIDC 클라이언트 애플리케이션을 생성하세요.

Authgear에서 애플리케이션 생성

2단계: 앱 자격 증명 복사

Authgear의 모든 애플리케이션에는 애플리케이션 코드가 Authgear API를 호출하는 데 사용할 고유한 영숫자 CLIENT ID와 CLIENT Secret이 할당됩니다. 생성된 Authgear ISSUER(예: https://example-auth.authgear-apps.com), CLIENT ID, CLIENT SECRET을 출력에서 기록하세요. 다음 단계에서 웹 앱 구성에 이러한 값을 사용할 것입니다.

앱 자격 증명 복사

3단계: 리디렉션 URI 구성

애플리케이션의 승인된 리디렉션 URI는 사용자가 인증을 완료한 후 Authgear가 리디렉션할 URL입니다. 이 경우, 프론트엔드의 홈 페이지가 될 것이며 http://localhost:3000에서 실행됩니다.

승인된 리디렉션 URI 필드에 http://localhost:3000을 설정하세요. 설정하지 않으면 사용자가 로그인 후 애플리케이션으로 돌아오지 않습니다.

4단계: 액세스 토큰 활성화

또한 앱 구성의 액세스 토큰 섹션에서 JWT를 액세스 토큰으로 발급 옵션을 활성화하세요:

Authgear에서 액세스 토큰 활성화

5단계: 로그인 방법 선택

Authgear 앱을 생성한 후, 로그인 페이지에서 사용자가 어떻게 인증할지 선택하세요. 인증 탭에서 로그인 방법으로 이동하여 이메일, 모바일, 소셜, 사용자 이름만 사용하거나 지정한 사용자 정의 방법 등 다양한 옵션 중에서 로그인 방법을 선택할 수 있습니다. 이 데모에서는 사용자가 계정을 등록하고 이메일을 사용하여 로그인하도록 요청하는 이메일+패스워드리스 방식을 선택했습니다. 사용자는 이메일로 일회용 비밀번호(OTP)를 받고 코드를 확인하여 앱을 사용할 수 있습니다.

로그인 방법 선택

데모 프로젝트 설정 및 실행

Authgear가 성공적으로 구성되었으므로 이제 GitHub 저장소를 가져와 환경 변수를 구성하고 서비스를 실행할 수 있습니다:

먼저 프로젝트를 로컬 머신에 클론하세요:

git clone https://github.com/Boburmirzo/apisix-authgear-oidc-full-stack-auth.git

프로젝트 디렉토리를 현재 작업 디렉토리로 만드세요:

cd apisix-authgear-oidc-full-stack-auth

프로젝트의 루트 디렉토리에서 Docker compose yaml 파일이 있는 위치에 .env 파일을 생성하고 다음 환경 변수를 추가하세요:

CLIENT_ID={AUTHGEAR_APP_CLIENT_ID}
CLIENT_SECRET={AUTHGEAR_APP_CLIENT_SECRET}
ISSUER={AUTHGEAR_ISSUER}
REDIRECT_URI=http://localhost:3000

중괄호 안의 값을 위의 Authgear 구성 섹션에서 얻은 Authgear 앱 설정 값(예: Issuer, ClientId, ClientSecret)으로 대체하세요.

환경 파일을 추가한 후, 루트 디렉토리에서 docker compose up 명령을 실행하세요.

인증 흐름 테스트

데모를 위해 Docker를 사용하여 단일 명령으로 3가지 구성 요소(백엔드, API 게이트웨이, 프론트엔드)를 설치하고 실행했습니다. 프론트엔드 웹 앱을 위해 ExpressJS를 사용하여 단일 페이지 앱을 localhost:3000에서 호스팅했습니다. APISIX 게이트웨이는 localhost:9080에서 접근할 수 있으며, 백엔드 API(Python, Java, NodeJS 등으로 구축한 모든 API가 될 수 있음)는 localhost:9081에 설정되었습니다.

Authgear 로그인 페이지