keycloak - Oauth - OIDC

https://gnobaaaaar.tistory.com/114

[CI/CD] 5주차 - Argo CD 2/3

이전 포스팅에서 부족한 부분을 정리해봅니다
 
 

용어정리

Keycloak

애플리케이션에 초점을 맞춘 오픈 소스 ID 및 접근(권한) 관리 도구입니다.
자세한 내용은 이전 글을 참조하시길 바랍니다.
 
 

OAuth 2.0

OAuth 2.0 은 권한 위임(Authorization)을 위한 프로토콜 입니다.
 
인증 -> 인가(권한) 로 이루어진 과정에서
인증은 유저가 직접 수행하고 권한은 클라이언트가 받습니다.
 
OAuth 2.0은 어떤 앱(클라이언트)가 어떤 권한을 얼마동안 사용할지 결정하는 권한 시스템입니다.
권한 위임 프로토콜 이므로 로그인을 해결하지 않고 사용자 정보를 가지고 있지 않습니다.
 
따라서 OAuth 2 만 사용하면 Argo CD는 로그인 구현 자체가 어렵습니다.
누가 로그인했는지 모른다  
사용자 이름도 모른다  
그룹도 모른다  
권한 부여도 못 한다
 
 

OAuth2.0 의 권한부여 흐름

권한부여 흐름을 통해 좀더 이해해보겠습니다.

1. 애플리케이션은 권한 부여 요청(authorization request)을 준비하고 사용자 브라우저를 Keycloak으로 리디렉션하도록 요청합니다.
2. 사용자 브라우저는 사용자를 권한 부여 엔드포인트(authorization endpoint)라는 엔드포인트 에서 Keycloak으로 리디렉션합니다.
3. 사용자가 아직 Keycloak에 인증되지 않은 경우, Keycloak은 사용자를 인증합니다. 인증이 완료되면 Keycloak은 사용자에게 애플리케이션이 사용자를 대신하여 서비스에 액세스하도록 허용하는 데 동의하도록 요청합니다.
4. 애플리케이션은 Keycloak으로부터 권한 부여 응답의 형태로 권한 부여 코드를 수신합니다.
5. 애플리케이션은 Keycloak의 토큰 엔드포인트에 대한 액세스 토큰 요청을 통해 권한 부여 코드를 액세스 토큰으로 교환합니다.
6. 이제 애플리케이션은 액세스 토큰을 사용하여 보호된 리소스를 호출할 수 있습니다.

 
위 흐름을 보면 인증이 마치 로그인 과정처럼 보이지만 실제로는 권한부여 받는 흐름입니다.
실제로 중간에 보이는 Keycloak 화면은 권한 부여받기 위한 사용자 확인 화면입니다.
Oauth2 관점에서는 사용자가 누구인지, 프로필이 무엇인지는 다루지 않습니다.
따라서 OpenID Connect 라는 인증계층을 추가하게 됩니다.
 
 
 

OIDC (OpenID Connect)

OIDC는 OAuth2 기반의 사용자 인증(Authorization) 프로토콜 입니다.
위에서 보듯이 OAuth2 는 사용자 정보가 없습니다.
OIDC는 OAuth2 의 부족한 기능을 보안하여 로그인을 구현하게 해줍니다.
 
ID Token(사용자 정보가 담긴 JWT) 에서 사용자 프로필이 나옵니다.
OIDC는 OAuth2 표준을 확장하여 OAuth2 위에서 동작합니다.
 
 
 

Argo CD OIDC 제공자 설정

ArgoCD 에 OIDC 제공자를 Keycloak 으로 설정할 때 아래와 같이 설정합니다.
ArgoCD는 oidc.config 설정값을 읽어서 동작합니다.

  oidc.config: |
    name: Keycloak
    issuer: http://192.168.0.7:8080/realms/master
    clientID: argocd
    clientSecret: fWHxpr8bHcSlu54sk3oEAhUYFHSTwhkG
    requestedScopes: ["openid", "profile", "email"]

 

설정값

issuer
http://192.168.0.7:8080/realms/master
 
OIDC에서 가장 중요한 URL 값입니다.
해당 값을 통해 OIDC Provider가 누구인지 알려주게 됩니다.
 
ArgoCD는 issuer URL 하나를 통해 아래와 같은 Keycloak의 모든 인증 엔드포인트를 자동으로 탐색합니다.

인증 페이지	/protocol/openid-connect/auth
토큰 교환	/protocol/openid-connect/token
사용자 정보	/protocol/openid-connect/userinfo
JWKS 공개키	/protocol/openid-connect/certs

 
clientID / clientSecret
Argo CD가 Keycloak 에게 토큰을 받을 때 필요한 값.
토큰 요청시 해당 값이 포함됩니다.
 
requestedScopes: ["openid", "profile", "email"]
openid -> OIDC 로그인 활성화 (ID Token 발급)
해당 설정이 없으면 keycloak은 access_token만 발급하면서 로그인이 실패하게 됩니다.
 
 
 

인증흐름

실제 ArgoCD -> Keycloak 인증과정을 통해 더 이해해보겠습니다.
OIDC 로그인은 아래와 같이 동작합니다.

1. ArgoCD → Keycloak로 redirect (Authorization Request)
2. Keycloak 사용자 인증
3. Keycloak → ArgoCD로 Authorization Code 전달
4. ArgoCD → Keycloak Token 요청
5. Keycloak → ID Token + Access Token 응답
6. ArgoCD: ID Token 검증 → 로그인 → RBAC 매핑

 
간단한 흐름도는 아래와 같습니다.

OIDC 가 추가된 흐름

 
단계별로 해당 내용을 자세하게 확인해보겠습니다.
 
 

Step1 : 사용자 -> ArgoCD 로그인 시도

ArgoCD에 Login VIA Keycloak을 통해 로그인이 시도 됩니다.

 
이때부터 OIDC 로그인이 시작됩니다.
ArgoCD는 브라우저를 다음 URL로 리다이렉트합니다.

# ex
https://keycloak/realms/master/protocol/openid-connect/auth
    ?client_id=argocd
    &redirect_uri=https://argocd.example.com/auth/callback
    &response_type=code
    &scope=openid+profile+email
    &state=XYZ123

 

 

Step2 : Keycloak이 로그인 페이지를 표시 (사용자인증)

사용자는 Keycloak 로그인 화면에 아이디/패스워드를 입력하고 제출합니다.

• 인증(Authentication): Keycloak이 사용자를 검증하는 단계
• OAuth2에는 인증이 없음 → OIDC가 인증 기능을 제공
• Keycloak은 내부적으로 세션 생성

 

Step3 : 인증성공 후 Keycloak -> ArgoCD로 Authorization 코드 전달

용어정리에서 OAuth2 는 권한부여를 위한 프로토콜이라고 하였습니다.
 
keycloak은 사용자의 계정을 내부에서 확인합니다.
로그인이 성공하면 브라우저를 ArgoCD에게 리다이렉트합니다.

302 Found
Location: https://argocd.example.com/auth/callback
    ?code=AbCdEf12345
    &state=XYZ123

 
keycloak 은 토큰을 직접 주지않고 ArgoCD가 토큰을 교환하도록 Authorization code (토큰 요청 가능)를 전달합니다.
 
 

Step4 : Argo CD -> Keycloak 에게 Token 교환 요청

ArgoCD는 code와 함께 POST /token 으로 AccessToken 발급을 요청합니다.

# example
POST /protocol/openid-connect/token
grant_type=authorization_code
client_id=argocd
client_secret=xxx
redirect_uri=https://argocd.example.com/auth/callback
code=AbCdEf12345

 
Authorization Server 는 ArgoCD 에게 AccessToken(RefreshToken 포함) 반환 해줍니다.
소셜로그인 OpenID Connect (OIDC)에서는 추가로 ID Token이 발급됩니다

{
  "access_token": "...",
  "refresh_token": "...",
  "id_token": "...."
}

 
 

Step5 : Argo CD는 ID Token은 디코드 -> 로그인 처리, RBAC

전달받은 ID Token으로 Argo CD는 사용자가 누구인지 등을 확인합니다.
또한 RBAC 정책을 ID Token 정보를 통해 확인 후 적용합니다.
 

Step6 : 사용자 로그인

ArgoCD는 사용자 세션을 만들고 UI로 리다이렉트합니다.

https://argocd.example.com/applications

 
Token은 ArgoCD 내부에 저장하고 (주로 Redis)
사용자 정보를 꺼내서 세션을 생성하고 쿠키(Session JWT) 형태로 저장합니다.
서버는 세션ID를 브라우저에 쿠키 형태로 주로 저장합니다
 
ArgoCD는 세션 저장소를 따로 두지않고 세션 자체를 JWT로 만들어 쿠키에 넣습니다
디코딩하면 username, issuer, session_state 등의 정보확인이 가능합니다

argocd.token -> Cookie

 
 
 

OAuth2 Proxy (인증프록시)

 
ArgoCD만이 아닌 Grafana, Prometheus, Jenkins, 또는 자체 애플리케이션에 동일한 인증정책을 적용하고 싶다면
OAuth2 Proxy (인증프록시) 도입도 한가지 예시가 될 수있습니다.
 
또한 재로그인 문제, redirect의 복잡성, 설정 꼬임 등을 방지할 수 있고
토큰/쿠키 관리를 대신 하므로 보안적으로도 더 안정적입니다.
 
실제로 현업에서는 Nginx Ingress + OAuth2 Proxy + Keycloak + ArgoCD 구조가 많이 사용됩니다.
 

기본구조

어플리케이션 클라이언트가 직접 Keycloak을 사용하지 않는 구조에서는
OAuth2 Proxy가 인증의 모든 흐름을 처리하고 ArgoCD는 인증된 사용자만 받습니다.

Browser → OAuth2 Proxy → Keycloak
                           ↓
Browser ← OAuth2 Proxy ← ID Token
 ↓
OAuth2 Proxy → ArgoCD (Authorization Header 삽입)

• Keycloak 로그인을 proxy가 처리하고
• 인증이 끝나면 proxy가 ArgoCD로 요청을 전달
• ArgoCD는 Keycloak을 전혀 알 필요가 없습니다.

 

동작단계

1. 브라우저가 ArgoCD URL 접근시 Oauth2 Proxy가 가로챕니다.
만약 Ingress가 OAuth2 Proxy에 연결되어 있다면 세션 없다면 로그인 페이지로 리다이렉트 합니다.
 
2. OAuth2 Proxy -> Keycloak으로 대신 redirect 
keycloak에 로그인 요청을 대신 보냅니다.

/auth?client_id=oauth2-proxy&redirect_uri=<proxy-callback>

 
3. Keycloak -> Oauth2 Proxy로 인증코드 전달
4. OAuth2 Proxy code -> token 교환
 
5. OAuth2 Proxy가 세션 쿠키를 생성하여 브라우저에 저장

_oauth2_proxy=<JWT>

ArgoCD의 쿠키(argocd.token)가 아닙니다.
 
6. OAuth2 Proxy가 요청을 ArgoCD로 프록시 처리하면서 인증헤더 삽입

Authorization: Bearer <id-token>
X-Auth-User: tom
X-Auth-Email: tom@example.com
X-Auth-Groups: dev,ops

 
ArgoCD가 인증정보를 알 수 있도록 인증정보를 삽입합니다.
X-Auth-User header만 보고 로그인 처리가 가능합니다. (헤더기반 인증모드-ArgoCD)
 
 
 

인증과 인가

용어	뜻	대상	수행
인증 Authentication	누구인지	ID / PW, 토큰	Keycloak, OAuth2 Proxy
인가 Authorization	무엇을 할 수 있는지	권한 / 역할	ArgoCD (RBAC)