OKE 플랫폼 엔지니어링 랩 5편 — Keycloak + Istio로 OIDC 인증 구성하기

이 포스트는 OKE 플랫폼 엔지니어링 랩 시리즈의 5편입니다.

• 1편 — Terraform + Terragrunt로 OKE 클러스터 프로비저닝하기
• 2편 — ArgoCD App-in-Apps로 인프라 배포하기
• 3편 — Vault + External Secrets로 Kubernetes 시크릿 관리하기
• 4편 — Istio + cert-manager로 TLS 인증서 자동화하기
• 5편 — Keycloak + Istio로 OIDC 인증 구성하기 ← 현재

1. 배경

4편까지 TLS 인증서 자동화를 마쳤습니다. ArgoCD 대시보드에 HTTPS로 접근할 수 있지만, 인증 없이 누구나 접근할 수 있는 상태입니다.

서비스마다 개별 인증을 구성하는 대신, Keycloak을 IdP(Identity Provider)로 배포하고 OIDC(OpenID Connect) 프로토콜로 SSO를 구성합니다. ArgoCD 대시보드에 Keycloak 인증을 연동해 접근을 제어합니다.

OIDC란?

OIDC(OpenID Connect)는 OAuth 2.0 위에 인증 레이어를 추가한 프로토콜입니다. 사용자가 IdP(Keycloak)에서 로그인하면 ID Token(JWT)을 발급받고, 각 애플리케이션은 이 토큰을 검증해 사용자를 인식합니다.

sequenceDiagram
  participant User
  participant App as ArgoCD
  participant KC as Keycloak

  User->>App: 접근 시도
  App->>KC: 로그인 페이지로 리다이렉트
  User->>KC: 사용자 인증 (ID/PW)
  KC->>App: Authorization Code 전달
  App->>KC: Code → ID Token 교환
  KC->>App: ID Token (JWT) 발급
  App->>User: 인증 완료, 대시보드 접근 허용

2. Keycloak 배포

Keycloak Operator

Keycloak Operator는 2편에서 ArgoCD platform 그룹에 이미 등록한 상태입니다. keycloak-operator Application이 Keycloak CRD와 Operator를 설치합니다.

Keycloak CR 배포

Operator가 설치되면 Keycloak CR(Custom Resource)로 인스턴스를 배포합니다. PostgreSQL을 내장 DB로 함께 구성합니다.

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: keycloak
  namespace: keycloak
spec:
  instances: 1
  db:
    vendor: postgres
    host: keycloak-db
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password
  hostname:
    hostname: keycloak.<your-domain>
  http:
    httpEnabled: true    # Istio에서 TLS 종료하므로 HTTP로 실행
  proxy:
    headers: xforwarded

Istio VirtualService

4편에서 구성한 Istio Gateway를 통해 keycloak.<your-domain>으로 노출합니다.

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: keycloak
  namespace: keycloak
spec:
  hosts:
    - keycloak.<your-domain>
  gateways:
    - istio-system/gateway
  http:
    - route:
        - destination:
            host: keycloak-service
            port:
              number: 8080

시크릿 관리

DB 크레덴셜과 admin 비밀번호는 3편에서 구성한 Vault + External Secrets로 관리합니다. Vault에 시크릿을 저장하고 ExternalSecret으로 Kubernetes Secret을 생성합니다.

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: keycloak-db-secret
  namespace: keycloak
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: keycloak-db-secret
  data:
    - secretKey: username
      remoteRef:
        key: secret/keycloak
        property: db-username
    - secretKey: password
      remoteRef:
        key: secret/keycloak
        property: db-password

3. Realm 및 Client 설정

Realm 생성

Keycloak의 Realm은 인증 영역입니다. 기본 master Realm은 관리용이므로, 서비스용 Realm을 별도로 생성합니다.

Keycloak 관리 콘솔(keycloak.<your-domain>)에 접속해 Realm을 생성합니다.

ArgoCD OIDC Client

ArgoCD용 OIDC Client를 생성합니다. ArgoCD가 Keycloak에 인증을 요청할 때 사용하는 설정입니다.

Client를 생성하면 Client Secret이 발급됩니다. 이 값을 Vault에 저장합니다.

vault kv put secret/argocd oidc.keycloak.clientSecret=<client-secret>

사용자 및 그룹

homelab Realm에 사용자와 그룹을 생성합니다. 그룹은 ArgoCD와 Vault에서 권한 매핑에 사용됩니다.

사용자를 생성하고 해당 그룹에 할당합니다. OIDC 토큰에 그룹 정보를 포함하려면 Client Scope에서 groups mapper를 추가해야 합니다.

Client Scopes → groups → Mappers 추가:

4. ArgoCD OIDC 연동

OIDC 설정

ArgoCD의 argocd-cm ConfigMap에 OIDC 설정을 추가합니다. Helm values에 아래 내용을 추가하면 ArgoCD 재배포 시 반영됩니다.

# argocd/values.yaml
configs:
  cm:
    url: https://argocd.<your-domain>
    oidc.config: |
      name: Keycloak
      issuer: https://keycloak.<your-domain>/realms/homelab
      clientID: argocd
      clientSecret: $oidc.keycloak.clientSecret
      requestedScopes:
        - openid
        - profile
        - email
        - groups

clientSecret은 $oidc.keycloak.clientSecret 형식으로 참조합니다. ArgoCD는 argocd-secret Secret에서 이 키를 찾아 값을 사용합니다. External Secrets로 Vault에서 주입합니다.

RBAC 설정

argocd-rbac-cm ConfigMap에서 Keycloak 그룹과 ArgoCD 역할을 매핑합니다.

configs:
  rbac:
    policy.csv: |
      g, /admin, role:admin
      g, /viewer, role:readonly
    scopes: "[groups]"

/admin 그룹 사용자는 role:admin, /viewer 그룹 사용자는 role:readonly 권한을 갖습니다.

로그인 테스트

ArgoCD 대시보드에 접속하면 기존 admin 로그인 외에 LOG IN VIA KEYCLOAK 버튼이 나타납니다. 클릭하면 Keycloak 로그인 페이지로 이동하고, 인증 후 ArgoCD 대시보드로 돌아옵니다.

5. 정리

Keycloak을 IdP로 배포하고 OIDC를 통해 ArgoCD에 SSO를 구성했습니다. 이전 시리즈에서 구축한 인프라가 그대로 활용됩니다.

flowchart LR
  user((User))
  kc[Keycloak]
  argocd[ArgoCD]
  istio[Istio Gateway]

  user --> istio
  istio --> kc
  istio --> argocd
  argocd -->|OIDC 토큰 검증| kc