Microsoft

Microsoft (Entra ID) 연동

이 문서는 Microsoft Entra ID(이전 Azure AD)를 Argo CD의 ID 프로바이더로 연동하는 방법을 안내합니다. OIDC를 통한 앱 등록 인증, Dex를 통한 SAML 엔터프라이즈 앱 인증, Dex를 통한 앱 등록 인증 세 가지 방식이 있습니다.

출처: 문서

본문

Microsoft

참고: Entra ID는 이전에 Azure AD로 알려져 있었습니다.

OIDC를 사용한 Entra ID App Registration 인증
Dex를 사용한 Entra ID SAML Enterprise App 인증
Dex를 사용한 Entra ID App Registration 인증

OIDC를 사용한 Entra ID App Registration 인증

새 Entra ID App registration 구성

새 Entra ID App registration 추가

Microsoft Entra ID > App registrations 메뉴에서 + New registration을 선택하세요.
애플리케이션의 Name을 입력하세요(예: Argo CD).
애플리케이션을 사용할 수 있는 대상을 지정하세요(예: Accounts in this organizational directory only).
Redirect URI(선택 사항)를 다음과 같이 입력하고(my-argo-cd-url을 Argo URL로 교체) Add를 선택하세요.
- Platform: Web
- Redirect URI: https://<my-argo-cd-url>/auth/callback
등록이 끝나면 Azure 포털에 앱 등록의 Overview 창이 표시됩니다. Application (client) ID가 보일 것입니다.

ArgoCD CLI용 추가 플랫폼 설정 구성

Azure 포털의 App registrations에서 애플리케이션을 선택하세요.
Manage 아래에서 Authentication을 선택하세요.
Platform configurations 아래에서 Add a platform을 선택하세요.
Configure platforms에서 "Mobile and desktop applications" 타일을 선택하세요. 아래 값을 사용하세요. 변경하면 안 됩니다.
- Redirect URI: http://localhost:8085/auth/callback

새 Entra ID App registration에 자격 증명 추가

Workload Identity Federation 사용 (권장)

Pod 라벨 지정: argocd-server 파드에 azure.workload.identity/use: "true" 라벨을 추가하세요.
서비스 계정에 어노테이션 추가: 이전 단계에서 만든 애플리케이션의 세부 정보를 사용해 argocd-server 서비스 계정에 azure.workload.identity/client-id: "$CLIENT_ID" 어노테이션을 추가하세요.
Certificates & secrets 메뉴에서 Federated credentials로 이동한 다음 + Add credential을 선택하세요.
Federated credential scenario로 Kubernetes Accessing Azure resources를 선택하세요.
Cluster Issuer URL을 입력하세요. OIDC issuer URL 검색 문서를 참조하세요.
namespace에 argocd가 배포된 네임스페이스를 입력하세요.
service account name에 argocd-server를 입력하세요.
고유한 이름을 입력하세요.
Add를 클릭하세요.

Client Secret 사용

Certificates & secrets 메뉴에서 + New client secret을 선택하세요.
시크릿의 Name을 입력하세요(예: ArgoCD-SSO). 생성된 값을 복사해 저장하세요. 이것이 client_secret의 값입니다.

Entra ID 애플리케이션용 권한 설정

API permissions 메뉴에서 + Add a permission을 선택하세요.
User.Read 권한(Microsoft Graph 아래)을 찾아 생성된 애플리케이션에 부여하세요.
Token Configuration 메뉴에서 + Add groups claim을 선택하세요.

Entra ID 그룹을 Entra ID App registration에 연결

Microsoft Entra ID > Enterprise applications 메뉴에서 만든 앱(예: Argo CD)을 검색하세요. 새 Entra ID App registration을 추가하면 같은 이름의 Enterprise application이 생성됩니다.
앱의 Users and groups 메뉴에서 서비스에 접근해야 하는 사용자나 그룹을 추가하세요.

Argo가 새 Entra ID App registration을 사용하도록 구성

argocd-cm을 편집하고 data.oidc.config와 data.url 섹션을 구성하세요:

    ConfigMap -> argocd-cm

    data:
       url: https://argocd.example.com/ # Replace with the external base URL of your Argo CD
       oidc.config: |
             name: Azure
             issuer: https://login.microsoftonline.com/{directory_tenant_id}/v2.0
             clientID: {azure_ad_application_client_id}
             clientSecret: $oidc.azure.clientSecret // if using client secret for authentication
             azure:
               useWorkloadIdentity: true // if using azure workload identity for authentication
             requestedIDTokenClaims:
                groups:
                   essential: true
                   value: "ApplicationGroup"
             requestedScopes:
                - openid
                - profile
                - email

azure workload identity를 사용한다면 이 단계를 건너뛰세요. argocd-secret을 편집하고 data.oidc.azure.clientSecret 섹션을 구성하세요:

    Secret -> argocd-secret

    data:
       oidc.azure.clientSecret: {client_secret | base64_encoded}

argocd-rbac-cm을 편집해 권한을 구성하세요. 역할 할당에 Azure의 그룹 ID를 사용하세요. RBAC Configurations 참조.

    ConfigMap -> argocd-rbac-cm

    policy.default: role:readonly
    policy.csv: |
       p, role:org-admin, applications, *, */*, allow
       p, role:org-admin, clusters, get, *, allow
       p, role:org-admin, repositories, get, *, allow
       p, role:org-admin, repositories, create, *, allow
       p, role:org-admin, repositories, update, *, allow
       p, role:org-admin, repositories, delete, *, allow
       g, "84ce98d1-e359-4f3b-85af-985b458de3c6", role:org-admin

jwt 토큰의 역할을 argo로 매핑합니다. jwt 토큰의 역할을 기본 역할(readonly, admin)과 일치하도록 매핑하려면 rbac-configmap에서 scope 변수를 변경해야 합니다.

    policy.default: role:readonly
    policy.csv: |
       p, role:org-admin, applications, *, */*, allow
       p, role:org-admin, clusters, get, *, allow
       p, role:org-admin, repositories, get, *, allow
       p, role:org-admin, repositories, create, *, allow
       p, role:org-admin, repositories, update, *, allow
       p, role:org-admin, repositories, delete, *, allow
       g, "84ce98d1-e359-4f3b-85af-985b458de3c6", role:org-admin
    scopes: '[groups, email]'

사용 가능한 모든 변수는 operator-manual/argocd-rbac-cm.yaml을 참조하세요.

Azure AD 그룹 오버플로 해결 (200개 이상 그룹)

개요

Azure AD / Entra ID 액세스 토큰은 최대 200개 그룹을 포함할 수 있습니다. 사용자가 200개가 넘는 그룹에 속하면 Azure AD는 groups 클레임을 포함하는 대신 ID 토큰에 오버플로 표시자(_claim_names와 _claim_sources)를 설정합니다. 이로 인해 사용자가 Argo CD에서 그룹 기반 RBAC 권한을 갖지 못하게 됩니다.

Argo CD는 이 오버플로를 자동으로 감지하고 Microsoft Graph API를 호출해 완전한 그룹 멤버십 목록을 가져와 해결할 수 있습니다.

전제 조건

Azure AD 앱 등록에 User.Read 위임 권한이 있어야 합니다. 위의 Setup permissions 단계를 따르면 기본적으로 부여됩니다. Azure AD는 requestedScopes에서 명시적으로 요청하지 않아도 승인된 권한을 액세스 토큰의 scp 클레임에 자동으로 포함합니다.

구성

argocd-cm ConfigMap의 oidc.config 아래에 다음을 추가하세요:

oidc.config: |
  name: Azure
  issuer: https://login.microsoftonline.com/{tenant_id}/v2.0
  clientID: {client_id}
  clientSecret: $oidc.azure.clientSecret
  requestedScopes:
    - openid
    - profile
    - email
  azure:
    enableUserGroupOverageClaim: true

구성 옵션

설정	기본값	설명
enableUserGroupOverageClaim	false	Graph API를 통한 자동 오버플로 해결 활성화
graphApiEndpoint	https://graph.microsoft.com/v1.0	Graph API 기본 URL(소버린 클라우드용 재정의)
userGroupOverageClaimCacheExpiration	토큰 만료	해결된 그룹의 캐시 기간(예: 10m)

소버린 클라우드(Sovereign Clouds)

Azure Government, Azure China 또는 다른 소버린 클라우드의 경우 Graph API 엔드포인트를 재정의하세요:

azure:
  enableUserGroupOverageClaim: true
  graphApiEndpoint: https://graph.microsoft.us/v1.0  # Azure Government

동작 방식

감지: Argo CD는 ID 토큰에서 오버플로 표시자(_claim_names와 _claim_sources)를 확인합니다.
스코프 확인: 액세스 토큰에 User.Read 스코프가 포함되어 있는지 검증합니다.
Graph API 호출: POST /me/getMemberGroups를 호출해 모든 그룹 ID(최대 2048개)를 가져옵니다. 보안 활성 그룹만 반환되며(배포 목록은 제외), 이는 RBAC 평가에 적합합니다.
캐싱: 해결된 그룹을 토큰 기간 또는 구성된 만료 기간 동안 암호화하여 캐시합니다.
RBAC 통합: 해결된 그룹 ID를 사용자의 클레임에 추가해 RBAC 평가에 사용합니다.

문제 해결

증상	원인	해결책
200개 이상 멤버십인데도 사용자 그룹이 0개	기능 미활성화	enableUserGroupOverageClaim: true 설정
로그에 "access token missing User.Read scope"	권한 누락	Azure AD 앱 등록에 User.Read 위임 권한이 부여되었는지 확인
로그에 "insufficient permissions for Graph API"	앱 권한 거부	Azure AD의 앱 권한 확인
로그에 "no access token cached"	토큰 만료	사용자가 재인증해야 함

경고: 이 기능은 인증 시점에 Microsoft Graph API에 접근할 수 있어야 합니다. Graph API를 사용할 수 없으면(네트워크 문제, 장애 등) 200개 이상 그룹 멤버십을 가진 사용자는 서비스가 복구될 때까지 인증할 수 없습니다. 200개 미만 그룹의 사용자는 그룹이 ID 토큰에 직접 포함되므로 영향을 받지 않습니다. Graph API 실패(스코프 누락, 권한 거부, 네트워크 오류)는 인증이 401 Unauthorized 응답으로 실패하게 합니다. 이는 UserInfo 엔드포인트의 동작 방식과 일치합니다. 200개 이상 그룹을 가진 사용자에게 그룹 기반 RBAC가 필요할 때만 이 기능을 활성화하고, 인증 문제를 피하려면 위 전제 조건이 충족되었는지 확인하세요.

Dex를 사용한 Entra ID SAML Enterprise App 인증

새 Entra ID Enterprise App 구성

Microsoft Entra ID > Enterprise applications 메뉴에서 + New application을 선택하세요.
Non-gallery application을 선택하세요.
애플리케이션의 Name을 입력한 다음(예: Argo CD) Add를 선택하세요.
애플리케이션이 생성되면 Enterprise applications 메뉴에서 열어주세요.
앱의 Users and groups 메뉴에서 서비스에 접근해야 하는 사용자나 그룹을 추가하세요.
Single sign-on 메뉴에서 Basic SAML Configuration 섹션을 다음과 같이 편집하세요(my-argo-cd-url을 Argo URL로 교체):
- Identifier (Entity ID): https://<my-argo-cd-url>/api/dex/callback
- Reply URL (Assertion Consumer Service URL): https://<my-argo-cd-url>/api/dex/callback
- Sign on URL: https://<my-argo-cd-url>/auth/login
- Relay State: <empty>
- Logout Url: <empty>
Single sign-on 메뉴에서 User Attributes & Claims 섹션을 편집해 다음 클레임을 만드세요:
- + Add new claim | Name: email | Source: Attribute | Source attribute: user.mail
- + Add group claim | Which groups: All groups | Source attribute: Group ID | Customize: True | Name: Group | Namespace: <empty> | Emit groups as role claims: False
참고: Unique User Identifier 필수 클레임은 기본값 user.userprincipalname으로 둘 수 있습니다.
Single sign-on 메뉴에서 SAML 서명 인증서(Base64)를 다운로드하세요.
- 다운로드한 인증서 파일 내용을 base64로 인코딩하세요. 예:
$ cat ArgoCD.cer | base64
인코딩된 출력 사본을 다음 섹션에서 사용하기 위해 보관하세요.
Single sign-on 메뉴에서 Login URL 파라미터를 복사해 다음 섹션에서 사용하세요.

Argo가 새 Entra ID Enterprise App을 사용하도록 구성

argocd-cm을 편집하고 data 섹션에 다음 dex.config를 추가하세요. caData, my-argo-cd-url, my-login-url을 Entra ID App의 값으로 교체하세요:

    data:
      url: https://my-argo-cd-url
      dex.config: |
        logger:
          level: debug
          format: json
        connectors:
        - type: saml
          id: saml
          name: saml
          config:
            entityIssuer: https://my-argo-cd-url/api/dex/callback
            ssoURL: https://my-login-url (e.g. https://login.microsoftonline.com/xxxxx/a/saml2)
            caData: |
               MY-BASE64-ENCODED-CERTIFICATE-DATA
            redirectURI: https://my-argo-cd-url/api/dex/callback
            usernameAttr: email
            emailAttr: email
            groupsAttr: Group

argocd-rbac-cm을 편집해 권한을 구성하세요(아래 예시와 유사).
역할 할당에 Entra ID Group IDs를 사용하세요.
더 자세한 시나리오는 RBAC Configurations를 참조하세요.

# example policy
policy.default: role:readonly
policy.csv: |
   p, role:org-admin, applications, *, */*, allow
   p, role:org-admin, clusters, get, *, allow
   p, role:org-admin, repositories, get, *, allow
   p, role:org-admin, repositories, create, *, allow
   p, role:org-admin, repositories, update, *, allow
   p, role:org-admin, repositories, delete, *, allow
   g, "84ce98d1-e359-4f3b-85af-985b458de3c6", role:org-admin # (azure group assigned to role)

Dex를 사용한 Entra ID App Registration 인증

위와 같이 새 AD App Registration을 구성하세요. 그런 다음 argocd-cm에 dex.config를 추가하세요:

ConfigMap -> argocd-cm

data:
    dex.config: |
      connectors:
      - type: microsoft
        id: microsoft
        name: Your Company GmbH
        config:
          clientID: $MICROSOFT_APPLICATION_ID
          clientSecret: $MICROSOFT_CLIENT_SECRET
          redirectURI: http://localhost:8080/api/dex/callback
          tenant: ffffffff-ffff-ffff-ffff-ffffffffffff
          groups:
            - DevOps

검증(Validation)

SSO로 ArgoCD UI에 로그인

새 브라우저 탭을 열고 ArgoCD URI를 입력하세요: https://<my-argo-cd-url>
LOGIN VIA AZURE 버튼을 클릭해 Microsoft Entra ID 계정으로 로그인하세요. ArgoCD 애플리케이션 화면이 보일 것입니다.
User Info로 이동해 Group ID를 확인하세요. 그룹에는 Setup permissions for Entra ID Application 단계에서 추가한 그룹의 Object ID가 표시됩니다.

CLI로 ArgoCD에 로그인

터미널을 열고 아래 명령어를 실행하세요.

    argocd login <my-argo-cd-url> --grpc-web-root-path / --sso

브라우저에서 자격 증명을 입력한 후 아래 메시지가 보일 것입니다.
터미널 출력은 아래와 비슷할 것입니다.

    WARNING: server certificate had error: x509: certificate is valid for ingress.local, not my-argo-cd-url. Proceed insecurely (y/n)? y
    Opening browser for authentication
    INFO[0003] RequestedClaims: map[groups:essential:true ]
    Performing authorization_code flow login: https://login.microsoftonline.com/XXXXXXXXXXXXX/oauth2/v2.0/authorize?access_type=offline&claims=%7B%22id_token%22%3A%7B%22groups%22%3A%7B%22essential%22%3Atrue%7D%7D%7D&client_id=XXXXXXXXXXXXX&code_challenge=XXXXXXXXXXXXX&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A8085%2Fauth%2Fcallback&response_type=code&scope=openid+profile+email+offline_access&state=XXXXXXXX
    Authentication successful
    '[email protected]' logged in successfully
    Context 'my-argo-cd-url' updated

올바르게 서명된 인증서를 사용하지 않으면 경고가 발생할 수 있습니다. "Why Am I Getting x509: certificate signed by unknown authority When Using The CLI?"를 참조하세요.

도메인 힌트 (선택 사항)

Microsoft ID 플랫폼의 경우 oidc.config에서 domainHint를 설정해 로그인 시 도메인 힌트를 제공할 수 있습니다.

구성되면 Argo CD는 Microsoft로 보내는 인가 요청에 domain_hint=<value>를 추가합니다. 이는 다중 테넌트 또는 페더레이션 환경에서 계정 검색 프롬프트를 줄일 수 있습니다.

필드: domainHint
타입: string
필수: 아니오
기본값: 빈 값(파라미터가 전송되지 않음)

예시:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  oidc.config: |
    name: Microsoft
    issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
    clientID: <client-id>
    clientSecret: $oidc.microsoft.clientSecret
    requestedScopes: ["openid", "profile", "email", "groups"]
    domainHint: contoso.com

Microsoft

Microsoft (Entra ID) 연동

본문

Microsoft

OIDC를 사용한 Entra ID App Registration 인증

새 Entra ID App registration 구성

새 Entra ID App registration 추가

ArgoCD CLI용 추가 플랫폼 설정 구성

새 Entra ID App registration에 자격 증명 추가

Workload Identity Federation 사용 (권장)

Client Secret 사용

Entra ID 애플리케이션용 권한 설정

Entra ID 그룹을 Entra ID App registration에 연결

Argo가 새 Entra ID App registration을 사용하도록 구성

Azure AD 그룹 오버플로 해결 (200개 이상 그룹)

개요

전제 조건

구성

구성 옵션

소버린 클라우드(Sovereign Clouds)

동작 방식

문제 해결

Dex를 사용한 Entra ID SAML Enterprise App 인증

새 Entra ID Enterprise App 구성

Argo가 새 Entra ID Enterprise App을 사용하도록 구성

Dex를 사용한 Entra ID App Registration 인증

검증(Validation)

SSO로 ArgoCD UI에 로그인

CLI로 ArgoCD에 로그인

도메인 힌트 (선택 사항)

더 알아보기 (Learn more)