OIDC 인증을 위해 Fleet 멤버 클러스터 설정

이 문서에서는 클러스터 관리자 또는 애플리케이션 운영자가 서드 파티 OpenID Connect (OIDC) 제공업체를 사용하여 인증을 지원하도록 클러스터를 구성하는 방법을 설명합니다.

제한사항

OIDC를 지원하는 클러스터 유형을 사용해야 합니다.

시작하기 전에

  1. Install the Google Cloud CLI.

  2. 외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

  3. gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다. 

    gcloud init

  4. gcloud CLI를 초기화한 후 업데이트하고 필요한 구성요소를 설치합니다. 

    gcloud components update
gcloud components install kubectl
  5. 플랫폼 관리자가 필요한 모든 공급자 정보를 제공했는지 확인합니다. 자세한 내용은 ID 공급업체 세부정보 공유를 참고하세요.
  6. Google Cloud 콘솔을 사용하여 인증하려면 구성하려는 각 클러스터를 프로젝트 Fleet에 등록합니다. 자세한 내용은 Fleet 생성 개요를 참고하세요.
  7. 배스천 호스트를 통해 현재 VPC 네트워크 외부에 있는 AWS 또는 Azure 클러스터의 제어 영역에 연결하려면 배스천 호스트를 만들었고 8118 포트에서 SSH 터널을 시작했는지 확인합니다. 이 문서에서 kubectl 명령어를 실행할 때는 명령어 앞에 HTTPS_PROXY=http://localhost:PORT을 추가합니다. 여기서 PORT은 SSH 터널을 시작할 때 사용한 포트 번호입니다.
  8. Google Cloud의 GKE 클러스터의 경우 클러스터를 Fleet에 등록합니다.

클러스터 구성

OIDC를 사용하여 클러스터에 대한 인증을 구성하려면 ClientConfig라는 Kubernetes 커스텀 리소스에 다음 정보를 추가합니다.

  • 클라이언트 ID, 보안 비밀번호 등 ID 공급자에 관한 정보
  • 인증에 ID 공급자가 사용하는 JSON 웹 토큰 (JWT)에 관한 정보입니다.
  • ID 공급업체에 고유한 추가 범위 또는 매개변수

플랫폼 관리자 또는 조직에서 ID를 관리하는 사용자로부터 필요한 정보에 대한 자세한 내용은 ID 공급업체 세부정보 공유를 참고하세요.

클러스터는 ClientConfig 커스텀 리소스의 필드를 사용하여 ID 공급자와 상호작용합니다. 모든 클러스터에는 kube-public 네임스페이스에 default라는 ClientConfig가 있습니다. 수정하는 특정 필드는 ID 공급업체에 따라 다릅니다.

default ClientConfig를 수정하려면 kubectl을 통해 클러스터에 연결할 수 있는지 확인한 후 다음 명령어를 실행합니다.

kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public

KUBECONFIG_PATH를 클러스터의 kubeconfig 파일 경로로 바꿉니다(예: $HOME/.kube/config).

텍스트 편집기가 클러스터의 ClientConfig 리소스를 로드합니다. 다음 샘플에 표시된 대로 spec.authentication.oidc 객체를 추가합니다. 이미 작성된 기본 데이터를 수정하지 마세요.

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_AUTHORITY_DATA
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
      enableAccessToken: ENABLE_ACCESS_TOKEN
    proxy: PROXY_URL
# Rest of the resource is managed by Google. DO NOT MODIFY.

예를 들어 다음 ID 토큰 필드를 고려해 보세요.

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  # Multiple lines are omitted here
}

이 예에서 iss는 ID 공급업체 URI이고 sub는 사용자를 식별하며 groupList는 사용자가 속한 보안 그룹을 나열합니다. 이 예시에는 실제 토큰에 있을 수 있는 필드의 샘플만 표시되어 있습니다.

위의 예시 토큰의 경우 ClientConfig의 spec.authentication.oidc 객체에서 다음 필드를 업데이트합니다.

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
# Multiple lines are omitted here

동일한 ClientConfig에 여러 OIDC, LDAP, SAML ID 공급업체 구성을 추가할 수 있습니다. 클러스터는 정의된 순서대로 각 구성으로 인증을 시도하고 첫 번째 인증에 성공하면 중지됩니다. 다음 예시 ClientConfig는 특정 순서로 여러 ID 공급자를 정의합니다.

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - aws:
      region: us-west-2
    name: AWS Login
  - ldap:
  # Multiple lines are omitted here.
  - saml:
  # Multiple lines are omitted here.
  - azureAD:
  # Multiple lines are omitted here.
  - oidc:
    name: Okta OIDC
  # Multiple lines are omitted here.
  - oidc:
    name: Google OIDC
  # Multiple lines are omitted here.

ClientConfig OIDC 필드

다음 표는 ClientConfig oidc 객체의 필드를 설명합니다. 추가해야 하는 필드는 ID 공급업체 토큰과 플랫폼 관리자가 공급업체를 구성한 방식에 따라 다릅니다.

필드 필수 설명 형식
name 예 이 구성을 식별하는 데 사용할 이름입니다(일반적으로 ID 공급업체 이름). 구성 이름은 문자로 시작해야 합니다. 이어서 최대 39자(영문 기준)의 소문자, 숫자 또는 하이픈이 와야 하며 하이픈으로 끝나면 안 됩니다 문자열
certificateAuthorityData 아니요 플랫폼 관리자가 제공한 경우 ID 공급업체의 PEM 인코딩 인증서 문자열입니다. certificateAuthorityData에 결과 문자열을 단일 줄로 포함합니다. 문자열
clientID 예 ID 공급업체의 클라이언트 ID입니다. 문자열
clientSecret 아니요 OIDC 클라이언트 애플리케이션과 OIDC 제공업체 간에 공유된 보안 비밀입니다. 문자열
deployCloudConsoleProxy 아니요 Google Cloud 콘솔이 인터넷을 통해 공개적으로 액세스할 수 없는 온프레미스 ID 공급업체에 연결할 수 있게 해주는 프록시가 배포되었는지 여부를 지정합니다. 기본적으로 false로 설정됩니다. 불리언
extraParams 아니요 쉼표로 구분된 목록으로 지정된 ID 공급업체에 전송할 추가 키-값 매개변수입니다(예: `prompt=consent,access_type=offline`). 쉼표로 구분된 목록
groupsClaim 아니요 제공업체가 계정의 보안 그룹을 반환하기 위해 사용하는 JWT 클레임(필드 이름)입니다. 문자열
groupPrefix 아니요 여러 ID 공급업체(일반적으로 제공업체 이름)에 대한 구성이 있는 경우 액세스 제어 규칙의 기존 이름과 충돌하지 않도록 보안 그룹 이름 앞에 추가하려는 프리픽스입니다. 문자열
issuerURI 예 ID 공급업체에 승인 요청이 수행된 URI입니다. URI는 HTTPS를 사용해야 하며 후행 슬래시로 끝나서는 안 됩니다. URL 문자열
kubectlRedirectURI 예 리디렉션 URI: gcloud CLI에서 사용하고 플랫폼 관리자가 등록할 때 지정하는 리디렉션 URL 및 포트로, 일반적으로 http://localhost:PORT/callback 형식입니다. URL 문자열
범위 예 OpenID 제공업체에 전송할 추가적인 범위입니다. 예를 들어 Microsoft Azure와 Okta에는 offline_access 범위가 필요합니다. 쉼표로 구분된 목록
userClaim 아니요 제공업체가 사용자 계정을 식별하는 데 사용하는 JWT 클레임(필드 이름)입니다. 여기에서 값을 지정하지 않으면 기본값은 다수의 공급업체에서 사용하는 사용자 ID 클레임인 '하위'입니다. OpenID 제공업체에 따라 '이메일' 또는 '이름'과 같은 다른 클레임을 선택할 수 있습니다. 'email' 이외의 클레임은 이름 충돌을 방지하기 위해 발급기관 URL이 프리픽스로 추가됩니다. 문자열
userPrefix 아니요 기본 프리픽스를 사용하지 않으려는 경우 기존 이름과 충돌을 방지하기 위해 사용자 클레임 앞에 추가되는 프리픽스입니다. 문자열
enableAccessToken 아니요 사용 설정된 경우 클러스터는 사용자가 명령줄에서 로그인할 때 ID 공급업체의 사용자 정보 엔드포인트를 사용하여 그룹 정보를 가져올 수 있습니다. 이렇게 하면 이 엔드포인트에서 그룹 클레임을 제공하는 제공업체(예: Okta)가 있을 때 승인을 위해 보안 그룹을 사용할 수 있습니다. 설정하지 않은 경우 false로 간주됩니다. 불리언
proxy 아니요 해당되는 경우 ID 공급업체에 연결하는 데 사용할 프록시 서버 주소입니다. 예를 들어 클러스터가 비공개 네트워크에 있고 공개 ID 공급업체에 연결해야 하는 경우 이를 설정해야 할 수 있습니다. 예를 들면 http://user:password@10.10.10.10:8888입니다. 문자열

ClientConfig를 수정한 후 파일을 저장하여 클러스터의 ClientConfig를 업데이트합니다. 문법 오류가 발생하면 오류를 수정하고 파일을 저장하라는 메시지가 표시됩니다.

제공업체별 구성

이 섹션에서는 몇 가지 많이 사용되는 OIDC 제공업체의 구성 안내를 제공하며, 여기에는 자체 세부정보로 복사하고 수정할 수 있는 구성 예시가 포함됩니다.

Microsoft Entra ID

이는 Microsoft Entra ID를 사용한 인증을 위해 클러스터를 설정하는 기본 구성입니다. 이 구성을 사용하면 클러스터가 Microsoft Entra ID에서 사용자 및 그룹 멤버십 정보를 가져올 수 있고 그룹을 기준으로 Kubernetes 역할 기반 액세스 제어 (RBAC)를 설정할 수 있습니다. 그러나 이 구성을 사용하면 사용자당 약 200개 그룹을 검색하도록 제한됩니다.

사용자당 그룹을 200개 넘게 검색해야 할 경우에는 Microsoft Entra ID (고급) 안내를 참고하세요.

# Multiple lines are omitted here.
spec:
  authentication:
  - name: oidc-entraid
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

다음을 바꿉니다.

  • CLIENT_ID: Microsoft Entra ID의 클라이언트 ID입니다.
  • CLIENT_SECRET: OIDC 클라이언트 애플리케이션과 OIDC 제공업체 간에 공유된 보안 비밀입니다.
  • TENANT_ID: 인증할 Microsoft Entra ID 계정의 종류입니다. 지원되는 값은 테넌트 ID 또는 특정 테넌트에 속한 계정의 테넌트 이름입니다. 테넌트 이름은 기본 도메인이라고도 합니다. 이러한 값을 찾는 방법에 대한 자세한 내용은 Microsoft Entra 테넌트 ID 및 기본 도메인 이름 찾기를 참고하세요.
  • PORT: gcloud CLI에서 사용하는 리디렉션 URL에 대해 선택된 포트 번호이며 등록 시 플랫폼 관리자가 지정합니다.

Microsoft Entra ID (고급)

이 선택적인 Microsoft Entra ID 구성을 사용하면 클러스터에서 Microsoft Graph API를 사용하여 사용자당 그룹 수에 대한 제한 없이 사용자 및 그룹 정보를 검색할 수 있습니다.

이 구성을 지원하는 플랫폼에 대한 자세한 내용은 Microsoft Entra ID 고급 설정을 참고하세요.

사용자당 그룹을 200개 미만으로 검색해야 할 경우에는 ClientConfig에서 oidc 앵커를 사용하는 기본 구성을 사용하는 것이 좋습니다. 자세한 내용은 Microsoft Entra ID 안내를 참고하세요.

다음 구성 예시의 모든 필드가 필수입니다.

# Multiple lines are omitted here.
spec:
  authentication:
  - name: NAME
    proxy: PROXY_URL
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_ID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM
# Multiple lines are omitted here. Do not modify any pre-filled data.

다음을 바꿉니다.

  • NAME: 이 구성을 식별하는 데 사용할 이름입니다(일반적으로 ID 공급업체 이름). 구성 이름은 문자로 시작해야 합니다. 이어서 최대 39자(영문 기준)의 소문자, 숫자 또는 하이픈이 와야 하며 하이픈으로 끝나서는 안 됩니다
  • PROXY_URL: 해당되는 경우 ID 공급업체에 연결하는 데 사용할 프록시 서버 주소입니다. 예를 들어 클러스터가 비공개 네트워크에 있고 공개 ID 공급업체에 연결해야 하는 경우 이를 설정해야 할 수 있습니다. 예를 들면 http://user:password@10.10.10.10:8888입니다.
  • CLIENT_ID: Microsoft Entra ID의 클라이언트 ID입니다.
  • CLIENT_SECRET: OIDC 클라이언트 애플리케이션과 OIDC 제공업체 간에 공유된 보안 비밀입니다.
  • TENANT: 인증할 Microsoft Entra 계정의 종류입니다. 지원되는 값은 테넌트 ID 또는 특정 테넌트에 속한 계정의 테넌트 이름입니다. 테넌트 이름은 기본 도메인이라고도 합니다. 이러한 값을 찾는 방법에 대한 자세한 내용은 Microsoft Entra 테넌트 ID 및 기본 도메인 이름 찾기를 참고하세요.
  • PORT: gcloud CLI에서 사용하는 리디렉션 URL에 대해 선택된 포트 번호이며 등록 시 플랫폼 관리자가 지정합니다.
  • GROUP_FORMAT: 그룹 정보를 검색하려는 형식입니다. 이 필드에는 사용자 그룹의 ID 또는 NAME에 해당하는 값을 사용할 수 있습니다. 이 설정은 베어메탈 Google Distributed Cloud 배포의 클러스터에만 사용할 수 있습니다.
  • USER_CLAIM(선택사항): 제공업체가 계정을 식별하는 데 사용하는 JWT 클레임(필드 이름)입니다. 여기에 값을 지정하지 않으면 클러스터가 'email', 'preferred_username' 또는 'sub' 순으로 값을 사용해 사용자 세부정보를 가져옵니다. 이 속성은 버전 1.28부터 사용할 수 있습니다.

Okta

다음은 Okta를 ID 공급업체로 사용해서 사용자와 그룹을 모두 사용하여 인증을 설정하는 방법을 보여줍니다. 이 구성을 사용하면 클러스터가 액세스 토큰 및 Okta의 사용자 정보 엔드포인트를 사용하여 사용자 및 그룹 클레임을 검색할 수 있습니다.

# Multiple lines are omitted here.
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

그룹 액세스 한도

Okta 사용자의 경우 클러스터가 연결된 그룹 이름의 길이가 170,000자 미만인 사용자에 대해 그룹 정보를 검색할 수 있습니다. 이것은 Okta 그룹 길이가 최대라고 가정할 때 약 650개 그룹의 멤버십에 해당합니다. 사용자가 너무 많은 그룹의 멤버이면 인증 호출이 실패합니다.

다음 단계

구성이 적용된 후 클러스터에 대한 사용자 액세스 설정하기