599 lines
23 KiB
Markdown
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 변경 이벤트 기록)
|