OIDC 인증 가이드¶

이 문서는 백엔드 API의 OIDC 인증 시스템에 대한 가이드입니다.

1. 인증 아키텍처 개요¶

이 백엔드는 OIDC Resource Server (Relying Party) 로 동작합니다. 외부 OIDC Provider(Keycloak, Auth0, Google 등)에서 발급한 JWT Access Token을 검증합니다.

인증 흐름¶

sequenceDiagram
    participant FE as Frontend
    participant BE as Backend API
    participant OP as OIDC Provider

    FE->>OP: 1. 로그인 요청
    OP-->>FE: 2. Access Token 발급
    FE->>BE: 3. API 요청 + Bearer Token
    BE->>OP: 4. JWKS 조회 (캐시됨)
    BE->>BE: 5. JWT 서명 검증
    BE-->>FE: 6. 응답 + 사용자 데이터

핵심 개념¶

용어	설명
OIDC Provider	사용자 인증을 담당하는 외부 서버 (Keycloak, Auth0, Google 등)
Access Token	OIDC Provider가 발급한 JWT, API 요청 시 사용
JWKS	JSON Web Key Set, JWT 서명 검증에 사용되는 공개키
sub claim	JWT 내 사용자 고유 식별자, 데이터 소유권(owner_id)에 사용

데이터 격리¶

모든 사용자 데이터는 owner_id 필드로 격리됩니다: - Schedule, Todo, Tag, Timer 등 모든 모델에 owner_id 필드 존재 - owner_id는 JWT의 sub claim 값과 매칭 - 다른 사용자의 데이터에는 접근 불가 (404 반환)

기존 데이터 마이그레이션¶

마이그레이션 시 기존 데이터에 할당할 owner_id를 환경변수로 지정할 수 있습니다:

# 개발환경 (기본값: test-user-id)
# OIDC_ENABLED=false 시 mock 사용자와 일치하여 기존 데이터에 접근 가능
alembic upgrade head

# 프로덕션 (특정 사용자 ID 지정)
MIGRATION_DEFAULT_OWNER_ID=admin-user-oidc-sub alembic upgrade head

환경	MIGRATION_DEFAULT_OWNER_ID	설명
개발	`test-user-id` (기본값)	Mock 사용자와 일치
프로덕션	실제 OIDC sub	관리자 또는 기존 사용자의 sub claim

2. 개발 환경: 인증 비활성화¶

로컬 개발이나 테스트 시 OIDC 인증을 비활성화할 수 있습니다.

방법 1: 환경변수 설정¶

# .env 파일
OIDC_ENABLED=false

방법 2: 환경변수 직접 지정¶

Linux/MacWindows (PowerShell)

OIDC_ENABLED=false uvicorn app.main:app --reload

$env:OIDC_ENABLED="false"; uvicorn app.main:app --reload

인증 비활성화 시 동작¶

인증이 비활성화되면 모든 요청에 아래의 Mock 사용자가 자동으로 주입됩니다:

{
  "sub": "test-user-id",
  "email": "test@example.com",
  "name": "Test User"
}

주의

프로덕션 환경에서는 반드시 OIDC_ENABLED=true로 설정하세요!

테스트 환경¶

pytest 실행 시 자동으로 인증이 비활성화됩니다 (tests/conftest.py에서 설정):

import os
os.environ["OIDC_ENABLED"] = "false"

3. 프로덕션: OIDC 설정¶

환경변수 목록¶

환경변수	필수	기본값	설명
`OIDC_ENABLED`	O	`true`	인증 활성화 여부
`OIDC_ISSUER_URL`	O	-	OIDC Provider의 Issuer URL
`OIDC_AUDIENCE`	O	-	Client ID (Access Token의 `aud` claim)
`OIDC_DISCOVERY_URL`	X	자동 생성	커스텀 Discovery URL
`OIDC_JWKS_CACHE_TTL_SECONDS`	X	`3600`	JWKS 캐시 TTL (초)

예시 설정 (.env)¶

# 프로덕션 설정 예시
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://auth.example.com/realms/production
OIDC_AUDIENCE=my-frontend-app
OIDC_JWKS_CACHE_TTL_SECONDS=3600

Docker Compose 설정¶

# compose.yaml
services:
  backend:
    environment:
      - OIDC_ENABLED=true
      - OIDC_ISSUER_URL=https://auth.example.com/realms/production
      - OIDC_AUDIENCE=my-frontend-app

4. Well-Known 엔드포인트¶

자동 Discovery¶

백엔드는 OIDC Discovery를 통해 자동으로 Provider 설정을 가져옵니다:

Discovery URL = {OIDC_ISSUER_URL}/.well-known/openid-configuration

예시: - Issuer URL: https://auth.example.com/realms/myrealm - Discovery URL: https://auth.example.com/realms/myrealm/.well-known/openid-configuration

커스텀 Discovery URL¶

비표준 경로를 사용하는 Provider의 경우 직접 지정:

OIDC_DISCOVERY_URL=https://auth.example.com/custom/.well-known/openid-configuration

Discovery에서 가져오는 정보¶

필드	용도
`jwks_uri`	JWT 서명 검증을 위한 공개키 URL
`issuer`	토큰 발급자 검증용

JWKS 캐싱¶

성능 최적화를 위해 JWKS는 캐싱됩니다: - 기본 캐시 TTL: 3600초 (1시간) - OIDC_JWKS_CACHE_TTL_SECONDS 환경변수로 조정 가능 - 캐시 만료 시 자동으로 재조회

5. 프론트엔드 통합 가이드¶

인증 헤더 형식¶

모든 API 요청에 Bearer 토큰을 포함해야 합니다:

Authorization: Bearer <access_token>

REST API 요청 예시¶

JavaScript (fetch)¶

const accessToken = 'your-access-token';

const response = await fetch('http://localhost:8000/api/v1/schedules', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
});

if (response.status === 401) {
  // 토큰 만료 또는 유효하지 않음 → 재로그인 필요
  redirectToLogin();
}

const data = await response.json();

Axios 인터셉터¶

import axios from 'axios';

const api = axios.create({
  baseURL: 'http://localhost:8000/api/v1',
});

// 요청 인터셉터: 토큰 자동 추가
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('access_token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// 응답 인터셉터: 401 처리
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // 토큰 갱신 또는 재로그인
      handleTokenRefresh();
    }
    return Promise.reject(error);
  }
);

GraphQL 요청 예시¶

const query = `
  query GetCalendar($startDate: Date!, $endDate: Date!) {
    calendar(startDate: $startDate, endDate: $endDate) {
      days {
        date
        events {
          id
          title
        }
      }
    }
  }
`;

const response = await fetch('http://localhost:8000/graphql', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query,
    variables: {
      startDate: '2026-01-01',
      endDate: '2026-01-31',
    },
  }),
});

에러 응답 처리¶

401 Unauthorized¶

{
  "detail": "Authorization header missing"
}

또는

{
  "detail": "Invalid token: Signature verification failed"
}

처리 방법: 1. Refresh Token으로 새 Access Token 요청 2. 실패 시 로그인 페이지로 리다이렉트

403 Forbidden (GraphQL)¶

GraphQL에서 인증 없이 보호된 쿼리 실행 시:

{
  "data": null,
  "errors": [
    {
      "message": "인증이 필요합니다. Authorization 헤더에 Bearer 토큰을 제공해주세요."
    }
  ]
}

토큰 갱신 (프론트엔드 책임)¶

Access Token 갱신은 프론트엔드에서 OIDC Provider와 직접 처리합니다:

// 예시: oidc-client-ts 사용
import { UserManager } from 'oidc-client-ts';

const userManager = new UserManager({
  authority: 'https://auth.example.com/realms/myrealm',
  client_id: 'my-frontend-app',
  redirect_uri: 'http://localhost:3000/callback',
});

// 자동 토큰 갱신
userManager.events.addAccessTokenExpiring(async () => {
  try {
    await userManager.signinSilent();
  } catch (error) {
    // 갱신 실패 → 재로그인 필요
    await userManager.signinRedirect();
  }
});

6. OIDC Provider별 설정 예시¶

Keycloak¶

# Keycloak 설정
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://keycloak.example.com/realms/myrealm
OIDC_AUDIENCE=my-frontend-app

Keycloak 설정 시 확인 사항: - Client 생성 시 Access Type: public (SPA) 또는 confidential - Valid Redirect URIs: 프론트엔드 URL 등록 - Web Origins: CORS 설정을 위한 프론트엔드 origin

프론트엔드 설정:

const oidcConfig = {
  authority: 'https://keycloak.example.com/realms/myrealm',
  client_id: 'my-frontend-app',
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'openid profile email',
};

Google¶

# Google 설정
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://accounts.google.com
OIDC_AUDIENCE=your-google-client-id.apps.googleusercontent.com

Google Cloud Console 설정: 1. OAuth 2.0 클라이언트 ID 생성 2. 승인된 JavaScript 원본에 프론트엔드 URL 추가 3. 승인된 리다이렉션 URI 추가

프론트엔드 설정:

const oidcConfig = {
  authority: 'https://accounts.google.com',
  client_id: 'your-google-client-id.apps.googleusercontent.com',
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'openid profile email',
};

Auth0¶

# Auth0 설정
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://your-tenant.auth0.com/
OIDC_AUDIENCE=https://your-api-identifier

주의

Auth0의 Issuer URL은 끝에 /가 포함되어야 합니다.

Auth0 Dashboard 설정: 1. Application 생성 (Single Page Application) 2. API 생성 및 Identifier 설정 3. Allowed Callback URLs, Logout URLs, Web Origins 설정

프론트엔드 설정:

const oidcConfig = {
  authority: 'https://your-tenant.auth0.com',
  client_id: 'your-auth0-client-id',
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'openid profile email',
  audience: 'https://your-api-identifier',
};

FAQ¶

Q: 인증 없이 빠르게 테스트하고 싶어요¶

.env 파일에 OIDC_ENABLED=false 추가 후 서버 재시작

Q: 다른 사용자의 데이터가 보이지 않아요¶

정상입니다. 모든 데이터는 owner_id로 격리되어 있습니다.

Q: 토큰 만료 시간은 어떻게 되나요?¶

OIDC Provider 설정에 따라 다릅니다. 일반적으로: - Access Token: 5분 ~ 1시간 - Refresh Token: 1일 ~ 30일

Q: JWKS 캐시가 갱신되지 않아요¶

서버 재시작 또는 캐시 TTL(기본 1시간) 만료를 기다리세요.

파일	설명
`app/core/auth.py`	OIDC 인증 핵심 로직
`app/core/config.py`	환경변수 설정
`app/api/v1/graphql.py`	GraphQL 컨텍스트 인증 처리

OIDC 인증 가이드¶

1. 인증 아키텍처 개요¶

인증 흐름¶

핵심 개념¶

데이터 격리¶

기존 데이터 마이그레이션¶

2. 개발 환경: 인증 비활성화¶

방법 1: 환경변수 설정¶

방법 2: 환경변수 직접 지정¶

인증 비활성화 시 동작¶

테스트 환경¶

3. 프로덕션: OIDC 설정¶

환경변수 목록¶

예시 설정 (.env)¶

Docker Compose 설정¶

4. Well-Known 엔드포인트¶

자동 Discovery¶

커스텀 Discovery URL¶

Discovery에서 가져오는 정보¶

JWKS 캐싱¶

5. 프론트엔드 통합 가이드¶

인증 헤더 형식¶

REST API 요청 예시¶

JavaScript (fetch)¶

Axios 인터셉터¶

GraphQL 요청 예시¶

에러 응답 처리¶

401 Unauthorized¶

403 Forbidden (GraphQL)¶

토큰 갱신 (프론트엔드 책임)¶

6. OIDC Provider별 설정 예시¶

Keycloak¶

Google¶

Auth0¶

관련 코드 참조¶

CurrentUser 모델¶

FastAPI Dependency 사용법¶

FAQ¶

Q: 인증 없이 빠르게 테스트하고 싶어요¶

Q: 다른 사용자의 데이터가 보이지 않아요¶

Q: 토큰 만료 시간은 어떻게 되나요?¶

Q: JWKS 캐시가 갱신되지 않아요¶