Files
lolympus-tournament-support/entraid-oidc-플랜.md
T
2026-04-25 11:49:21 -07:00

599 lines
23 KiB
Markdown

# Microsoft Entra ID OIDC 로그인 도입 플랜
> **대상**: codex 가 이어서 진행 가능한 수준의 실행 플랜
> **레포**: `/Users/dahyeon/source/lolympus-tournament-support` (pnpm workspace)
> **작성 기준**: 2026-04-25
> **선행 상태**: dakao NATS 통합, RiotAccount enrichment(force=true 동기 호출, summoner/league/mastery v4) 1차 구현 완료. 인증은 여전히 `X-Auth-User-Id` 헤더 기반.
---
## 1. Context
현재 인증은 `apps/api/src/modules/auth/auth.middleware.ts` 가 `X-Auth-User-Id` 헤더 (Mongo ObjectId) 를 읽어 User 를 `req.user` 에 붙이는 임시 방식입니다. 프로덕션으로 가려면 진짜 OIDC 로그인이 필요합니다.
다른 프로젝트에서 검증된 `apps/api/src/modules/auth/jwt.guard.ts`, `jwt.service.ts` 를 이식해 **Microsoft Entra ID 단일 IdP** OIDC 인증으로 교체합니다. 결정:
- **Identity 모델**: Top-level `Identity` 컬렉션 신설. User 는 community 별로 유지하되 `identityId` 로 Identity 를 가리킴. 한 Entra 사용자가 여러 community 에 멤버가 되는 모델을 자연스럽게 표현.
- **첫 로그인**: `/me` 가 빈 `memberships` 반환. 자동 멤버십 생성 없음. 프론트가 "커뮤니티 만들기/초대 받기" 분기.
- **프론트엔드 통합**: `@azure/msal-browser` + `@azure/msal-react` 로 같은 변경 묶음에 포함.
- **Dev fallback**: `AUTH_DEV_HEADER_ENABLED=true` + `NODE_ENV !== 'prod'` 일 때만 `X-Auth-User-Id` 헤더 허용.
dakao NATS 경로(카카오 명령) 는 HTTP 미들웨어/가드를 거치지 않으므로 그대로 보존됩니다.
---
## 2. 결정된 설계
### 2.1 `Identity` 컬렉션 (신규)
```ts
// apps/api/src/modules/global/database/schema.ts
export interface Identity extends MongooseTimestamps {
entraOid: string; // Entra 'oid' claim (tenant 내 유일)
tenantId?: string; // 'tid' claim — 다중 테넌트 대비
email?: string; // preferred_username
displayName?: string; // name
lastSignInAt?: Date;
}
export const IdentitySchema = new Schema<Identity>({
entraOid: { type: String, required: true },
tenantId: { type: String },
email: { type: String },
displayName: { type: String },
lastSignInAt: { type: Date },
}, { timestamps: true, collection: 'identity' });
IdentitySchema.index({ entraOid: 1 }, { unique: true });
IdentitySchema.index({ email: 1 });
```
`tournamentModelDefinitions` 에 `{ name: 'identity', schema: IdentitySchema, schemaName: 'identity' }` 추가, `TournamentModelTypes` 에 `identity: Identity` 추가.
### 2.2 `User` 변경
```ts
export interface User {
// 기존 필드 유지
identityId?: mongoose.Types.ObjectId;
}
```
스키마/인덱스:
```ts
identityId: { type: Schema.Types.ObjectId, ref: 'identity' },
// ...
UserSchema.index(
{ communityId: 1, identityId: 1 },
{ unique: true, sparse: true },
);
UserSchema.index({ identityId: 1 }, { sparse: true });
```
같은 사람이 한 community 에 두 번 등록되지 못하게 `{ communityId, identityId }` unique sparse. 글로벌 `{ identityId }` 로 한 사람의 모든 멤버십 빠른 조회.
기존 `kakaoTalkId`, `discordId` 인덱스/필드는 유지. dakao 사용자가 추후 Entra 로 로그인하면 같은 community 에서 별도 User 가 생기지 않도록 후속 "계정 연결" 플로우는 별도 작업(이번 범위 외).
### 2.3 인증 파이프라인
```
HTTP Request
└ JwtAuthGuard (verify JWT, req.tokenPayload 채움)
└ IdentityResolverGuard (oid → Identity 조회/upsert, req.identity)
└ (라우트별) UserResolverInterceptor (path :communityId + identityId → req.user)
└ RolesGuard (req.user.role 검증)
```
- `JwtAuthGuard`, `IdentityResolverGuard` 는 `APP_GUARD` 로 글로벌 등록.
- `UserResolverInterceptor` 는 `:communityId` path 파라미터를 가진 community 라우트에 `@UseInterceptors` 로 명시 적용.
- `@AllowPublicAccess()` 메타데이터가 붙은 라우트는 두 글로벌 가드를 통과(JWT 없어도 됨). 토큰이 있으면 `req.identity` 까지는 채워줌(soft auth).
### 2.4 `request` 필드 명세
| 필드 | 타입 | 의미 | 누가 채우나 |
| --- | --- | --- | --- |
| `request.tokenPayload` | `JWTPayload \| undefined` | 검증된 JWT claims | `JwtAuthGuard` |
| `request.identityProvider` | `IdentityProviderName` | 발행자 | `JwtAuthGuard` |
| `request.identity` | `IdentityDocument \| undefined` | DB Identity | `IdentityResolverGuard` |
| `request.user` | `UserDocument \| undefined` | community 멤버십 User | `UserResolverInterceptor` 또는 dev fallback |
기존 `request.user` 시맨틱(UserDocument)을 유지해 `RolesGuard` / `@CurrentUser()` 호환성 보존.
### 2.5 Dev fallback
`JwtAuthGuard` 또는 별도 `AuthDevFallbackMiddleware` 안에서:
```ts
if (
!authzHeader &&
process.env.NODE_ENV !== 'prod' &&
process.env.AUTH_DEV_HEADER_ENABLED === 'true'
) {
const userId = request.headers['x-auth-user-id'];
if (userId && isValidObjectId(userId)) {
const user = await UserModel.findById(userId).exec();
if (user) {
request.user = user;
if (user.identityId) {
request.identity = await IdentityModel.findById(user.identityId).exec();
}
return true;
}
}
}
```
`prod` 에서는 환경변수 무시.
### 2.6 `@AllowPublicAccess()` 적용 라우트
| 라우트 | 이유 |
| --- | --- |
| `RiotWebhookController.captureTournamentWebhook` | 외부 webhook |
| `CommunityController.createCommunity` | 가입 (MVP 호환을 위해 공개 유지하되 토큰이 있으면 token identity 우선) |
| `CommunityController.getCommunity` | 공개 정보 |
| `MatchController.listMatches`, `getMatch` | 공개 읽기 |
| `UserController.getMe` | 토큰 있으면 채워주고 없으면 빈 응답 |
### 2.7 엔드포인트 동작 변경
#### `GET /me`
**Before**: `{ user: UserDocument | null }`
**After**:
```jsonc
{
"identity": {
"id": "...",
"entraOid": "f0e47b9f-00cd-...",
"email": "park@dahyeon.us",
"displayName": "박 다현"
} /* | null */,
"memberships": [
{
"user": { /* UserDocument */ },
"community": { "id": "...", "name": "..." }
}
]
}
```
- 토큰 없이 호출하면 `{ identity: null, memberships: [] }`.
- `memberships` 가 빈 배열이면 프론트는 "community 만들기 / 초대 받기" UI 분기.
#### `POST /communities`
owner 정보를 body 에서 받지 않고 `req.identity` + 새 community 에 owner User 자동 생성. 기존 `CreateCommunityDto.owner` 는 deprecated. dev fallback 시에는 body 도 backward compat 으로 허용.
#### `PATCH /communities/:communityId/...`, `POST /communities/:communityId/matches/...`
`UserResolverInterceptor` 가 path 의 `communityId` + `req.identity._id` 로 User 를 찾아 `req.user` 에 주입. 못 찾으면 `RolesGuard` 가 `ForbiddenException('No membership in this community.')`.
### 2.8 WebSocket (auction gateway)
- 클라이언트: `io('/auction', { auth: { token: <bearer> } })`
- 서버: `handleConnection` 에서 `socket.handshake.auth.token` 을 `JwtService.verify()` 로 검증, identity → user 조회, `socket.data.user` 에 저장.
- dev fallback: `socket.handshake.auth['x-auth-user-id']` 도 dev 환경에서 허용.
- 인증 실패 시 `socket.disconnect(true)`.
### 2.9 프론트엔드 (apps/web)
#### 의존성
```bash
pnpm --filter web add @azure/msal-browser @azure/msal-react
```
#### 환경변수 (`apps/web/.env`, `.env.example`)
- `VITE_MSAL_CLIENT_ID` — Azure App 등록의 Application (client) ID
- `VITE_MSAL_AUTHORITY` — `https://login.microsoftonline.com/<tenantId>`
- `VITE_MSAL_API_SCOPE` — 예: `api://lolympus-api/access_as_user`
- `VITE_MSAL_REDIRECT_URI` — 예: `http://localhost:5173/auth/callback`
#### 신규 파일
- `apps/web/src/lib/auth/msal.config.ts` — `PublicClientApplication` 인스턴스
- `apps/web/src/lib/auth/MsalAppProvider.tsx` — `MsalProvider` 래핑 + redirect 처리
- `apps/web/src/lib/auth/use-access-token.ts` — `acquireTokenSilent → acquireTokenPopup/Redirect` fallback
- `apps/web/src/pages/Login.tsx` — 로그인 진입
- `apps/web/src/pages/AuthCallback.tsx` — redirect 콜백
- `apps/web/src/components/CommunitySwitcher.tsx` — memberships > 1 일 때 active community 선택
#### 수정 파일
- `apps/web/src/main.tsx` — `MsalAppProvider` 로 앱 감싸기
- `apps/web/src/lib/api.ts` — `apiFetch` 가 `acquireTokenSilent` 후 `Authorization: Bearer ...` 첨부, 401 시 재로그인 트리거
- `apps/web/src/lib/socket.ts` (또는 socket 초기화 파일) — `io({ auth: { token } })`
- `apps/web/src/config.ts` — `getAuthUserId/setAuthUserId/useAuthUserId` 는 `import.meta.env.DEV` 분기로 격리
- `apps/web/src/components/DevAuthSwitcher.tsx` — `import.meta.env.DEV` 빌드에서만 렌더
#### `/me` consumer
- `useMe()` 훅 결과 모양 변경 (`{ identity, memberships }`)
- header 의 사용자 표시: `identity.displayName ?? identity.email`
- admin 가시성: `memberships.find(m => m.community.id === activeCommunityId)?.user.role`
### 2.10 Azure App Registration 체크리스트
운영자 작업 (코드 외):
1. App Registration 생성 (single-tenant 권장)
2. Authentication 플랫폼 추가:
- SPA: redirect URI = `http://localhost:5173/auth/callback`, 프로덕션 URL 추가
3. Expose an API:
- Application ID URI = `api://lolympus-api`
- Scope 추가 = `access_as_user`
- Authorized client applications (자기 자신 추가)
4. Token configuration: optional claim `email`, `preferred_username` 활성화
Infisical 시크릿 추가:
- `MICROSOFT_ENTRAID_TENANT_ID`
- `MICROSOFT_ENTRAID_ALLOWED_ALGS=RS256`
- `JWT_CLAIM_AUDIENCE` = Application ID URI
- `AUTH_DEV_HEADER_ENABLED=true` (dev/staging 환경만)
`SecretService.PROCESS_ENVS` 에 `JWT_CLAIM_AUDIENCE`, `MICROSOFT_ENTRAID_TENANT_ID`, `MICROSOFT_ENTRAID_ALLOWED_ALGS`, `AUTH_DEV_HEADER_ENABLED` 추가.
---
## 3. 실행 단계 (codex 진행 순서)
작업 단위는 PR 단위로 쪼갤 수 있도록 분리되어 있습니다.
### Step 1. 스키마 변경
**파일**: `apps/api/src/modules/global/database/schema.ts`
- `Identity` 인터페이스/스키마/인덱스 추가
- `tournamentModelDefinitions` 에 등록, `TournamentModelTypes` 확장
- `User.identityId` optional 필드 + 인덱스 추가
- `UserDocument` / `IdentityDocument` 타입 export
### Step 2. `AllowPublicAccess` 데코레이터
**신규**: `apps/api/src/modules/auth/allow-public-access.decorator.ts`
```ts
export const METADATA_KEY_IS_PUBLIC_ACCESS_ALLOWED = 'allow_public_access';
export const AllowPublicAccess = () =>
SetMetadata(METADATA_KEY_IS_PUBLIC_ACCESS_ALLOWED, true);
```
### Step 3. JwtService / JwtAuthGuard 이식
**신규**: `apps/api/src/modules/auth/jwt.service.ts`, `apps/api/src/modules/auth/jwt.guard.ts`
- 다른 프로젝트의 참고 코드를 그대로 이식하되 `import` 경로는 `../global/secret/secret.service` 로 수정
- `jose` 의존성 추가: `pnpm --filter api add jose`
- `JwtAuthGuard` 의 동작 변경: `request.tokenPayload = payload` (기존 `request.user` 가 아닌)
- public access 시 토큰이 있으면 검증 시도, 없으면 그냥 통과 (soft auth)
### Step 4. IdentityService + IdentityResolverGuard
**신규**: `apps/api/src/modules/auth/identity.service.ts`
```ts
@Injectable()
export class IdentityService {
constructor(private readonly connectionService: ConnectionService) {}
async findOrCreateByOid(payload: {
entraOid: string;
tenantId?: string;
email?: string;
displayName?: string;
}): Promise<IdentityDocument> {
const IdentityModel = await this.connectionService.getModel('identity');
return IdentityModel.findOneAndUpdate(
{ entraOid: payload.entraOid },
{
$set: {
email: payload.email,
displayName: payload.displayName,
tenantId: payload.tenantId,
lastSignInAt: new Date(),
},
$setOnInsert: { entraOid: payload.entraOid },
},
{ upsert: true, returnDocument: 'after', setDefaultsOnInsert: true },
).exec();
}
}
```
**신규**: `apps/api/src/modules/auth/identity-resolver.guard.ts`
`request.tokenPayload` 가 있으면 `IdentityService.findOrCreateByOid` 호출해 `request.identity` 채움. public 라우트에서도 토큰 있으면 채워줌.
### Step 5. UserResolverInterceptor
**신규**: `apps/api/src/modules/auth/user-resolver.interceptor.ts`
```ts
@Injectable()
export class UserResolverInterceptor implements NestInterceptor {
constructor(private readonly connectionService: ConnectionService) {}
async intercept(ctx: ExecutionContext, next: CallHandler) {
const req = ctx.switchToHttp().getRequest();
const communityId = req.params?.communityId;
if (req.identity && communityId && isValidObjectId(communityId)) {
const UserModel = await this.connectionService.getModel('user');
req.user = await UserModel.findOne({
communityId: new mongoose.Types.ObjectId(communityId),
identityId: req.identity._id,
}).exec();
}
return next.handle();
}
}
```
community 라우트 controller 들 (Match, Auction, Community 의 `:communityId` 라우트) 에 `@UseInterceptors(UserResolverInterceptor)` 적용.
### Step 6. AuthModule 재구성
**파일**: `apps/api/src/modules/auth/auth.module.ts`
```ts
@Global()
@Module({
imports: [SecretModule],
providers: [
JwtService,
JwtAuthGuard,
IdentityService,
IdentityResolverGuard,
UserResolverInterceptor,
AuthService, // dev fallback 전용으로 축소
RolesGuard,
{ provide: APP_GUARD, useClass: JwtAuthGuard },
{ provide: APP_GUARD, useClass: IdentityResolverGuard },
],
exports: [JwtService, IdentityService, RolesGuard, UserResolverInterceptor],
})
export class AuthModule {}
```
### Step 7. AuthMiddleware → AuthService dev fallback 으로 축소
**파일**: `apps/api/src/modules/auth/auth.middleware.ts`, `auth.service.ts`
- `AuthModule.configure` 에서 글로벌 미들웨어 등록 제거
- `auth.service.ts` 는 dev fallback 메서드만 노출. `JwtAuthGuard` 내부에서 호출하거나 별도 미들웨어로 dev only 등록
### Step 8. RolesGuard 호환 보강
**파일**: `apps/api/src/modules/auth/roles.guard.ts`
- 동작 그대로. `req.user` 가 `UserDocument` 면 OK
- `request.identity` 만 있고 `request.user` 가 없을 때 메시지: `ForbiddenException('No membership in this community.')`
### Step 9. `/me` 엔드포인트 변경
**파일**: `apps/api/src/modules/user/user.controller.ts`, `apps/api/src/modules/user/dto/me-response.dto.ts` (신규)
```ts
@Get('me')
@AllowPublicAccess()
async getMe(@Req() req): Promise<MeResponse> {
if (!req.identity) return { identity: null, memberships: [] };
const UserModel = await this.connectionService.getModel('user');
const CommunityModel = await this.connectionService.getModel('community');
const users = await UserModel.find({ identityId: req.identity._id }).exec();
const communities = await CommunityModel.find({
_id: { $in: users.map((u) => u.communityId) },
}).exec();
return {
identity: serializeIdentity(req.identity),
memberships: users.map((u) => ({
user: u,
community: communities.find((c) => c._id.equals(u.communityId)),
})),
};
}
```
`@CurrentIdentity()` 데코레이터 추가 시 `req.identity` 직접 주입 가능.
### Step 10. Community 생성 흐름
**파일**: `apps/api/src/modules/community/community.controller.ts`, `community.service.ts`, `dto/create-community.dto.ts`
- `createCommunity` 가 `req.identity` 가 있으면 owner User 의 `identityId` 자동 설정
- body 의 `owner` 필드는 dev fallback / backward compat 으로만 사용
### Step 11. Public access 라우트 표시
위 §2.6 표의 라우트들에 `@AllowPublicAccess()` 추가.
### Step 12. WebSocket 인증
**파일**: `apps/api/src/modules/auction/auction.gateway.ts`
- `handleConnection` 에서 token → identity → user 조회
- 실패 시 `client.disconnect(true)`
- dev fallback: `socket.handshake.auth['x-auth-user-id']` 도 dev 환경에서 허용
### Step 13. SecretService 확장
**파일**: `apps/api/src/modules/global/secret/secret.service.ts`
`PROCESS_ENVS` 에 추가:
- `JWT_CLAIM_AUDIENCE`
- `MICROSOFT_ENTRAID_TENANT_ID`
- `MICROSOFT_ENTRAID_ALLOWED_ALGS`
- `AUTH_DEV_HEADER_ENABLED`
### Step 14. 백엔드 단위 테스트
**신규 spec**:
- `auth/jwt.service.spec.ts` — issuer/audience/tenant/alg 검증, 잘못된 토큰 거부
- `auth/jwt.guard.spec.ts` — public access 통과, missing/invalid bearer 거부
- `auth/identity.service.spec.ts` — findOrCreateByOid upsert 동작
- `auth/identity-resolver.guard.spec.ts` — tokenPayload → identity 매핑
- `auth/user-resolver.interceptor.spec.ts` — path communityId + identityId 매칭
- `auth/dev-fallback.spec.ts` — 환경변수 OFF 시 차단, ON 시 동작
### Step 15. 프론트엔드 MSAL 통합
위 §2.9 의 신규/수정 파일들. `apiFetch` 의 token 첨부 흐름:
```ts
const token = await acquireAccessToken(); // silent → popup/redirect fallback
return fetch(url, {
...init,
headers: {
...init?.headers,
...(token ? { Authorization: `Bearer ${token}` } : {}),
},
});
```
401 응답 시 토큰 캐시 invalidate 후 1회 재시도, 그래도 실패면 `/login` redirect.
WebSocket 초기화:
```ts
const socket = io('/auction', {
auth: { token: await acquireAccessToken() },
});
```
### Step 16. 회귀 / 통합 검증
- `pnpm --filter api exec tsc --noEmit` 통과
- `pnpm --filter api exec jest` 전체 PASS
- 로컬에서 Entra 로그인 → JWT 생성 → API 호출 → `/me` 가 identity 반환
- dakao `!내전 신청 ...` 시나리오 → 여전히 동작 (HTTP 인증과 무관)
- dev fallback: `AUTH_DEV_HEADER_ENABLED=true` + `X-Auth-User-Id` 헤더 → 200 OK / `=false` → 401
- Azure App 등록 후 `JWT_CLAIM_AUDIENCE` 시크릿 일치 확인
- `pnpm --filter web build` 통과, `/login` → 콜백 → memberships 분기
---
## 4. 변경/추가 파일 목록
### 신규 (백엔드)
- `apps/api/src/modules/auth/allow-public-access.decorator.ts`
- `apps/api/src/modules/auth/jwt.service.ts`
- `apps/api/src/modules/auth/jwt.guard.ts`
- `apps/api/src/modules/auth/identity.service.ts`
- `apps/api/src/modules/auth/identity-resolver.guard.ts`
- `apps/api/src/modules/auth/user-resolver.interceptor.ts`
- `apps/api/src/modules/auth/current-identity.decorator.ts`
- `apps/api/src/modules/auth/jwt.service.spec.ts`
- `apps/api/src/modules/auth/jwt.guard.spec.ts`
- `apps/api/src/modules/auth/identity.service.spec.ts`
- `apps/api/src/modules/auth/identity-resolver.guard.spec.ts`
- `apps/api/src/modules/auth/user-resolver.interceptor.spec.ts`
- `apps/api/src/modules/auth/dev-fallback.spec.ts`
- `apps/api/src/modules/user/dto/me-response.dto.ts`
### 수정 (백엔드)
- `apps/api/src/modules/global/database/schema.ts` — Identity 추가, User.identityId
- `apps/api/src/modules/auth/auth.module.ts` — APP_GUARD 등록, providers 재구성
- `apps/api/src/modules/auth/auth.service.ts` — dev fallback 전용 축소
- `apps/api/src/modules/auth/auth.middleware.ts` — 제거 또는 dev only 축소
- `apps/api/src/modules/auth/roles.guard.ts` — 에러 메시지 보강
- `apps/api/src/modules/auth/current-user.decorator.ts` — 그대로 (호환 유지)
- `apps/api/src/modules/user/user.controller.ts` — `/me` 응답 모양 변경
- `apps/api/src/modules/community/community.controller.ts` — `@AllowPublicAccess`, owner 자동 연결
- `apps/api/src/modules/community/community.service.ts` — owner 생성 시 identityId 연결
- `apps/api/src/modules/community/dto/create-community.dto.ts` — owner 필드 deprecated
- `apps/api/src/modules/match/match.controller.ts` — `@AllowPublicAccess` (read), `@UseInterceptors(UserResolverInterceptor)` (write)
- `apps/api/src/modules/auction/auction.controller.ts` — interceptor 적용
- `apps/api/src/modules/auction/auction.gateway.ts` — JWT handshake 검증
- `apps/api/src/modules/riot/riot-webhook.controller.ts` — `@AllowPublicAccess`
- `apps/api/src/modules/global/secret/secret.service.ts` — PROCESS_ENVS 확장
### 의존성 (백엔드)
- `pnpm --filter api add jose`
### 신규 (프론트엔드)
- `apps/web/src/lib/auth/msal.config.ts`
- `apps/web/src/lib/auth/MsalAppProvider.tsx`
- `apps/web/src/lib/auth/use-access-token.ts`
- `apps/web/src/pages/Login.tsx`
- `apps/web/src/pages/AuthCallback.tsx`
- `apps/web/src/components/CommunitySwitcher.tsx`
### 수정 (프론트엔드)
- `apps/web/src/main.tsx`
- `apps/web/src/lib/api.ts`
- `apps/web/src/lib/socket.ts` (또는 해당 socket 초기화 파일)
- `apps/web/src/config.ts`
- `apps/web/src/components/DevAuthSwitcher.tsx`
- `apps/web/.env.example`
### 의존성 (프론트엔드)
- `pnpm --filter web add @azure/msal-browser @azure/msal-react`
### 인프라 / 시크릿
- Azure App Registration (SPA platform, expose API, scope `access_as_user`)
- Infisical: `MICROSOFT_ENTRAID_TENANT_ID`, `MICROSOFT_ENTRAID_ALLOWED_ALGS`, `JWT_CLAIM_AUDIENCE`, `AUTH_DEV_HEADER_ENABLED`(dev 만)
- Frontend env: `VITE_MSAL_CLIENT_ID`, `VITE_MSAL_AUTHORITY`, `VITE_MSAL_API_SCOPE`, `VITE_MSAL_REDIRECT_URI`
---
## 5. 기존 파일 / 함수 재사용 매핑
| 신규 작업 | 재사용 대상 | 경로 |
| --- | --- | --- |
| JwtService / JwtGuard 본체 | 다른 프로젝트 참고 파일 | `apps/api/src/modules/auth/jwt.service.ts`, `jwt.guard.ts` |
| 시크릿 로딩 | `SecretService.get` / `ready` | `apps/api/src/modules/global/secret/secret.service.ts` |
| Mongo 모델 액세스 | `ConnectionService.getModel` | `apps/api/src/modules/global/database/connection.service.ts` |
| 현재 user 데코레이터 | `CurrentUser` (그대로 호환) | `apps/api/src/modules/auth/current-user.decorator.ts` |
| 권한 매핑 | `permissions.ts`, `roles.guard.ts`, `roles.decorator.ts` | `apps/api/src/modules/auth/` |
| ObjectId 검증 | `ParseObjectIdPipe`, `mongoose.isValidObjectId` | `apps/api/src/modules/common/parse-object-id.pipe.ts` |
---
## 6. 검증 (end-to-end)
### 백엔드
1. `pnpm --filter api exec tsc --noEmit`
2. `pnpm --filter api exec jest`
3. dev 환경 부팅 후:
- `curl -H "X-Auth-User-Id: <id>" http://localhost:3000/me` → `AUTH_DEV_HEADER_ENABLED=true` 일 때 200, `=false` 일 때 401
- 실제 Entra access token 으로 `Authorization: Bearer ...` 호출 → 200, identity 채워짐
- `Authorization` 누락 + dev fallback 비활성 + 보호 라우트 → 401
- `Authorization` 정상 + community path 의 멤버 아님 → 403 `No membership in this community.`
4. dakao 시나리오: `!내전 신청 ...` 메시지 publish → 변동 없이 동작 확인
### 프론트엔드
1. `pnpm --filter web build` 통과
2. `pnpm --filter web dev` 후:
- `/login` → Entra 로그인 → 콜백 → `/me` 호출 성공
- memberships 빈 배열 → "커뮤니티 만들기/초대 받기" 분기 표시
- 보호된 페이지(매치 관리) 진입 시 토큰 자동 첨부
- 토큰 만료 시 silent refresh → 실패 시 재로그인 redirect
- WebSocket(/auction) 연결 시 핸드셰이크에 토큰 포함, 인증 실패면 disconnect
---
## 7. 범위 외 (다음 작업으로 미룸)
- dakao 사용자 ↔ Entra identity 자동/수동 연결 플로우
- `createCommunity` 강제 인증 + invitation token 기반 멤버 가입
- 다중 테넌트 지원 (`tid` 동적 분기)
- Cognito 등 추가 IdP
- Refresh token 백엔드 처리 (현재 stateless)
- Audit log (로그인/identity 변경 이벤트 기록)