Gnuboard7/docs/frontend/auth-system.md

인증 시스템 (AuthManager)

그누보드7 프론트엔드 인증 시스템 가이드

---

TL;DR (5초 요약)

1. AuthManager: 싱글톤 인증 상태 관리 클래스
2. 토큰 자동 갱신: 401 응답 시 자동 처리
3. 컨텍스트 분리: admin/user 분리 관리
4. 로그인: login 핸들러 또는 AuthManager.login()
5. 이벤트: auth:login, auth:logout 이벤트 구독 가능

---

목차

• 개요
• 인증 흐름
• 인증 타입 판단
• API 엔드포인트
• 토큰 자동 갱신
• 로그인 시 로케일 처리
• 사용 예시
• 이벤트 처리
• 주의사항
• 관련 문서

---

개요

AuthManager는 프론트엔드 인증 상태 관리를 담당하는 싱글톤 클래스입니다.

위치: /resources/js/core/auth/AuthManager.ts

주요 기능:

• 인증 상태 확인 및 관리
• 토큰 자동 갱신 (401 응답 시)
• 로그인/로그아웃 처리
• 관리자/일반사용자 컨텍스트 분리
• 로그인 시 사용자 언어 설정 자동 반영

---

인증 흐름

사용자가 /admin/dashboard 접근
         ↓
Router.navigateToCurrentPath()
         ↓
auth_required: true 확인
         ↓
auth_type 결정 (명시 또는 경로 기반)
         ↓
AuthManager.checkAuth(authType)
         ↓
    ┌────┴────┐
    ↓         ↓
 인증됨    미인증
    ↓         ↓
 렌더링    로그인 페이지로 리다이렉트
           (?redirect 파라미터 포함)

---

인증 타입 판단

auth_type이 라우트에 명시되지 않은 경우 경로 기반으로 자동 판단:

// Router.ts
private getAuthType(route: Route, pathname: string): AuthType {
  // 1. 라우트에 명시된 경우 사용
  if (route.auth_type) {
    return route.auth_type;
  }

  // 2. 경로 기반 자동 판단
  if (pathname.startsWith('/admin')) {
    return 'admin';
  }

  return 'user';
}

우선순위:

1. 라우트에 명시된 auth_type 값
2. 경로 기반 자동 판단 (/admin → admin, 그 외 → user)

---

API 엔드포인트

구분	로그인	인증번호 확인	인증번호 재발송	사용자 정보	로그아웃	토큰 갱신
관리자	/auth/admin/login	/auth/admin/login/two-factor	/auth/admin/login/two-factor/resend	/admin/auth/user	/admin/auth/logout	/admin/auth/refresh
일반사용자	/auth/login	/auth/login/two-factor	/auth/login/two-factor/resend	/user/auth/user	/user/auth/logout	/user/auth/refresh

공통:

• 로그인 엔드포인트는 관리자/일반사용자가 다릅니다 (AuthConfig.loginEndpoint)
• updateConfig({ loginEndpoint }) 로 템플릿이 재정의한 값이 그대로 사용됩니다
• 인증 후 작업은 각각 분리된 엔드포인트 사용
• API 인증은 Bearer 토큰 전용 (세션 기반 인증 미사용)
• 401 응답 시 서버가 세션 쿠키 만료 헤더를 자동 전송 (잔존 쿠키 정리)

---

토큰 자동 갱신

ApiClient의 응답 인터셉터에서 401 응답 시 자동으로 토큰 갱신을 시도합니다:

// ApiClient.ts 응답 인터셉터
if (error.response?.status === 401 && !originalRequest._retry) {
  originalRequest._retry = true;

  const authManager = AuthManager.getInstance();
  const refreshed = await authManager.refreshToken();

  if (refreshed) {
    // 토큰 갱신 성공, 원래 요청 재시도
    const token = this.getToken();
    originalRequest.headers.Authorization = `Bearer ${token}`;
    return this.client(originalRequest);
  }

  // 갱신 실패 시 로그아웃 처리
}

동시 갱신 방지: 여러 요청이 동시에 401을 받아도 하나의 갱신 요청만 수행

---

로그인 시 로케일 처리

로그인 성공 시 사용자의 language 설정을 자동으로 반영합니다:

로그인 API 응답 수신
         ↓
user.language 확인
         ↓
현재 g7_locale과 비교
         ↓
    ┌────┴────┐
    ↓         ↓
  동일      다름
    ↓         ↓
  skip    localStorage 저장
            ↓
          TemplateApp.changeLocale() 호출
            ↓
          UI 즉시 업데이트

구현 위치: AuthManager.establishSession() — 일반 로그인과 2단계 인증 완료가 같은 후처리를 공유합니다. 갈라지면 한쪽 경로에서만 로케일 전환이나 이벤트 발행이 빠집니다.

// 로케일 변경 감지 및 처리
const userLanguage = user.language;
const currentLocale = localStorage.getItem('g7_locale');
const localeChanged = userLanguage && userLanguage !== currentLocale;

if (userLanguage) {
  localStorage.setItem('g7_locale', userLanguage);
}

// 로케일이 변경된 경우 TemplateApp 재초기화
if (localeChanged && window.__templateApp) {
  window.__templateApp.changeLocale(userLanguage);
}

주요 포인트:

• 사용자의 DB language 값을 g7_locale localStorage에 저장
• 로케일이 변경된 경우에만 changeLocale() 호출 (불필요한 재초기화 방지)
• SPA 환경에서도 새로고침 없이 즉시 반영

---

2단계 인증 로그인 (engine-v1.65.0+)

보안 환경설정의 「2단계 인증」이 켜져 있으면 서버는 비밀번호가 맞아도 토큰을 발급하지 않고 인증 요청(challenge)만 돌려줍니다. 즉, 로그인 응답은 두 가지 형태의 200 입니다.

export type LoginResult =
  | { status: 'authenticated'; user: AuthUser }
  | { status: 'two_factor_required'; challenge: TwoFactorChallenge };

AuthManager.login() 은 이 판별 유니온을 돌려줍니다. 한 형태만 가정하면 challenge 응답에서 data.user.* 접근이 예외가 되고, data.token(undefined)을 저장하면 "undefined" 문자열이 남아 이후 모든 요청이 401 로 튕깁니다.

메서드	하는 일
login(type, credentials, options?)	비밀번호 확인. LoginResult 반환
completeTwoFactor(type, { challengeId, code }, options?)	인증번호 확인 → 토큰 발급 → AuthUser 반환
resendTwoFactor(type, { challengeId }, options?)	인증번호 재발송 → 새 TwoFactorChallenge 반환

레이아웃에서는 액션 핸들러 login / loginTwoFactor / loginTwoFactorResend 로 사용합니다 (→ actions-handlers-ui.md).

레이아웃 작성 규칙

• 1단계 블록과 2단계 블록의 if 는 상보적이어야 합니다. 두 블록이 동시에 보이면 인증번호 단계에서 이메일·비밀번호가 함께 노출됩니다.
• 제출 시퀀스의 login 과 loginTwoFactor 도 상호배타 if 를 갖습니다. if 가 빠지면 인증번호 단계에서 Enter 를 누를 때 새 challenge 가 발급되어 흐름이 깨집니다. if 는 시퀀스 시작 시점 스냅샷으로 평가되므로 한 번의 제출에 정확히 하나만 실행됩니다.
• 같은 시퀀스·onSuccess 안에서 방금 저장한 상태를 다시 읽지 않습니다. 그 자리의 상태는 아직 갱신 전이므로 {{response.*}} 만 사용합니다.
• 인증번호 입력은 자동바인딩이 아니라 value + onChange 로 상태가 값을 소유해야 합니다 — 재발송 시 입력값을 비워야 하기 때문입니다.
• 인증 단계 상태는 화면을 떠나도 남으므로, 로그인 화면 진입 시 init_actions 에서 초기화합니다.

재발송의 계약

서버는 기존 challenge 를 취소하고 새로 발행합니다. 유효한 코드를 여러 개 동시에 살려 두면 대입 시도의 표적이 넓어지기 때문입니다. 따라서 클라이언트는 응답의 challenge_id 로 반드시 교체하고 입력란을 비워야 합니다.

---

사용 예시

routes.json 설정

{
  "routes": [
    {
      "path": "/admin/login",
      "layout": "admin_login",
      "auth_required": false
    },
    {
      "path": "/admin/dashboard",
      "layout": "admin_dashboard",
      "auth_required": true
    },
    {
      "path": "/profile",
      "layout": "user_profile",
      "auth_required": true,
      "auth_type": "user"
    }
  ]
}

로그인 후 리다이렉트

// 로그인 성공 후 원래 페이지로 이동
const authManager = AuthManager.getInstance();
const redirectUrl = authManager.getRedirectUrl('admin');
window.location.href = redirectUrl; // URL 파라미터의 redirect 값 또는 기본 경로

---

이벤트 처리

AuthManager는 이벤트 기반으로 인증 상태 변경을 알립니다:

const authManager = AuthManager.getInstance();

// 인증 상태 변경 감지
authManager.on('authStateChange', (state) => {
  console.log('Auth state:', state.isAuthenticated, state.user);
});

// 로그아웃 감지
authManager.on('logout', () => {
  console.log('User logged out');
});

사용 가능한 이벤트:

• authStateChange: 인증 상태가 변경될 때
• logout: 사용자가 로그아웃할 때

---

주의사항

로그인 페이지 설정

로그인 페이지는 반드시 auth_required: false로 설정
   → 그렇지 않으면 무한 루프 발생

// ✅ DO
{
  "path": "/admin/login",
  "layout": "admin_login",
  "auth_required": false
}

// ❌ DON'T - 무한 루프 발생
{
  "path": "/admin/login",
  "layout": "admin_login",
  "auth_required": true
}

보안 규칙

• 리다이렉트 URL: 같은 도메인 경로만 허용 (외부 URL 차단)
• 토큰 저장: localStorage의 auth_token 키에 저장

토큰 관리

// 토큰 저장 위치
localStorage.getItem('auth_token');  // 토큰 조회
localStorage.setItem('auth_token', token);  // 토큰 저장
localStorage.removeItem('auth_token');  // 토큰 삭제 (로그아웃)

---

인증 설정 커스터마이징 (AuthManager.updateConfig)

템플릿이 코어 디폴트 로그인 경로(/login, /admin/login)와 다른 경로를 사용하는 경우, **템플릿 부트스트랩(initTemplate)**에서 AuthManager.updateConfig 를 호출해 사이트 단위로 오버라이드한다. IDV launcher 등록 패턴(template-idv-bootstrap.md)과 동일한 "코어는 슬롯, 템플릿이 채움" 철학.

시그니처

AuthManager.getInstance().updateConfig(
  type: 'user' | 'admin',
  partial: Partial<AuthConfig>
): void

AuthConfig 의 갱신 가능 필드: loginPath, defaultPath, loginEndpoint, logoutEndpoint, refreshEndpoint, userEndpoint, unauthorizedRedirect.

호출 위치 — 템플릿 부트스트랩만

// templates/_bundled/{template-id}/src/initTemplate.ts (예시)
import { AuthManager } from '@core/auth/AuthManager';

export function initTemplate() {
  // 사이트 단위 로그인 경로 커스터마이징
  AuthManager.getInstance().updateConfig('user', {
    loginPath: '/account/signin',
  });
}

코드 예시 1 — 사용자 로그인 경로 커스터마이징

AuthManager.getInstance().updateConfig('user', { loginPath: '/account/signin' });
// → 401 자동 리다이렉트 시 /account/signin?redirect=...&reason=session_expired 로 이동

코드 예시 2 — 다국어 prefix 반영

const locale = window.G7Core?.locale || 'ko';
AuthManager.getInstance().updateConfig('user', { loginPath: `/${locale}/login` });

호출 금지 — 모듈/플러그인

❌ 금지	✅ 올바른 사용
모듈/플러그인의 부트스트랩에서 updateConfig 호출	템플릿 부트스트랩에서만 호출
다른 템플릿이 활성화된 사이트에 침범하여 부작용 발생	사이트 단위 결정은 템플릿 책임

보안 가드 — open redirect 차단

loginPath 는 동일 origin path-only(즉 /로 시작)만 허용하며, // 시작(protocol-relative URL) 도 차단한다. 외부 URL 을 지정하면 throw 된다 — open redirect 취약점을 런타임에서 차단.

// ❌ throw — 외부 origin
AuthManager.getInstance().updateConfig('user', { loginPath: 'https://evil.com/login' });

// ❌ throw — protocol-relative URL
AuthManager.getInstance().updateConfig('user', { loginPath: '//evil.com/login' });

// ❌ throw — 상대 경로
AuthManager.getInstance().updateConfig('user', { loginPath: './login' });

// ✅ OK — path-only
AuthManager.getInstance().updateConfig('user', { loginPath: '/account/signin' });

401 자동 리다이렉트 동작

레이아웃 fetch 가 토큰 만료 등으로 401 재시도까지 실패하면, 코어 TemplateApp.showRouteError 가드가 자동으로 로그인 페이지로 리다이렉트한다 — getLoginRedirectUrl(authType, returnUrl, 'session_expired') 호출하여 ?reason=session_expired 쿼리 포함. 로그인 레이아웃의 init_actions 에서 해당 reason 을 감지해 안내 토스트를 표시한다.

// 로그인 레이아웃 init_actions 예시
{
  "if": "{{route?.query?.reason}} === 'session_expired'",
  "handler": "toast",
  "params": {
    "type": "warning",
    "message": "$t:auth.session_expired_toast"
  }
}

리다이렉트 동작 자체는 코어가 강제하며 레이아웃이 끌 수 없다. 경로만 updateConfig 로 사이트 단위 커스터마이즈 가능 ("여부는 강제, 경로는 커스터마이즈" 분리 설계).

---

관련 문서

• 데이터 소스 - API 호출 및 인증 헤더
• 보안 및 검증 - 프론트엔드 보안 규칙
• 컴포넌트 - 로그인 폼 컴포넌트

---

체크리스트

인증 기능 구현 시 확인 사항:

• 로그인 페이지에 auth_required: false 설정
• 인증 필요 페이지에 auth_required: true 설정
• 적절한 auth_type 설정 (admin/user)
• 리다이렉트 URL 보안 검증
• 토큰 갱신 로직 테스트
• 로그아웃 시 토큰 정리 확인