Spring Cloud Gateway 기반의 API Gateway 서비스로 Keycloak OAuth2/OIDC 인증과 Google 소셜 로그인을 지원합니다.
- Keycloak 통합 인증: OAuth2/OIDC 기반 사용자 인증
- Google 소셜 로그인: 팝업 기반 소셜 로그인 지원
- 사용자 관리: 회원가입, 로그인, 중복 사용자 감지
- 토큰 관리: Access Token, Refresh Token 발급 및 갱신
- JWT 게이트웨이 검증: JWT 토큰을 게이트웨이 레벨에서 검증하고 헤더로 사용자 정보 전달
- 마이크로서비스 라우팅: 6개 백엔드 서비스로 요청 라우팅
- User Service (사용자 관리)
- Product Service (제품 관리)
- Review Service (리뷰 관리)
- Customer Service (고객 관리)
- Product Details Service (제품 상세)
- ABTest Service (A/B 테스트)
- CORS 설정: 프론트엔드 도메인(
buildingbite.com) 허용 - Health Check: Kubernetes 환경 지원
- Java 11+
- Maven 3.6+
- Kubernetes Cluster
- PostgreSQL Database
- Google OAuth2 Client (Google Console)
- Keycloak 22.x
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/auth/register |
회원가입 |
| POST | /api/auth/login |
로그인 |
| POST | /api/auth/refresh |
토큰 갱신 |
| POST | /api/auth/logout |
로그아웃 |
| GET | /api/auth/userinfo |
사용자 정보 조회 |
| GET | /api/auth/validate |
토큰 검증 |
| GET | /api/auth/test |
인증 컨트롤러 테스트 |
| Method | Endpoint | Description |
|---|---|---|
| PUT | /api/auth/users/me |
현재 사용자 정보 수정 |
| DELETE | /api/auth/users/me |
현재 사용자 계정 삭제 (User Service + Keycloak) |
| PUT | /api/auth/users/me/password |
현재 사용자 패스워드 변경 (Keycloak) |
| Method | Path Pattern | Target Service | Network Address | Description |
|---|---|---|---|---|
| ALL | /api/users/** |
User Service | user-service.user-service.svc.cluster.local |
사용자 관리 API (게이트웨이 직접 처리 제외) |
| ALL | /api/products/** |
Product Service | product-service.product-service.svc.cluster.local:8082 |
제품 관리 API |
| ALL | /api/review/** |
Review Service | review-service.sangsangplus-backend.svc.cluster.local |
리뷰 관리 API |
| ALL | /api/customer/** |
Customer Service | customer-service.sangsangplus-backend.svc.cluster.local |
고객 관리 API |
| ALL | /api/product-details/** |
Product Details Service | product-details-service.sangsangplus-backend.svc.cluster.local |
제품 상세 정보 API |
| ALL | /api/abtest/** |
ABTest Service | abtest-service.sangsangplus-backend.svc.cluster.local |
A/B 테스트 API |
- JWT 필터 적용: 모든 서비스 라우팅에
JwtAuth필터 적용 - 토큰 없는 요청: JWT 토큰이 없으면 인증 헤더 없이 다운스트림으로 전달
- 토큰 있는 요청: JWT 검증 후 사용자 정보를 헤더로 다운스트림에 전달
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/auth/google |
Google 소셜 로그인 |
| GET | /api/auth/google/callback |
Google 소셜 로그인 콜백 (내부용) |
이 게이트웨이는 중앙 집중식 JWT 검증을 수행합니다. 모든 보호된 엔드포인트에 대한 요청은 게이트웨이에서 JWT 토큰을 검증하고, 검증된 사용자 정보를 헤더로 다운스트림 서비스에 전달합니다.
- 토큰 추출: Authorization Bearer 토큰 또는 쿠키에서 JWT 토큰 추출
- RSA 공개키 검증: Keycloak RSA 공개키로 토큰 서명 검증
- 클레임 추출: 토큰에서 사용자 이메일과 역할 정보 추출
- 헤더 추가: 검증된 정보를 HTTP 헤더로 추가
- 요청 전달: 헤더와 함께 다운스트림 서비스로 요청 전달
| 헤더명 | 설명 | 예시 값 | 데이터 소스 |
|---|---|---|---|
X-User-Email |
사용자 이메일 | user@example.com |
JWT email 클레임 |
X-User-Role |
사용자 역할 (쉼표 구분) | USER 또는 USER,ADMIN |
JWT realm_access.roles |
X-User-Provider |
로그인 제공자 | LOCAL 또는 GOOGLE |
JWT provider 커스텀 속성 |
X-User-LoginCount |
총 로그인 횟수 | 15 |
JWT loginCount 커스텀 속성 |
X-User-LastLoginAt |
마지막 로그인 시간 | 2025-01-15T10:30:00 |
JWT lastLoginAt 커스텀 속성 |
- 헤더 없이 다운스트림 서비스로 통과
- 각 서비스에서 비인증 사용자로 처리 가능
# JWT 검증 필터가 적용되는 라우트
spring:
cloud:
gateway:
routes:
- id: user-service
uri: http://user-service.user-service.svc.cluster.local
predicates:
- Path=/api/users/**
filters:
- JwtAuth # JWT 검증 필터 적용다운스트림 서비스는 JWT 토큰을 검증할 필요 없이 헤더에서 사용자 정보를 직접 사용할 수 있습니다:
// Spring Boot Controller 예시
@RestController
public class UserController {
@GetMapping("/api/users/me")
public ResponseEntity<User> getCurrentUser(
@RequestHeader("X-User-Email") String email,
@RequestHeader("X-User-Role") String roles) {
// 게이트웨이에서 검증된 사용자 정보 사용
return userService.findByEmail(email);
}
}이 게이트웨이는 Keycloak에서 다음과 같은 사용자 데이터를 자동으로 관리합니다:
| 필드명 | 타입 | 설명 | 예시 값 |
|---|---|---|---|
username |
String | 로그인 ID (이메일과 동일) | user@example.com |
email |
String | 이메일 주소 | user@example.com |
emailVerified |
Boolean | 이메일 인증 여부 | true |
enabled |
Boolean | 계정 활성화 여부 | true |
createdTimestamp |
Long | 계정 생성 시간 (Unix timestamp) | 1672531200000 |
| 속성명 | 타입 | 설명 | 기본값 | 업데이트 시점 |
|---|---|---|---|---|
role |
String | 사용자 역할 | USER |
회원가입 시 |
provider |
String | 로그인 제공자 | LOCAL |
회원가업/소셜로그인 시 |
loginCount |
String | 총 로그인 횟수 | 0 |
매 로그인 시 +1 |
lastLoginAt |
String | 마지막 로그인 시간 | 빈 문자열 | 매 로그인 시 현재시간 |
createdAt |
String | 커스텀 생성 시간 | 현재시간 | 회원가입 시 |
회원가입 → Keycloak User 생성 + 커스텀 속성 초기화
↓
로그인 → JWT 발급 + 로그인 통계 업데이트 (loginCount++, lastLoginAt)
↓
API 요청 → Gateway JWT 검증 → 모든 사용자 정보를 헤더로 전달
↓
다운스트림 서비스 → 헤더에서 사용자 정보 활용
- Google 로그인:
provider=GOOGLE, 기타 속성은 일반 회원가입과 동일 - 자동 동기화: 소셜 로그인 사용자도 동일한 커스텀 속성 구조 적용
프론트엔드에서 Google 로그인 버튼을 구현할 때 리다이렉트 방식을 사용합니다:
<!-- HTML 버튼 -->
<a href="https://oauth.buildingbite.com/api/auth/google" class="google-login-button">
Google로 로그인
</a>
<!-- 또는 JavaScript로 이동 -->
<button onclick="loginWithGoogle()">Google로 로그인</button>
<script>
function loginWithGoogle() {
// 현재 페이지에서 Google 로그인 페이지로 리다이렉트
window.location.href = 'https://oauth.buildingbite.com/api/auth/google';
}
</script>로그인 성공 후 콜백 페이지에서 토큰을 처리하세요:
<!-- 콜백 처리 페이지 -->
<script>
// URL에서 파라미터 추출
const urlParams = new URLSearchParams(window.location.search);
const token = urlParams.get('token');
const refreshToken = urlParams.get('refreshToken');
const expiresIn = urlParams.get('expiresIn');
const error = urlParams.get('error');
if (error) {
alert('로그인 실패: ' + error);
window.location.href = '/login';
} else if (token && refreshToken) {
// 토큰을 localStorage에 저장
localStorage.setItem('accessToken', token);
localStorage.setItem('refreshToken', refreshToken);
localStorage.setItem('tokenExpiresIn', expiresIn);
// URL에서 토큰 정보 제거 (보안상 중요!)
window.history.replaceState({}, document.title, '/');
// 홈페이지로 이동
window.location.href = '/';
} else {
// 로그인 실패 처리
window.location.href = '/login';
}
</script>import React from 'react';
const GoogleLoginButton = () => {
const handleGoogleLogin = () => {
// 현재 페이지에서 Google 로그인으로 이동
window.location.href = 'https://oauth.buildingbite.com/api/auth/google';
};
return (
<button onClick={handleGoogleLogin} className="google-login-button">
Google로 로그인
</button>
);
};
// 콜백 처리 컴포넌트
const AuthCallback = () => {
React.useEffect(() => {
const urlParams = new URLSearchParams(window.location.search);
const token = urlParams.get('token');
const refreshToken = urlParams.get('refreshToken');
const expiresIn = urlParams.get('expiresIn');
const error = urlParams.get('error');
if (error) {
console.error('로그인 오류:', error);
window.location.href = '/login';
return;
}
if (token && refreshToken) {
// 토큰 저장
localStorage.setItem('accessToken', token);
localStorage.setItem('refreshToken', refreshToken);
localStorage.setItem('tokenExpiresIn', expiresIn);
// URL 정리 후 홈으로 이동
window.history.replaceState({}, document.title, '/');
window.location.href = '/';
} else {
window.location.href = '/login';
}
}, []);
return <div>로그인 처리 중...</div>;
};
export default { GoogleLoginButton, AuthCallback };<template>
<button @click="loginWithGoogle" class="google-login-btn">
Google로 로그인
</button>
</template>
<script>
export default {
methods: {
loginWithGoogle() {
const popup = window.open(
'https://oauth.buildingbite.com/api/auth/google',
'googleLogin',
'width=500,height=600,scrollbars=yes,resizable=yes'
);
const handleMessage = (event) => {
if (event.origin !== 'https://oauth.buildingbite.com') return;
const { success, error, token, refreshToken } = event.data;
if (success) {
// 토큰 저장
localStorage.setItem('accessToken', token);
localStorage.setItem('refreshToken', refreshToken);
// 루트(/)로 이동
window.location.href = '/';
} else {
this.$toast.error('로그인 실패: ' + error);
}
popup.close();
window.removeEventListener('message', handleMessage);
};
window.addEventListener('message', handleMessage);
}
}
}
</script>핵심 사항:
- ✅ 간단한 URL:
https://oauth.buildingbite.com/api/auth/google - ✅ 팝업 방식: 팝업으로 로그인하고 결과를 메시지로 전달
- ✅ 성공 시: 토큰을 받아서 저장 후 원하는 페이지로 이동
- ✅ 실패 시: 에러 메시지를 받아서 처리
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/health |
Health Check |
| 변수명 | 설명 | 기본값 | Kubernetes 설정값 |
|---|---|---|---|
USER_SERVICE_URL |
User 서비스 URL | http://user-service |
http://user-service.user-service.svc.cluster.local |
PRODUCT_SERVICE_URL |
Product 서비스 URL | http://product-service |
http://product-service.product-service.svc.cluster.local:8082 |
REVIEW_SERVICE_URL |
Review 서비스 URL | http://review-service |
http://review-service.sangsangplus-backend.svc.cluster.local |
CUSTOMER_SERVICE_URL |
Customer 서비스 URL | http://customer-service |
http://customer-service.sangsangplus-backend.svc.cluster.local |
PRODUCT_DETAILS_SERVICE_URL |
Product Details 서비스 URL | http://product-details-service |
http://product-details-service.sangsangplus-backend.svc.cluster.local |
ABTEST_SERVICE_URL |
ABTest 서비스 URL | http://abtest-service |
http://abtest-service.sangsangplus-backend.svc.cluster.local |
FRONTEND_URL |
프론트엔드 URL | https://buildingbite.com |
OAuth2 리다이렉트용 |
| 변수명 | 설명 | 기본값 | 비고 |
|---|---|---|---|
KEYCLOAK_AUTH_SERVER_URL |
Keycloak 서버 URL | http://keycloak:8080 |
K8s 내부 URL |
KEYCLOAK_REALM |
Keycloak Realm 이름 | sangsang-plus |
Realm 생성 필요 |
KEYCLOAK_CLIENT_ID |
Keycloak 클라이언트 ID | gateway-client |
Client 생성 필요 |
KEYCLOAK_CLIENT_SECRET |
Keycloak 클라이언트 시크릿 | - | 필수 설정 |
KEYCLOAK_ISSUER_URI |
JWT Issuer URI | http://keycloak:8080/realms/sangsang-plus |
토큰 검증용 |
| 변수명 | 설명 | 기본값 |
|---|---|---|
JWT_SECRET |
JWT 서명용 비밀키 | mySecretKey |
JWT_ACCESS_TOKEN_EXPIRATION |
액세스 토큰 만료시간 | - |
JWT_REFRESH_TOKEN_EXPIRATION |
리프레시 토큰 만료시간 | - |
| 변수명 | 설명 | 비고 |
|---|---|---|
GOOGLE_CLIENT_ID |
Google OAuth 클라이언트 ID | 필수 설정 |
GOOGLE_CLIENT_SECRET |
Google OAuth 클라이언트 시크릿 | 필수 설정 |
- Java 11+
- Maven 3.6+
- Docker (선택사항)
git clone <repository-url>
cd sangsang-plus-gateway# Maven 빌드
mvn clean package
# 애플리케이션 실행
java -jar target/gateway-service-1.0.0.jarexport USER_SERVICE_URL=http://localhost:8081
export JWT_SECRET=your-super-secret-jwt-keydocker build -t buildingbite/sangsangplus-gateway:latest .docker run -p 8080:8080 \
-e USER_SERVICE_URL=http://user-service \
-e JWT_SECRET=your-super-secret-jwt-key \
buildingbite/sangsangplus-gateway:latest이 프로젝트는 두 개의 주요 인프라 파일을 사용합니다:
- 용도: Kubernetes 클러스터에 Nginx Ingress Controller 설치
- 포함 내용:
- Nginx Ingress Controller Deployment
- LoadBalancer Service (고정 IP: 20.249.144.238)
- RBAC 권한 설정
- IngressClass 정의
- 실행 시점: 클러스터 초기 설정 시 한 번만
- 실행 명령:
kubectl apply -f ingress-setup.yaml
- 용도: 도메인과 서비스 간 라우팅 규칙 정의
- 포함 내용:
oauth.buildingbite.com→ Gateway Service 라우팅buildingbite.com→ Frontend Service 라우팅
- 실행 시점: 라우팅 규칙 변경 시마다
- 실행 명령:
kubectl apply -f gateway-ingress.yaml
# 1. Nginx Ingress Controller 설치 (최초 1회)
kubectl apply -f ingress-setup.yaml
# 2. Ingress Controller 상태 확인
kubectl get pods -n ingress-nginx
kubectl get svc -n ingress-nginx
# 3. 애플리케이션 라우팅 규칙 적용
kubectl apply -f gateway-ingress.yaml
# 4. Ingress 상태 확인
kubectl get ingress -AInternet
↓
[LoadBalancer: 20.249.144.238]
↓
[Nginx Ingress Controller]
↓
├── oauth.buildingbite.com → Gateway Service (ClusterIP)
└── buildingbite.com → Frontend Service (ClusterIP)
다음 서비스들이 먼저 배포되어 있어야 합니다:
- Nginx Ingress Controller (네임스페이스:
ingress-nginx) - Keycloak (네임스페이스:
default또는keycloak) - User Service (네임스페이스:
user-service) - Product Service (네임스페이스:
product-service)
kubectl create secret generic keycloak-secrets \
--from-literal=admin-password='your-admin-password' \
--from-literal=azure-db-password='your-azure-db-password'kubectl apply -f keycloak-deployment-azure.yamlKeycloak 관리 콘솔에서 다음 설정을 수행:
- Realm 생성:
sangsang-plus - Client 생성:
gateway-client- Client Protocol:
openid-connect - Access Type:
confidential - Valid Redirect URIs:
https://oauth.buildingbite.com/* - Web Origins:
https://oauth.buildingbite.com
- Client Protocol:
- Client Secret 복사: Credentials 탭에서 Secret 값 복사
- Roles 생성:
USER,ADMIN - Test User 생성: 테스트용 사용자 계정
# Gateway 전용 네임스페이스 생성 (선택사항)
kubectl create namespace gatewaykubectl create secret generic gateway-secrets \
--from-literal=keycloak-client-secret='your-keycloak-client-secret' \ # 네임스페이스 사용 시kubectl create configmap gateway-config \
--from-literal=KEYCLOAK_AUTH_SERVER_URL='http://keycloak:8080' \
--from-literal=KEYCLOAK_REALM='sangsang-plus' \
--from-literal=KEYCLOAK_CLIENT_ID='gateway-client' \게이트웨이는 JWT 토큰 검증을 위해 RSA public key를 사용합니다. Public key는 Kubernetes Secret으로 안전하게 관리됩니다.
# OpenSSL 설치 (Ubuntu/Debian)
sudo apt update
sudo apt install openssl libssl-dev
# RSA 키 쌍 생성
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem
# Keycloak에서 사용할 수 있도록 private key를 Keycloak에 설정
# public key는 게이트웨이에서 JWT 검증용으로 사용# public.pem 파일로부터 Kubernetes Secret 생성
kubectl create secret generic jwt-public-key --from-file=public.pem=public.pem
# Secret 확인
kubectl get secret jwt-public-key
kubectl describe secret jwt-public-key시나리오: Keycloak에서 키를 로테이션하거나 새로운 키 쌍을 사용해야 하는 경우
# 1. 새로운 키 쌍 생성
openssl genrsa -out new-private.pem 2048
openssl rsa -in new-private.pem -pubout -out new-public.pem
# 2. Keycloak에 새로운 private key 설정
# - Keycloak Admin Console → Realm Settings → Keys → Providers
# - 새로운 RSA key provider 추가 또는 기존 키 교체
# 3. 기존 Secret 삭제
kubectl delete secret jwt-public-key
# 4. 새로운 Public Key로 Secret 재생성
kubectl create secret generic jwt-public-key --from-file=public.pem=new-public.pem
# 5. 게이트웨이 재시작 (Secret이 마운트된 Pod 재시작)
kubectl rollout restart deployment sangsang-plus-gateway
# 6. 재시작 완료 확인
kubectl rollout status deployment sangsang-plus-gateway프로덕션 환경에서 무중단으로 키를 교체하는 방법:
# 1. Keycloak에서 새로운 키를 추가 (기존 키와 함께 사용)
# 2. 새로운 키로 Secret 업데이트
kubectl create secret generic jwt-public-key-new --from-file=public.pem=new-public.pem
# 3. Deployment에서 새로운 Secret 사용하도록 업데이트
kubectl patch deployment sangsang-plus-gateway \
-p '{"spec":{"template":{"spec":{"volumes":[{"name":"jwt-public-key","secret":{"secretName":"jwt-public-key-new"}}]}}}}'
# 4. 모든 Pod이 새로운 키로 업데이트된 후 기존 Secret 삭제
kubectl delete secret jwt-public-key
kubectl delete secret jwt-public-key-new
# 5. 최종적으로 정상 이름으로 Secret 재생성
kubectl create secret generic jwt-public-key --from-file=public.pem=new-public.pem키 교체 후 정상 동작하는지 확인:
# 1. 게이트웨이 로그에서 키 로드 확인
kubectl logs deployment/sangsang-plus-gateway | grep -i "public"
# 출력: "Loading public key from file: /app/secrets/public.pem"
# 출력: "Successfully loaded public key from file"
# 2. JWT 토큰으로 API 호출 테스트
# 유효한 토큰으로 테스트
curl https://oauth.buildingbite.com/api/users/me \
-H "Authorization: Bearer YOUR_VALID_JWT_TOKEN"
# 잘못된 토큰으로 테스트 (401 에러가 나와야 정상)
curl https://oauth.buildingbite.com/api/users/me \
-H "Authorization: Bearer invalid-token"- Private Key 보안: private.pem 파일은 절대 Git에 커밋하지 마세요
- 키 순환: 보안을 위해 주기적으로 키를 교체하는 것을 권장합니다 (예: 6개월마다)
- 백업: 키 교체 전에 기존 키와 설정을 백업해두세요
- 테스트: 개발 환경에서 먼저 키 교체를 테스트한 후 프로덕션에 적용하세요
# Secret 백업
kubectl get secret jwt-public-key -o yaml > jwt-public-key-backup.yaml
# 복구 시
kubectl apply -f jwt-public-key-backup.yaml네임스페이스를 사용하는 경우 k8s-deployment.yaml 파일을 수정하세요:
# 각 리소스에 namespace 추가
metadata:
name: sangsang-plus-gateway
namespace: gateway # 추가# 기본 네임스페이스에 배포
kubectl apply -f k8s-deployment.yaml
# 특정 네임스페이스에 배포
kubectl apply -f k8s-deployment.yaml -n gateway# Pod 상태 확인
kubectl get pods -l app=sangsang-plus-gateway -n gateway
# 서비스 확인
kubectl get svc sangsang-plus-gateway -n gateway
# 로그 확인
kubectl logs -f deployment/sangsang-plus-gateway -n gateway
# Secret 확인
kubectl get secrets gateway-secrets -n gateway# User Service 연결 테스트
kubectl exec -it deployment/sangsang-plus-gateway -n gateway -- \
curl -f http://user-service.user-service.svc.cluster.local/api/health
# Product Service 연결 테스트
kubectl exec -it deployment/sangsang-plus-gateway -n gateway -- \
curl -f http://product-service.product-service.svc.cluster.local/api/health- 게이트웨이: LoadBalancer 타입으로 외부 노출
- User 서비스: ClusterIP로 내부 통신
- 서비스 URL:
http://user-service.user-service.svc.cluster.local
- 게이트웨이: 8080 (내부), 80 (외부)
- User 서비스: 80/443 (ClusterIP)
증상: /api/keycloak/login 접근 시 403 에러
원인: Spring Security 설정 문제
해결:
// SecurityConfig.java에서 확인
.antMatchers("/api/keycloak/**").permitAll()증상: 로그인 시 400 에러 원인: 이메일 validation 실패 해결: 이메일 형식으로 로그인
{
"email": "test@example.com", // "testuser" X
"password": "test123"
}# Keycloak 서비스 확인
kubectl get svc keycloak
kubectl get pods -l app=keycloak
# 연결 테스트
kubectl run -it --rm test-curl --image=curlimages/curl --restart=Never -- \
curl http://keycloak:8080/realms/sangsang-plus/.well-known/openid-configuration# User 서비스 상태 확인
kubectl get svc -n user-service
kubectl get pods -n user-service
# 네트워크 연결 테스트
kubectl exec -it deployment/sangsang-plus-gateway -n gateway -- \
curl -f http://user-service.user-service.svc.cluster.local/api/health# Product 서비스 상태 확인
kubectl get svc -n product-service
kubectl get pods -n product-service
# 네트워크 연결 테스트
kubectl exec -it deployment/sangsang-plus-gateway -n gateway -- \
curl -f http://product-service.product-service.svc.cluster.local/api/health# Secret 존재 확인
kubectl get secrets gateway-secrets -n gateway
# Secret 내용 확인 (base64 디코딩)
kubectl get secret gateway-secrets -n gateway -o jsonpath='{.data.jwt-secret}' | base64 -d만료되지 않은 토큰이 인증 실패할 경우:
- 로그아웃 후 해당 토큰이 블랙리스트에 추가됨
- 새로운 로그인으로 새 토큰 발급 필요
# 전체 로그 확인
kubectl logs -f deployment/sangsang-plus-gateway -n gateway
# 특정 시간대 로그
kubectl logs deployment/sangsang-plus-gateway -n gateway --since=10m
# 이전 컨테이너 로그 (재시작된 경우)
kubectl logs deployment/sangsang-plus-gateway -n gateway --previous# JWT 관련 오류
kubectl logs deployment/sangsang-plus-gateway -n gateway | grep -i jwt
# OAuth2 관련 오류
kubectl logs deployment/sangsang-plus-gateway -n gateway | grep -i oauth
# 서비스 연결 오류
kubectl logs deployment/sangsang-plus-gateway -n gateway | grep -i "connection"# PVC 상태 확인
kubectl get pvc -n gateway
# StorageClass 확인
kubectl get storageclass# 이미지 풀 오류 확인
kubectl describe pod <pod-name> -n gateway
# 이미지 빌드 및 푸시 재시도
docker build -t buildingbite/sangsangplus-gateway:latest .
docker push buildingbite/sangsangplus-gateway:latest
kubectl rollout restart deployment/sangsang-plus-gateway -n gateway# 리소스 사용량 확인
kubectl top pods -n gateway
kubectl describe pod <pod-name> -n gateway
# 리소스 제한 조정 (k8s-deployment.yaml)
resources:
requests:
memory: "512Mi" # 256Mi에서 증가
cpu: "500m" # 250m에서 증가
limits:
memory: "1Gi" # 512Mi에서 증가
cpu: "1000m" # 500m에서 증가-
User Service 상태 확인
kubectl get pods -n user-service kubectl logs deployment/user-service -n user-service
-
User Service Secret 확인
# User Service는 다음 secret이 필요합니다: kubectl create secret generic user-service-secrets \ --from-literal=db-username='postgre' \ --from-literal=db-password='postgre' \ --from-literal=encryption-key='your-encryption-key' \ --from-literal=jwt-secret='your-jwt-secret' \ -n user-service
-
Gateway OAuth2 로그 확인
kubectl logs deployment/sangsang-plus-gateway | grep -i oauth
OAuth2 로그인이 예상과 다르게 동작할 경우:
- 증상: Google 로그인 페이지를 거치지 않고 바로 성공 페이지로 리다이렉트
- 원인: 브라우저에 이미 Google 세션이나 JWT 토큰이 존재
- 해결 방법:
- 브라우저 시크릿/프라이빗 모드 사용
- 브라우저 쿠키 삭제:
buildingbite.com도메인의 모든 쿠키accounts.google.com쿠키
- Google 계정에서 로그아웃 후 재시도
# 1. 코드 변경 후 커밋 & 푸시
git add .
git commit -m "feat: 기능 추가"
git push origin main
# GitHub Actions 또는 CI/CD 파이프라인이 자동으로:
# - Docker 이미지 빌드
# - 이미지 푸시
# - Kubernetes 배포# 1. 코드 변경 후 이미지 빌드
docker build -t buildingbite/sangsangplus-gateway:latest .
# 2. 이미지 푸시
docker push buildingbite/sangsangplus-gateway:latest
# 3. Kubernetes 재배포
kubectl rollout restart deployment/sangsang-plus-gateway -n gateway
# 4. 배포 상태 확인
kubectl rollout status deployment/sangsang-plus-gateway -n gateway# 개발용 이미지 태그 사용
docker build -t buildingbite/sangsangplus-gateway:dev .
docker push buildingbite/sangsangplus-gateway:dev
# 개발 환경 배포
kubectl set image deployment/sangsang-plus-gateway \
gateway=buildingbite/sangsangplus-gateway:dev -n gateway-dev# 프로덕션용 이미지 태그 사용
docker build -t buildingbite/sangsangplus-gateway:v1.0.0 .
docker push buildingbite/sangsangplus-gateway:v1.0.0
# 프로덕션 환경 배포
kubectl set image deployment/sangsang-plus-gateway \
gateway=buildingbite/sangsangplus-gateway:v1.0.0 -n gateway-prod각 환경별로 별도 네임스페이스 사용을 권장합니다:
# 개발 환경
kubectl create namespace gateway-dev
kubectl create secret generic gateway-secrets -n gateway-dev \
--from-literal=jwt-secret='dev-jwt-secret'
# 스테이징 환경
kubectl create namespace gateway-staging
kubectl create secret generic gateway-secrets -n gateway-staging \
--from-literal=jwt-secret='staging-jwt-secret'
# 프로덕션 환경
kubectl create namespace gateway-prod
kubectl create secret generic gateway-secrets -n gateway-prod \
--from-literal=jwt-secret='production-jwt-secret'프로덕션 환경에서는 다음 설정을 권장합니다:
# k8s-deployment.yaml에서 수정
spec:
replicas: 3 # 기본 1에서 3으로 증가
# Pod Disruption Budget 추가
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: sangsang-plus-gateway-pdb
spec:
minAvailable: 2
selector:
matchLabels:
app: sangsang-plus-gatewaycurl -X POST https://oauth.buildingbite.com/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "newuser@example.com",
"name": "새로운 사용자",
"password": "password123!"
}'응답 예시 (성공)
{
"success": true,
"message": "로그인 성공",
"token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJUVjBoVFFBV1I4R3d...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmYWQxZjYyNC0z...",
"expiresIn": 300
}curl -X POST https://oauth.buildingbite.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com",
"password": "test123"
}'응답 예시 (성공)
{
"success": true,
"message": "로그인 성공",
"token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJUVjBoVFFBV1I4R3d...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmYWQxZjYyNC0z...",
"expiresIn": 300
}응답 예시 (실패)
{
"success": false,
"message": "USER_NOT_FOUND",
"token": null,
"refreshToken": null,
"expiresIn": null
}curl -X POST https://oauth.buildingbite.com/api/auth/refresh \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmYWQxZjYyNC0z..."
}'응답 예시
{
"success": true,
"message": "토큰 갱신 성공",
"token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJUVjBoVFFBV1I4R3d...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmYWQxZjYyNC0z...",
"expiresIn": 300
}curl -X POST https://oauth.buildingbite.com/api/auth/logout \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkI..." \
-d '{
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmYWQxZjYyNC0z..."
}'응답 예시
{
"success": true,
"message": "로그아웃 성공"
}curl -X GET https://oauth.buildingbite.com/api/auth/userinfo \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkI..."응답 예시 (Test Data)
{
"id": "test-id",
"username": "test-user",
"email": "test@example.com"
}주의: 이 API는 현재 하드코딩된 테스트 데이터를 반환합니다.
curl -X GET https://oauth.buildingbite.com/api/auth/validate \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkI..."응답 예시 (Test Data)
{
"valid": true,
"username": "test-user",
"roles": ["USER"]
}주의: 이 API는 현재 하드코딩된 테스트 데이터를 반환합니다.
curl -X GET https://oauth.buildingbite.com/api/health응답 예시
{
"service": "gateway-service",
"status": "UP"
}curl -X PUT https://oauth.buildingbite.com/api/auth/users/me \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkI..." \
-d '{
"name": "새로운 이름",
"phone": "010-1234-5678"
}'응답 예시 (성공)
{
"success": true,
"message": "사용자 정보가 성공적으로 수정되었습니다"
}응답 예시 (실패)
{
"success": false,
"message": "사용자를 찾을 수 없습니다"
}curl -X DELETE https://oauth.buildingbite.com/api/auth/users/me \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkI..."응답 예시 (성공)
{
"success": true,
"message": "계정이 성공적으로 삭제되었습니다"
}응답 예시 (부분 성공)
{
"success": true,
"message": "계정이 부분적으로 삭제되었습니다",
"userServiceDeleted": true,
"keycloakDeleted": false
}응답 예시 (실패)
{
"success": false,
"message": "계정 삭제 실패"
}curl -X PUT https://oauth.buildingbite.com/api/auth/users/me/password \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkI..." \
-d '{
"newPassword": "newpassword123"
}'응답 예시 (성공)
{
"success": true,
"message": "패스워드가 성공적으로 변경되었습니다"
}응답 예시 (검증 실패)
{
"success": false,
"message": "패스워드는 최소 8자 이상이어야 합니다"
}응답 예시 (실패)
{
"success": false,
"message": "패스워드 변경에 실패했습니다"
}모든 인증이 필요한 API는 다음과 같이 Bearer 토큰을 포함해야 합니다:
curl -X GET https://oauth.buildingbite.com/api/protected-endpoint \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkI..."- 모든 마이크로서비스의 인증을 Keycloak에서 통합 관리
- 사용자 정보, 권한, 세션을 한 곳에서 관리
- 표준 OAuth2/OIDC 프로토콜 지원
- 사용자명/비밀번호 인증
- 소셜 로그인 (Google, Facebook, GitHub 등)
- SAML, LDAP/AD 연동
- 2FA (Two-Factor Authentication)
- JWT 토큰 자동 발급 및 검증
- 토큰 만료 시간 중앙 관리
- Refresh Token 자동 처리
- PKCE (Proof Key for Code Exchange) 지원
- 토큰 암호화 및 서명
- Rate Limiting
- Brute Force Protection
Keycloak에서 발급하는 JWT 토큰의 구조:
{
"exp": 1753749483, // 만료 시간
"iat": 1753749183, // 발급 시간
"jti": "a6e82ac2-147e-48bc-93f4-67526b5d59e6",
"iss": "http://oauth.buildingbite.com/realms/sangsang-plus",
"aud": "account",
"sub": "e63b9f80-1f50-43d9-8ebc-b997654203f4", // 사용자 ID
"typ": "Bearer",
"azp": "gateway-client",
"session_state": "1ada7af1-cc23-4420-a23c-a5b2f95637bb",
"acr": "1",
"allowed-origins": ["https://oauth.buildingbite.com"],
"realm_access": {
"roles": ["offline_access", "uma_authorization", "USER"]
},
"resource_access": {
"account": {
"roles": ["manage-account", "view-profile"]
}
},
"scope": "profile email",
"email_verified": true,
"name": "Test User",
"preferred_username": "testuser",
"given_name": "Test",
"family_name": "User",
"email": "test@example.com"
}- HTTP-Only Secure Cookie로 저장 권장
- 30일 유효 기간 (설정 가능)
- Access Token 재발급에만 사용
- 이 저장소를 포크합니다
- 새로운 기능 브랜치를 생성합니다 (
git checkout -b feature/amazing-feature) - 변경 사항을 커밋합니다 (
git commit -m 'Add amazing feature') - 브랜치에 푸시합니다 (
git push origin feature/amazing-feature) - Pull Request를 생성합니다
HTTPS를 사용하는 경우 Ingress 또는 LoadBalancer에서 SSL 인증서를 설정하세요:
# ingress.yaml 예시
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: sangsang-plus-gateway-ingress
annotations:
kubernetes.io/ingress.class: nginx
cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
tls:
- hosts:
- oauth.buildingbite.com
secretName: gateway-tls
rules:
- host: oauth.buildingbite.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: sangsang-plus-gateway
port:
number: 80# 메트릭 수집을 위한 ServiceMonitor (Prometheus)
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: sangsang-plus-gateway
spec:
selector:
matchLabels:
app: sangsang-plus-gateway
endpoints:
- port: http
path: /actuator/prometheus중요한 설정들의 백업:
# Secret 백업
kubectl get secret gateway-secrets -n gateway -o yaml > gateway-secrets-backup.yaml
# ConfigMap 백업 (있는 경우)
kubectl get configmap -n gateway -o yaml > gateway-configmaps-backup.yaml
# 전체 네임스페이스 백업
kubectl get all -n gateway -o yaml > gateway-namespace-backup.yaml# k8s-deployment.yaml에서 환경변수 추가
env:
- name: JAVA_OPTS
value: "-Xms256m -Xmx512m -XX:+UseG1GC -XX:+UseStringDeduplication"# application.yml에 추가 설정
spring:
datasource:
hikari:
maximum-pool-size: 20
minimum-idle: 5
connection-timeout: 30000apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: sangsang-plus-gateway-netpol
namespace: gateway
spec:
podSelector:
matchLabels:
app: sangsang-plus-gateway
policyTypes:
- Ingress
- Egress
ingress:
- from:
- namespaceSelector:
matchLabels:
name: ingress-nginx
ports:
- protocol: TCP
port: 8080
egress:
- to:
- namespaceSelector:
matchLabels:
name: user-service
- to:
- namespaceSelector:
matchLabels:
name: product-service이 프로젝트는 MIT 라이선스 하에 있습니다.