.
This commit is contained in:
1 parent
fcfdf8ac67
commit
5316cbbc3e
12 files changed
+583
-80
No files matched your search
@@ -0,0 +1,179 @@
|
||||
# Azure Entra ID 인증 설정 가이드
|
||||
|
||||
이 문서는 Gem Wiki에 Azure Entra ID (구 Azure AD) OIDC 인증을 설정하는 방법을 설명합니다.
|
||||
|
||||
## 1. Azure Portal에서 앱 등록
|
||||
|
||||
### 1.1 Azure Portal 접속
|
||||
1. [Azure Portal](https://portal.azure.com)에 로그인합니다.
|
||||
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` 파일을 생성하고 다음 내용을 추가합니다:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
**프로덕션 환경:**
|
||||
```env
|
||||
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 컴포넌트에서 인증 상태 확인
|
||||
```typescript
|
||||
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 호출 시 인증 토큰 사용
|
||||
```typescript
|
||||
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`로 교체하거나,
|
||||
조건부로 사용하도록 설정합니다:
|
||||
|
||||
```typescript
|
||||
// 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. 개발 서버 실행
|
||||
|
||||
```bash
|
||||
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를 사용하세요.
|
||||
|
||||
## 참고 자료
|
||||
|
||||
- [Azure AD 문서](https://docs.microsoft.com/azure/active-directory/)
|
||||
- [MSAL.js 문서](https://github.com/AzureAD/microsoft-authentication-library-for-js)
|
||||
- [React용 MSAL 가이드](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-react)
|
||||
Reference in new issue
Block a user