OAuth2-Proxy 설치 가이드

1. 개요

본 문서는 gitops 저장소의 /oauth2-proxy 디렉터리 구조를 기반으로 OAuth2-Proxy를 Kubernetes 클러스터에 설치하는 전체 과정을 안내합니다. OAuth2-Proxy는 다양한 OAuth2/OIDC 제공자(Google, GitHub, Keycloak 등)와 연동하여 애플리케이션에 대한 인증을 제공하는 리버스 프록시입니다. Kustomize, Helm, Makefile을 활용한 배포 자동화, 환경별 설정, 주요 커스텀 옵션, 운영 팁을 포함합니다.

2. 사전 요구사항

• Kubernetes 클러스터: v1.30 이상
• 로컬 도구: kubectl, kustomize, helm 설치 완료
• 인증서: cert-manager를 통한 TLS 인증서 발급 및 네임스페이스 간 복제 구성 준비
• Redis: 세션 스토리지로 Redis가 필요 (선택적, cookie 기반도 가능)
• DNS 등록
  • oauth2-proxy.cnapcloud.com
  • httpbin.cnapcloud.com
• Keycloak Client 설정: oauth2-proxy client 생성(client scopes에 groups 포함)

3. 디렉터리 구조 및 역할

oauth2-proxy/
├── Makefile                           # 배포 자동화 스크립트
├── kustomize/
│   ├── base/                          # 공통 리소스(Helm 차트, CRD 등)
│   └── overlays/
│       └── dev/                       # dev 환경 설정
│           ├── kustomization.yaml     # Kustomize 구성
│           ├── helm/
│           │   ├── values.yaml        # OAuth2-Proxy 설정
│           │   └── helm-chart.yaml    # HelmChartInflationGenerator
│           ├── patches/               # 패치 파일들
│           ├── resources/             # 추가 리소스
│           └── tls/                   # TLS 관련 설정

• Makefile: apply, delete, preview 등 배포 자동화 명령어
• kustomize/base/: 모든 환경에 공통 적용될 리소스(Helm 차트, CRD 등)
• kustomize/overlays/dev/: dev 환경 특화 설정
• helm/values.yaml: OAuth2-Proxy Helm Chart 커스터마이징 설정

4. 설치 단계

4.1. values.yaml 커스터마이징

kustomize/overlays/dev/helm/values.yaml 파일을 열어 주요 설정을 수정합니다.

4.1.1. OIDC 제공자 설정

config:
  clientID: "oauth2-proxy"
  clientSecret: "your-client-secret"
  cookieSecret: "your-cookie-secret"
  
  configFile: |-
    provider="oidc"
    provider_display_name="Keycloak"
    oidc_issuer_url="https://keycloak.cnapcloud.com/realms/cnap"
    redirect_url="https://oauth2-proxy.cnapcloud.com/oauth2/callback"
    scope="openid profile email groups"

4.1.2. 세션 스토리지 설정

sessionStorage:
  type: redis
  redis:
    password: "your-redis-password"
    clientType: standalone

4.1.3. Ingress 설정

ingress:
  enabled: true
  className: nginx
  hosts:
    - oauth2-proxy.cnapcloud.com
  tls:
    - secretName: oauth2-proxy-tls

4.1.4. 인증 도메인 및 라우팅

config:
  configFile: |-
    whitelist_domains=[".cnapcloud.com"]
    email_domains=["*"]
    skip_auth_routes=["GET=^/api/token", "^/status"]

4.2. Kustomize 구성

4.2.1. kustomization.yaml 구성

kustomize/overlays/dev/kustomization.yaml에서 namespace, generators, resources, patches 등 지정

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: security
generators:
  - ./helm/helm-chart.yaml

resources:
   :

patches:
- target:
    kind: Deployment
    name: oauth2-proxy
  path: patches/add-host-alias.yaml

add-host-alias.yaml는 내부 IngressController를 사용하여 Keycloak 서비스에 접근하는 경우 추가한다. ingress-nginx-controller.ingress-nginx.svc의 ClusterIP로 설정한다.

4.2.2. HelmChartInflationGenerator 설정

helm/helm-chart.yaml에서 Helm 차트 경로와 values 파일 지정

apiVersion: builtin
kind: HelmChartInflationGenerator
metadata:
  name: oauth2-proxy
name: oauth2-proxy
chartHome: ../../base/helm
chart: oauth2-proxy
releaseName: oauth2-proxy
valuesFile: ./helm/values.yaml
includeCRDs: true
namespace: security

4.3. 배포 프로세스 (Makefile 활용)

Step 1: Namespace 생성

make namespace DEPLOY_ENV=dev

Step 2: 배포 미리보기

make preview DEPLOY_ENV=dev

Step 3: 배포 실행

make apply DEPLOY_ENV=dev

Step 4: 배포 상태 확인

kubectl get pods -n security -w

5. 설치 후 검증

5.1. 리소스 상태 확인

kubectl get pods,svc,ingress,secret -n security

확인 사항:

• 모든 Pod이 Running 상태 (oauth2-proxy-*)
• Service 생성 확인 (oauth2-proxy)
• Ingress 생성 확인 (oauth2-proxy.cnapcloud.com)
• Secret 생성 확인 (oauth2-proxy-secret, redis-secret 등)

5.2. OAuth2-Proxy 상태 확인

OAuth2-Proxy의 설정과 연결 상태를 확인합니다.

dns

5.2.1. Pod 로그 확인

kubectl logs -f deployment/oauth2-proxy -n security

설명: OAuth2-Proxy의 시작 로그를 확인하여 설정 오류나 연결 문제를 파악합니다.

예상 결과:

[2025/12/18 10:00:00] [oauth2-proxy] starting server on :4180
[2025/12/18 10:00:00] [oauth2-proxy] OIDC provider configured

확인 사항:

• 서버가 정상 시작됨
• OIDC 제공자 설정 성공
• Redis 연결 성공 (세션 스토리지 사용 시)

5.2.2. Ingress 접근 확인

Ingress를 통해 OAuth2-Proxy에 접근 가능한지 확인합니다.

curl -I https://oauth2-proxy.cnapcloud.com

확인 사항:

• HTTP 403 Forbidden (인증 필요로 정상)
• TLS 인증서 적용 확인

5.2.3. OIDC 플로우 테스트

OAuth2-Proxy의 인증 플로우를 브라우저 기반과 API 기반으로 나누어 테스트합니다.

5.2.3.1 브라우저 기반 인증 테스트

OAuth2-Proxy와 연동하기 위해 httpbin ingress 설정에 다음과 같은 annotations가 추가되어 있습니다:

annotations:
  nginx.ingress.kubernetes.io/auth-response-headers: X-Auth-Request-User,X-Auth-Request-Email,X-Auth-Request-Access-Token
  nginx.ingress.kubernetes.io/auth-signin: https://oauth2-proxy.cnapcloud.com/oauth2/start
  nginx.ingress.kubernetes.io/auth-url: http://oauth2-proxy.security.svc.cluster.local/oauth2/auth

테스트 단계:

1. 브라우저에서 https://httpbin.cnapcloud.com에 접근합니다.
2. Keycloak 로그인 페이지로 리다이렉트됩니다.
3. 인증 성공 후 원래 URL로 리턴합니다.

확인 사항:

• Keycloak 로그인 페이지로 리다이렉트
• 인증 성공 후 원래 URL로 리턴
• 세션 쿠키 생성 확인

5.2.3.2 API 기반 인증 테스트

OAuth2-Proxy와 연동하기 위해 httpbin ingress 설정에 다음과 같은 annotations가 추가되어 있습니다:

annotations:
  nginx.ingress.kubernetes.io/buffer-size: "16k"
  nginx.ingress.kubernetes.io/proxy-buffers-number: "4"
  nginx.ingress.kubernetes.io/auth-url: http://oauth2-proxy.security.svc.cluster.local/oauth2/auth

테스트 단계:

1. 토큰 발급:

   export KEYCLOAK_URL=https://keycloak.cnapcloud.com
   export REALM=cnap
   export CLIENT=oauth2-proxy
   export CLIENT_SECRET=h2QxtQFCnOjuRqqfwvkbBPZcsnJyyJHn
   export USER=admin
   export PASSWORD=password
   
   export ACCESS_TOKEN=$(curl -sk -X POST "${KEYCLOAK_URL}/realms/${REALM}/protocol/openid-connect/token" \
     -d grant_type=password \
     -d client_id=${CLIENT} \
     -d client_secret=${CLIENT_SECRET} \
     -d request_token_type=urn:ietf:params:oauth:token_type:access_token \
     -d username=${USER} \
     -d password=${PASSWORD} \
     -d scope='openid profile email' \
   | jq -r .access_token)
   
   echo "ACCESS_TOKEN: ${ACCESS_TOKEN}"
   

2. API 호출:

   curl -sk -H "Authorization: Bearer ${ACCESS_TOKEN}" \
        -H "accept: application/json" \
        -X GET "https://httpbin-api.cnapcloud.com/ip"
   

확인 사항:

• 토큰 발급 성공
• API 호출 시 200 OK 응답
• 인증 헤더가 올바르게 전달됨

5.3. Redis 세션 스토리지 확인 (선택적)

kubectl exec -it deployment/oauth2-proxy -n security -- redis-cli -h redis-service ping

설명: Redis 세션 스토리지가 정상 연결되는지 확인합니다.

예상 결과:

PONG

6. 운영 및 Troubleshooting

6.1. Pod가 Running 상태가 아닌 경우

kubectl get pods -n security
kubectl describe pod <pod명> -n security
kubectl logs <pod명> -n security

주요 원인:

• Secret 미생성 → clientSecret, cookieSecret 확인
• OIDC 설정 오류 → oidc_issuer_url, clientID 확인
• Redis 연결 실패 → Redis 서비스 및 비밀번호 확인

6.2. 인증 실패

• 로그 확인: kubectl logs deployment/oauth2-proxy -n security
• OIDC 설정 검증: issuer URL, client secret 확인
• 쿠키 설정: cookie_domains, cookie_secure 확인

6.3. 세션 문제

• Redis 연결 확인: kubectl get pods -n <redis-namespace>
• 세션 타임아웃: cookie_expire, cookie_refresh 설정 조정

6.4. Secret 관리

민감 정보(clientSecret, cookieSecret, Redis 비밀번호)는 별도 Secret으로 관리하고 values.yaml에서 참조하도록 권장합니다.

kubectl create secret generic oauth2-proxy-secret --from-literal=client-secret='your-secret' --from-literal=cookie-secret='your-cookie-secret' -n security

7. 보안 및 운영 권장사항

7.1. Secret 관리

민감 정보(clientSecret, cookieSecret, Redis 비밀번호)는 별도 Secret으로 관리하고 values.yaml에서 참조하도록 권장합니다.

kubectl create secret generic oauth2-proxy-secret --from-literal=client-secret='your-secret' --from-literal=cookie-secret='your-cookie-secret' -n security

7.2. Network Policy

OAuth2-Proxy Pod 간 네트워크 통신을 제한하는 NetworkPolicy 적용을 권장합니다.

8. 배포 제거

8.1. OAuth2-Proxy 삭제

make delete DEPLOY_ENV=dev

8.2. Namespace 삭제 (선택사항)

kubectl delete namespace security

주의: Namespace를 삭제하면 PVC를 포함한 모든 데이터가 영구 삭제됩니다.

9. 부록: 최종 체크리스트

설치 전:

• Kubernetes 클러스터 준비 (v1.20+)
• kubectl, kustomize, helm 설치
• 네임스페이스(security) 생성
• Keycloak OIDC 설정 완료
• Redis 설치 (세션 스토리지 사용 시)

설치:

• values.yaml 커스터마이징 완료 (OIDC, Redis, Ingress)
• kustomization.yaml 구성 완료
• make namespace 실행
• make preview 실행 및 확인
• make apply 실행

검증:

• 모든 Pod이 Running 상태
• Service/Ingress 생성 확인
• OAuth2-Proxy 로그 확인
• OIDC 인증 플로우 테스트
• Redis 연결 확인 (사용 시)

운영:

• Secret 관리 적용
• Network Policy 구성
• 모니터링 및 알림 설정 /home/ubuntu/devel/github/gitops/oauth2-proxy/install_guide.md