Keycloak 연동

Keycloak 연동

Keycloak과 Argo CD 통합은 Client authentication 방식과 PKCE 방식 두 가지로 구성할 수 있습니다. argo-cd 명령줄로 인증해야 한다면 PKCE 방식을 선택해야 합니다.

출처: 문서

본문

Keycloak

Keycloak과 Argo CD 통합은 Client authentication과 PKCE 두 가지 방식으로 구성할 수 있습니다.

argo-cd 명령줄로 인증해야 한다면 PKCE 방식을 선택해야 합니다.

  • Client authentication을 사용한 Keycloak과 Argo CD
  • PKCE를 사용한 Keycloak과 Argo CD

Client authentication을 사용한 Keycloak과 Argo CD

이 지침은 Argo CD 애플리케이션이 Keycloak으로 인증하도록 하는 전체 과정을 안내합니다.

Keycloak 내에서 클라이언트를 만들고 Argo CD가 Keycloak을 인증에 사용하도록 구성하는 것으로 시작하세요. Keycloak에 설정된 그룹을 사용해 Argo에서 권한을 결정합니다.

Keycloak에서 새 클라이언트 생성

먼저 새 클라이언트를 설정하세요.

keycloak 서버에 로그인하여 사용할 realm을 선택한 다음(master가 기본값) Clients로 이동해 상단의 Create client 버튼을 클릭하세요.

Client authentication을 활성화하세요.

Root URL, Web origins, Admin URL을 호스트 이름(https://{hostname})으로 설정하여 클라이언트를 구성하세요.

또한 Home URL을 /applications 경로로, Valid Post logout redirect URIs를 "https://{hostname}/applications"로 설정할 수 있습니다.

Valid Redirect URIs는 https://{hostname}/auth/callback으로 설정해야 합니다(테스트/개발 목적으로는 덜 안전한 https://{hostname}/*도 설정할 수 있지만, 프로덕션에서는 권장하지 않습니다).

Save를 클릭하세요.

Credentials라는 탭이 있습니다. Argo CD 구성에서 사용할 Client Secret을 복사할 수 있습니다.

Argo CD OIDC 구성

먼저 앞서 생성한 클라이언트 시크릿을 argocd 시크릿 argocd-secret에 저장하세요.

앞서 복사한 값으로 패치할 수 있습니다:

kubectl -n argo-cd patch secret argocd-secret --patch='{"stringData": { "oidc.keycloak.clientSecret": "<REPLACE_WITH_CLIENT_SECRET>" }}'

이제 config map을 구성하고 oidc 구성을 추가해 keycloak 인증을 활성화할 수 있습니다. $ kubectl edit configmap argocd-cm을 사용할 수 있습니다.

ConfigMap은 다음과 같아야 합니다:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
data:
  url: https://argocd.example.com
  oidc.config: |
    name: Keycloak
    issuer: https://keycloak.example.com/realms/master
    clientID: argocd
    clientSecret: $oidc.keycloak.clientSecret
    refreshTokenThreshold: 2m
    requestedScopes: ["openid", "profile", "email", "groups", "offline_access"]

반드시 확인하세요:

  • issuer가 올바른 realm으로 끝나는지(이 예시에서는 master)
  • 버전 17보다 오래된 Keycloak 릴리스에서는 issuer URL이 /auth를 포함해야 합니다(이 예시에서는 /auth/realms/master)
  • clientID가 Keycloak에서 구성한 Client ID로 설정되었는지
  • clientSecret이 argocd-secret 시크릿에서 만든 올바른 키를 가리키는지
  • Default scopes에 추가하지 않았다면 requestedScopes가 groups 클레임을 포함하는지
  • refreshTokenThreshold가 클라이언트 토큰 수명보다 작은지. 이 설정이 토큰 수명보다 작지 않으면 매 요청마다 새 토큰을 얻습니다. Keycloak은 클라이언트 토큰 수명을 기본적으로 5분으로 설정합니다.

PKCE를 사용한 Keycloak과 Argo CD

이 지침은 Argo CD 애플리케이션이 Keycloak으로 인증하도록 하는 전체 과정을 안내합니다.

Keycloak 내에서 클라이언트를 만들고 Argo CD가 Keycloak을 인증에 사용하도록 구성합니다. Keycloak에 설정된 그룹을 사용해 Argo에서 권한을 결정합니다.

또한 argo-cd 명령줄로 인증할 수 있게 됩니다.

Keycloak에서 새 클라이언트 생성

먼저 새 클라이언트를 설정하세요.

keycloak 서버에 로그인하여 사용할 realm을 선택한 다음(master가 기본값) Clients로 이동해 상단의 Create client 버튼을 클릭하세요.

기본값을 유지하세요.

Root URL, Web origins, Admin URL을 호스트 이름(https://{hostname})으로 설정하여 클라이언트를 구성하세요.

또한 Home URL을 /applications 경로로, Valid Post logout redirect URIs를 "https://{hostname}/applications"로 설정할 수 있습니다.

Valid Redirect URIs는 다음과 같이 설정해야 합니다:

Save를 클릭하세요.

이제 Settings라는 첫 번째 탭으로 가서 Capability config에서 PKCE Method라는 파라미터를 찾아 S256으로 설정하세요.

오래된 Keycloak 버전: Advanced라는 탭으로 가서 Proof Key for Code Exchange Code Challenge Method라는 파라미터를 찾아 S256으로 설정하세요.

Save를 클릭하세요.

Argo CD OIDC 구성

이제 config map을 구성하고 oidc 구성을 추가해 keycloak 인증을 활성화할 수 있습니다. $ kubectl edit configmap argocd-cm을 사용할 수 있습니다.

ConfigMap은 다음과 같아야 합니다:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
data:
  url: https://argocd.example.com
  oidc.config: |
    name: Keycloak
    issuer: https://keycloak.example.com/realms/master
    clientID: argocd
    enablePKCEAuthentication: true
    refreshTokenThreshold: 2m
    requestedScopes: ["openid", "profile", "email", "groups", "offline_access"]

반드시 확인하세요:

  • issuer가 올바른 realm으로 끝나는지(이 예시에서는 master)
  • 버전 17보다 오래된 Keycloak 릴리스에서는 issuer URL이 /auth를 포함해야 합니다(이 예시에서는 /auth/realms/master)
  • clientID가 Keycloak에서 구성한 Client ID로 설정되었는지
  • PKCE로 올바른 Argo CD 동작을 활성화하려면 enablePKCEAuthentication가 true로 설정되어야 하는지
  • Default scopes에 추가하지 않았다면 requestedScopes가 groups 클레임을 포함하는지
  • refreshTokenThreshold가 클라이언트 토큰 수명보다 작은지. 이 설정이 토큰 수명보다 작지 않으면 매 요청마다 새 토큰을 얻습니다. Keycloak은 클라이언트 토큰 수명을 기본적으로 5분으로 설정합니다.

groups 클레임 구성

Argo CD가 사용자가 속한 그룹을 제공하려면 인증 토큰에 포함될 groups 클레임을 구성해야 합니다.

이를 위해 groups라는 새 Client Scope를 만드는 것으로 시작합니다.

클라이언트 스코프를 만든 후, 클라이언트가 groups 스코프를 요청할 때 토큰에 groups 클레임을 추가하는 Token Mapper를 추가할 수 있습니다.

"Mappers" 탭에서 "Configure a new mapper"를 클릭하고 Group Membership을 선택하세요.

Name과 Token Claim Name을 모두 groups로 설정해야 합니다. 또한 "Full group path"를 비활성화하세요.

이제 클라이언트가 groups 스코프를 제공하도록 구성할 수 있습니다.

앞서 만든 클라이언트로 돌아가 "Client Scopes" 탭으로 이동하세요.

"Add client scope"를 클릭하고 groups 스코프를 선택해 Default 또는 Optional Client Scope에 추가하세요.

Optional 범주에 넣으면 Argo CD가 OIDC 구성에서 해당 스코프를 요청하는지 확인해야 합니다. 우리는 항상 그룹 정보를 원하므로 Default 범주를 사용하는 것을 권장합니다.

ArgoCDAdmins라는 그룹을 만들고 현재 사용자가 그 그룹에 들어가게 하세요.

Argo CD 정책 구성

이제 그룹을 제공하는 인증이 있으므로 이 그룹들에 정책을 적용하려고 합니다. $ kubectl edit configmap argocd-rbac-cm으로 argocd-rbac-cm ConfigMap을 수정할 수 있습니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
data:
  policy.csv: |
    g, ArgoCDAdmins, role:admin

이 예시에서는 ArgoCDAdmins 그룹의 모든 사용자에게 role:admin 역할을 부여합니다.

로그인

이제 새 Keycloak OIDC 인증으로 로그인할 수 있습니다:

PKCE 방법을 사용했다면 명령줄로도 인증할 수 있습니다:

argocd login argocd.example.com --sso --grpc-web

argocd cli는 localhost:8085에서 수신 대기를 시작하고 웹 브라우저를 열어 Keycloak으로 인증할 수 있게 합니다.

완료되면 확인할 수 있습니다.

문제 해결

Argo CD 인증이 401을 반환하거나 로그인 시도가 루프로 이어지면 argocd-server pod를 재시작하세요.

kubectl rollout restart deployment argocd-server -n argocd

Client authentication에서 PKCE로 마이그레이션하면 invalid_request: Missing parameter: code_challenge_method 오류가 발생할 수 있습니다.

리다이렉트 문제일 수 있으니 시크릿 브라우징 모드를 시도하거나 브라우저 쿠키를 정리하세요.

더 알아보기 (Learn more)