Files
wiki/AUTHENTICATION_SETUP.md
2025-11-07 19:35:31 +09:00

6.0 KiB

Azure Entra ID 인증 설정 가이드

이 문서는 Gem Wiki에 Azure Entra ID (구 Azure AD) OIDC 인증을 설정하는 방법을 설명합니다.

1. Azure Portal에서 앱 등록

1.1 Azure Portal 접속

  1. Azure Portal에 로그인합니다.
  2. "Azure Active Directory" (또는 "Microsoft Entra ID")로 이동합니다.
  3. "앱 등록" 메뉴를 선택합니다.

1.2 새 앱 등록

  1. 새 등록 버튼을 클릭합니다.
  2. 다음 정보를 입력합니다:
    • 이름: Gem Wiki (또는 원하는 이름)
    • 지원되는 계정 유형: 조직의 요구사항에 맞게 선택
    • 리디렉션 URI:
      • 플랫폼: 단일 페이지 애플리케이션(SPA)
      • URI: http://localhost:5173 (개발용)
      • 프로덕션: https://wiki.dahyeon.us

1.3 필요한 정보 수집

앱 등록 후, 다음 정보를 메모합니다:

  • Application (client) ID (예: 12345678-1234-1234-1234-123456789abc)
  • Directory (tenant) ID (예: 87654321-4321-4321-4321-cba987654321)

1.4 API 권한 설정

  1. "API 권한" 메뉴로 이동합니다.
  2. 기본적으로 User.Read 권한이 추가되어 있습니다.
  3. 추가 권한이 필요한 경우 권한 추가 버튼을 클릭합니다.

1.5 인증 설정

  1. "인증" 메뉴로 이동합니다.
  2. 암시적 허용 및 하이브리드 흐름에서:
    • ✅ "액세스 토큰" 체크
    • ✅ "ID 토큰" 체크
  3. 고급 설정에서:
    • ✅ "공용 클라이언트 흐름 허용" 체크 (선택사항)

2. 환경 변수 설정

프로젝트 루트에 .env 파일을 생성하고 다음 내용을 추가합니다:

# Azure AD Configuration
VITE_AZURE_CLIENT_ID=your-client-id-here
VITE_AZURE_AUTHORITY=https://login.microsoftonline.com/your-tenant-id-here
VITE_AZURE_REDIRECT_URI=http://localhost:5173
VITE_AZURE_POST_LOGOUT_REDIRECT_URI=http://localhost:5173

# API Configuration
VITE_API_BASE_URL=https://wiki.dahyeon.us/v1

프로덕션 환경:

VITE_AZURE_CLIENT_ID=your-client-id-here
VITE_AZURE_AUTHORITY=https://login.microsoftonline.com/your-tenant-id-here
VITE_AZURE_REDIRECT_URI=https://wiki.dahyeon.us
VITE_AZURE_POST_LOGOUT_REDIRECT_URI=https://wiki.dahyeon.us
VITE_API_BASE_URL=https://wiki.dahyeon.us/v1

3. 백엔드 API 설정

백엔드 API에서 JWT 토큰을 검증하도록 설정해야 합니다.

3.1 JWT 검증 설정

백엔드에서 다음을 확인해야 합니다:

  • Issuer: https://login.microsoftonline.com/{tenant-id}/v2.0
  • Audience: Azure Portal에서 설정한 Application (client) ID
  • JWKS URI: https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys

3.2 API 엔드포인트

서버 API는 다음과 같은 엔드포인트를 제공해야 합니다:

  • GET /v1/pages - 모든 페이지 조회
  • GET /v1/pages/:id - 특정 페이지 조회
  • POST /v1/pages - 새 페이지 생성
  • PUT /v1/pages/:id - 페이지 업데이트
  • DELETE /v1/pages/:id - 페이지 삭제

모든 요청은 Authorization: Bearer {token} 헤더를 포함해야 합니다.

4. 코드에서 인증 사용하기

4.1 컴포넌트에서 인증 상태 확인

import { useMsal } from '@azure/msal-react';

function MyComponent() {
  const { accounts } = useMsal();
  const isAuthenticated = accounts.length > 0;
  
  if (!isAuthenticated) {
    return <div>로그인이 필요합니다.</div>;
  }
  
  return <div>환영합니다, {accounts[0].name}!</div>;
}

4.2 API 호출 시 인증 토큰 사용

import { useAuthenticatedApi } from '../shared/hooks/useAuthenticatedApi';

function MyComponent() {
  const { authenticatedFetch } = useAuthenticatedApi();
  
  const fetchData = async () => {
    const response = await authenticatedFetch('https://wiki.dahyeon.us/v1/pages');
    const data = await response.json();
    return data;
  };
  
  // 사용 예시
}

4.3 서버 API 파일 사용

실제 서버와 통합하려면 src/entities/page/api.ts를 api.server.ts로 교체하거나, 조건부로 사용하도록 설정합니다:

// src/entities/page/index.ts
export * from './types';

// 개발/프로덕션 환경에 따라 다른 API 사용
if (import.meta.env.PROD) {
  export * from './api.server'; // 실제 서버 API
} else {
  export * from './api'; // Mock API
}

5. 개발 서버 실행

npm run dev

브라우저에서 http://localhost:5173으로 접속하면 상단 우측에 "로그인" 버튼이 표시됩니다.

6. 문제 해결

로그인 팝업이 차단되는 경우

  • 브라우저의 팝업 차단 설정을 확인하세요.
  • 리다이렉트 방식으로 변경하려면 AuthButton.tsx에서 loginPopup 대신 loginRedirect를 사용하세요.

CORS 오류가 발생하는 경우

  • 백엔드 API에서 CORS 설정을 확인하세요.
  • Access-Control-Allow-Origin 헤더가 올바르게 설정되어 있는지 확인하세요.

토큰이 만료된 경우

  • MSAL은 자동으로 토큰을 갱신합니다.
  • acquireTokenSilent 메서드가 실패하면 자동으로 팝업을 통해 재인증합니다.

7. 보안 권장사항

  1. 환경 변수 보안

    • .env 파일을 .gitignore에 추가하세요.
    • 프로덕션 환경에서는 환경 변수를 안전하게 관리하세요.
  2. 토큰 저장

    • 현재 설정은 sessionStorage를 사용합니다.
    • 더 안전한 저장이 필요한 경우 설정을 변경할 수 있습니다.
  3. API 검증

    • 백엔드에서 모든 요청의 JWT 토큰을 검증해야 합니다.
    • 토큰의 만료 시간, issuer, audience를 확인하세요.
  4. HTTPS 사용

    • 프로덕션에서는 항상 HTTPS를 사용하세요.
    • 개발 환경에서도 가능하면 HTTPS를 사용하세요.

참고 자료