Zitadel 연동

Zitadel 연동

이 문서는 Zitadel로 ArgoCD 애플리케이션을 인증하고 인가받는 전체 과정을 안내합니다. Zitadel 내에서 애플리케이션을 만들고, Zitadel의 역할을 사용해 ArgoCD 권한을 결정하도록 ArgoCD를 구성합니다.

출처: 문서

본문

Zitadel

Zitadel 문서도 함께 참조하세요.

Zitadel과 ArgoCD 통합

이 지침은 ArgoCD 애플리케이션이 Zitadel로 인증하고 인가받도록 하는 전체 과정을 안내합니다. Zitadel 내에서 애플리케이션을 만들고, Zitadel의 역할을 사용해 ArgoCD 권한을 결정하도록 ArgoCD를 구성합니다.

ArgoCD를 Zitadel과 통합하려면 다음 단계가 필요합니다:

  1. Zitadel에 새 프로젝트와 새 애플리케이션 생성
  2. Zitadel에서 애플리케이션 구성
  3. Zitadel에서 역할 설정
  4. Zitadel에서 액션(action) 설정
  5. ArgoCD configmaps 구성
  6. 설정 테스트

이 예시에서 사용할 값은 다음과 같습니다:

  • Zitadel FQDN: auth.example.com
  • Zitadel 프로젝트: argocd-project
  • Zitadel 애플리케이션: argocd-application
  • Zitadel 액션: groupsClaim
  • ArgoCD FQDN: argocd.example.com
  • ArgoCD 관리자 역할: argocd_administrators
  • ArgoCD 사용자 역할: argocd_users

구성에 따라 다른 값을 선택할 수 있습니다. 이 값들은 가이드를 일관되게 유지하기 위해 사용됩니다.

Zitadel에서 프로젝트와 애플리케이션 설정

먼저 Zitadel 내에서 새 프로젝트를 만듭니다. Projects로 이동해 Create New Project를 선택하세요. 이제 다음 화면이 보일 것입니다.

다음 옵션을 확인하세요:

  • Assert Roles on Authentication
  • Check authorization on Authentication

역할(Roles)

Roles로 이동해 New를 클릭하세요. 다음 두 역할을 만드세요. Key와 Group 두 필드 모두 아래 지정된 값을 사용하세요.

  • argocd_administrators
  • argocd_users

이제 역할이 다음과 같이 보일 것입니다.

인가(Authorizations)

다음으로 Authorizations로 이동해 사용자에게 argocd_administrators 역할을 할당하세요. New를 클릭하고 사용자 이름을 입력한 다음 Continue를 클릭하세요. argocd_administrators 역할을 선택하고 Save를 클릭하세요.

이제 인가가 다음과 같이 보일 것입니다.

애플리케이션 생성

General로 이동해 새 애플리케이션을 만드세요. 애플리케이션 이름을 argocd-application으로 지정하세요.

애플리케이션 유형으로 WEB을 선택하고 계속하세요.

CODE를 선택하고 계속하세요.

다음으로 리다이렉트 및 포스트 로그아웃 URI를 설정하겠습니다. 다음 값을 설정하세요:

  • Redirect URI: https://argocd.example.com/auth/callback
  • Post Logout URI: https://argocd.example.com

Post Logout URI는 선택 사항입니다. 예시 설정에서 사용자는 로그아웃 후 ArgoCD 로그인 페이지로 돌아갑니다.

다음 화면에서 구성을 확인하고 Create를 클릭해 애플리케이션을 만드세요.

Create를 클릭하면 애플리케이션의 ClientId와 ClientSecret이 표시됩니다. 이 창을 닫으면 검색할 수 없으므로 ClientSecret을 반드시 복사하세요. 예시에서는 다음 값이 사용됩니다:

  • ClientId: 227060711795262483@argocd-project
  • ClientSecret: UGvTjXVFAQ8EkMv2x4GbPcrEwrJGWZ0sR2KbwHRNfYxeLsDurCiVEpa5bkgW0pl0

ClientSecret을 안전한 곳에 저장했으면 Close를 클릭해 애플리케이션 생성을 완료하세요.

Token Settings로 이동해 다음 옵션을 활성화하세요:

  • User roles inside ID Token
  • User Info inside ID Token

Zitadel에서 액션 설정

Zitadel이 발급한 토큰에 사용자의 역할을 포함시키려면 Zitadel Action을 설정해야 합니다. ArgoCD의 인가는 인증 토큰에 포함된 역할에 따라 결정됩니다. Actions로 이동해 New를 클릭하고 액션 이름으로 groupsClaim을 선택하세요.

다음 코드를 액션에 붙여넣으세요:

/**
 * sets the roles an additional claim in the token with roles as value an project as key
 *
 * The role claims of the token look like the following:
 *
 * // added by the code below
 * "groups": ["{roleName}", "{roleName}", ...],
 *
 * Flow: Complement token, Triggers: Pre Userinfo creation, Pre access token creation
 *
 * @param ctx
 * @param api
 */
function groupsClaim(ctx, api) {
  if (ctx.v1.user.grants === undefined || ctx.v1.user.grants.count == 0) {
    return;
  }

  let grants = [];
  ctx.v1.user.grants.grants.forEach((claim) => {
    claim.roles.forEach((role) => {
      grants.push(role);
    });
  });

  api.v1.claims.setClaim("groups", grants);
}

Allowed To Fail을 체크하고 Add를 클릭해 액션을 추가하세요.

참고: Allowed To Fail이 체크되어 있지 않고 사용자에게 할당된 역할이 없으면, 액션이 실패할 때 로그인 흐름이 실패하므로 사용자가 Zitadel에 더 이상 로그인하지 못할 수 있습니다.

다음으로 액션을 Complement Token 흐름에 추가하세요. 드롭다운에서 Complement Token 흐름을 선택하고 Add trigger를 클릭하세요. 액션을 Pre Userinfo creation과 Pre access token creation 두 트리거 모두에 추가하세요.

이제 Actions 페이지는 다음 스크린샷처럼 보일 것입니다.

ArgoCD configmaps 구성

다음으로 두 개의 ArgoCD configmaps를 구성합니다:

  • argocd-cm.yaml
  • argocd-rbac-cm.yaml

url, issuer, clientID, clientSecret, logoutURL 같은 관련 값을 설정에 맞는 것으로 교체하면서 configmaps를 다음과 같이 구성하세요.

argocd-cm.yaml

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
  labels:
    app.kubernetes.io/part-of: argocd
data:
  admin.enabled: "false"
  url: https://argocd.example.com
  oidc.config: |
    name: Zitadel
    issuer: https://auth.example.com
    clientID: 227060711795262483@argocd-project
    clientSecret: UGvTjXVFAQ8EkMv2x4GbPcrEwrJGWZ0sR2KbwHRNfYxeLsDurCiVEpa5bkgW0pl0
    requestedScopes:
      - openid
      - profile
      - email
      - groups
    logoutURL: https://auth.example.com/oidc/v1/end_session

argocd-rbac-cm.yaml

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
  labels:
    app.kubernetes.io/part-of: argocd
data:
  scopes: '[groups]'
  policy.csv: |
    g, argocd_administrators, role:admin
    g, argocd_users, role:readonly
  policy.default: ''

policy.csv 아래 지정된 역할은 Zitadel에서 구성된 역할과 일치해야 합니다. Zitadel 역할 argocd_administrators에는 ArgoCD 역할 admin이 할당되어 ArgoCD에 대한 관리자 접근을 부여합니다. Zitadel 역할 argocd_users에는 ArgoCD 역할 readonly가 할당되어 ArgoCD에 대한 읽기 전용 접근을 부여합니다.

ArgoCD configmaps를 배포하세요. 이제 ArgoCD와 Zitadel이 사용자가 Zitadel로 ArgoCD에 로그인할 수 있도록 올바르게 설정되었을 것입니다.

설정 테스트

ArgoCD 인스턴스로 이동하세요. 이제 평소의 사용자 이름/비밀번호 로그인 위에 LOG IN WITH ZITADEL 버튼이 보일 것입니다.

Zitadel 사용자로 로그인한 후 User Info로 이동하세요. 모든 것이 올바르게 설정되었다면 아래와 같이 argocd_administrators 그룹이 보일 것입니다.

더 알아보기 (Learn more)