23 KiB
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 컬렉션 (신규)
// 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 변경
export interface User {
// 기존 필드 유지
identityId?: mongoose.Types.ObjectId;
}
스키마/인덱스:
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는:communityIdpath 파라미터를 가진 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 안에서:
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:
{
"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)
의존성
pnpm --filter web add @azure/msal-browser @azure/msal-react
환경변수 (apps/web/.env, .env.example)
VITE_MSAL_CLIENT_ID— Azure App 등록의 Application (client) IDVITE_MSAL_AUTHORITY—https://login.microsoftonline.com/<tenantId>VITE_MSAL_API_SCOPE— 예:api://lolympus-api/access_as_userVITE_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/Redirectfallbackapps/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 체크리스트
운영자 작업 (코드 외):
- App Registration 생성 (single-tenant 권장)
- Authentication 플랫폼 추가:
- SPA: redirect URI =
http://localhost:5173/auth/callback, 프로덕션 URL 추가
- SPA: redirect URI =
- Expose an API:
- Application ID URI =
api://lolympus-api - Scope 추가 =
access_as_user - Authorized client applications (자기 자신 추가)
- Application ID URI =
- Token configuration: optional claim
email,preferred_username활성화
Infisical 시크릿 추가:
MICROSOFT_ENTRAID_TENANT_IDMICROSOFT_ENTRAID_ALLOWED_ALGS=RS256JWT_CLAIM_AUDIENCE= Application ID URIAUTH_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.identityIdoptional 필드 + 인덱스 추가UserDocument/IdentityDocument타입 export
Step 2. AllowPublicAccess 데코레이터
신규: apps/api/src/modules/auth/allow-public-access.decorator.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 joseJwtAuthGuard의 동작 변경:request.tokenPayload = payload(기존request.user가 아닌)- public access 시 토큰이 있으면 검증 시도, 없으면 그냥 통과 (soft auth)
Step 4. IdentityService + IdentityResolverGuard
신규: apps/api/src/modules/auth/identity.service.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
@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
@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 (신규)
@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_AUDIENCEMICROSOFT_ENTRAID_TENANT_IDMICROSOFT_ENTRAID_ALLOWED_ALGSAUTH_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 첨부 흐름:
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 초기화:
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.tsapps/api/src/modules/auth/jwt.service.tsapps/api/src/modules/auth/jwt.guard.tsapps/api/src/modules/auth/identity.service.tsapps/api/src/modules/auth/identity-resolver.guard.tsapps/api/src/modules/auth/user-resolver.interceptor.tsapps/api/src/modules/auth/current-identity.decorator.tsapps/api/src/modules/auth/jwt.service.spec.tsapps/api/src/modules/auth/jwt.guard.spec.tsapps/api/src/modules/auth/identity.service.spec.tsapps/api/src/modules/auth/identity-resolver.guard.spec.tsapps/api/src/modules/auth/user-resolver.interceptor.spec.tsapps/api/src/modules/auth/dev-fallback.spec.tsapps/api/src/modules/user/dto/me-response.dto.ts
수정 (백엔드)
apps/api/src/modules/global/database/schema.ts— Identity 추가, User.identityIdapps/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 필드 deprecatedapps/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—@AllowPublicAccessapps/api/src/modules/global/secret/secret.service.ts— PROCESS_ENVS 확장
의존성 (백엔드)
pnpm --filter api add jose
신규 (프론트엔드)
apps/web/src/lib/auth/msal.config.tsapps/web/src/lib/auth/MsalAppProvider.tsxapps/web/src/lib/auth/use-access-token.tsapps/web/src/pages/Login.tsxapps/web/src/pages/AuthCallback.tsxapps/web/src/components/CommunitySwitcher.tsx
수정 (프론트엔드)
apps/web/src/main.tsxapps/web/src/lib/api.tsapps/web/src/lib/socket.ts(또는 해당 socket 초기화 파일)apps/web/src/config.tsapps/web/src/components/DevAuthSwitcher.tsxapps/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)
백엔드
pnpm --filter api exec tsc --noEmitpnpm --filter api exec jest- 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 비활성 + 보호 라우트 → 401Authorization정상 + community path 의 멤버 아님 → 403No membership in this community.
- dakao 시나리오:
!내전 신청 ...메시지 publish → 변동 없이 동작 확인
프론트엔드
pnpm --filter web build통과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 변경 이벤트 기록)