OIDC 및 Google로 인증

이 페이지에서는 GKE On-Prem으로 OpenID Connect(OIDC)를 사용하는 방법을 보여줍니다. OIDC를 사용하려면 OpenID 제공업체를 지정해야 합니다. 이 주제에서는 Google을 OpenID 제공업체로 사용하도록 GKE On-Prem을 구성하는 방법을 보여줍니다.

인증 흐름에 대한 개요는 인증을 참조하세요. GKE On-Prem에서 OpenID 제공업체를 사용하는 방법에 대한 일반 정보는 OpenID Connect로 인증을 참조하세요.

제한사항

Google OpenID 제공업체는 그룹을 지원하지 않습니다. Kubernetes 역할 기반 액세스 제어(RBAC)를 사용하여 인증된 사용자에게 역할을 부여할 때는 그룹이 아닌 개별 사용자에게 역할을 부여해야 합니다.

개요

GKE On-Prem은 OpenID Connect(OIDC)를 사용자 클러스터의 Kubernetes API 서버와 상호작용하는 인증 메커니즘 중 하나로 지원합니다. OIDC를 사용하면 조직에서 직원 계정을 만들고, 사용 설정하고, 사용 중지하기 위한 표준 절차에 따라 Kubernetes 클러스터 액세스를 관리할 수 있습니다.

직원이 OIDC 인증 흐름을 사용할 수 있는 방법은 두 가지입니다.

  • 직원은 kubectl을 사용하여 OIDC 흐름을 시작할 수 있습니다. 이 흐름을 자동으로 설정하기 위해 GKE On-Prem은 kubectl 플러그인이라는 Kubectl용 Anthos 플러그인을 제공합니다.

  • 직원은 Google Cloud Console을 사용하여 OIDC 인증 흐름을 시작할 수 있습니다.

이 연습에서는 kubectl 및 Google Cloud console의 두 가지 옵션을 모두 구성합니다.

시작하기 전에

이 주제를 읽기 전에 개발자는 OAuth 2.0 및 OpenID Connect를 숙지해야 합니다. 또한 OpenID 범위 및 클레임도 숙지해야 합니다.

캐릭터

이 주제에서는 세 가지 캐릭터를 기준으로 설명합니다.

  • 조직 관리자: 이 사람은 OpenID 제공업체를 선택하고 클라이언트 애플리케이션을 제공업체에 등록합니다.

  • 클러스터 관리자: 이 사람은 사용자 클러스터를 하나 이상 만들고 클러스터를 사용하는 개발자를 위한 인증 구성 파일을 만듭니다.

  • 개발자: 이 사람은 클러스터 한 개 이상에서 워크로드를 실행하고 OIDC를 사용하여 인증합니다.

Kubectl용 Anthos 플러그인의 리디렉션 URL 만들기

이 섹션은 조직 관리자를 위한 것입니다.

Google을 OpenID 제공업체로 구성하려면 Google에서 Kubectl용 Anthos 플러그인에 ID 토큰을 반환하는데 사용할 수 있는 리디렉션 URL을 지정해야 합니다. Kubectl용 Anthos 플러그인은 각 개발자의 로컬 머신에서 실행되고 사용자가 선택한 포트에서 리슨합니다. 이 목적에 적합한 1024를 초과하는 포트 번호를 선택하세요. 리디렉션 URL은 다음과 같습니다.

http://localhost:[PORT]/callback

여기서 [PORT]는 포트 번호입니다.

Google OpenID 제공업체를 구성할 때 http://localhost:[PORT]/callback을 리디렉션 URL 중 하나로 지정합니다.

Google Cloud console의 리디렉션 URL 구성

이 섹션은 조직 관리자를 위한 것입니다.

Kubectl용 Anthos 플러그인의 리디렉션 URL 외에도 Google Cloud Console의 리디렉션 URL이 필요합니다. Google Cloud Console의 리디렉션 URL은 다음과 같습니다.

https://console.cloud.google.com/kubernetes/oidc

Google OpenID 제공업체를 구성할 때 https://console.cloud.google.com/kubernetes/oidc를 리디렉션 URL 중 하나로 지정합니다.

이 섹션에서는 Google의 OAuth 동의 화면을 구성합니다. 조직의 개발자가 사용자 클러스터에 대한 인증을 시작하면 이 동의 화면으로 이동합니다. 이때 Google에 ID를 증명하고 식별 정보를 OAuth 클라이언트에 제공하는 토큰을 만들 수 있는 권한을 Google에 부여합니다. 이 주제의 컨텍스트에서 OAuth 클라이언트는 Kubectl용 Anthos 플러그인 또는 Google Cloud Console입니다.

  1. Google Cloud Console에서 OAuth 동의 화면 페이지로 이동합니다.

    OAuth 동의 화면 구성

  2. 내부를 선택하고 만들기를 클릭합니다.

  3. 애플리케이션 유형에 내부를 선택합니다.

  4. 애플리케이션 이름에 원하는 이름을 입력합니다. GKE on-prem을 사용하는 것이 좋습니다.

  5. 승인된 도메인에서 google.com을 추가합니다.

  6. 필요에 따라 추가 필드를 입력합니다.

  7. 저장을 클릭합니다.

Google에 클라이언트 애플리케이션 등록

이 섹션에서는 Google이 조직 내 개발자의 OpenID 제공업체 역할을 할 수 있도록 GKE On-Prem을 Google에 등록합니다. 등록의 일환으로 이전에 만든 리디렉션 URL 두 개를 제공해야 합니다.

  1. Google Cloud 콘솔의 사용자 인증 정보 페이지로 이동합니다.

    사용자 인증 정보 페이지로 이동

  2. 사용자 인증 정보 만들기를 클릭하고 OAuth 클라이언트 ID를 선택합니다.

  3. 애플리케이션 유형에 웹 애플리케이션을 선택합니다.

  4. 이름에 원하는 이름을 입력합니다.

  5. 승인된 리디렉션 URI 아래에 리디렉션 URL 두 개를 추가합니다. Kubectl용 Anthos 플러그인의 리디렉션 URL 및 Google Cloud Console의 리디렉션 URL을 만들었다는 것을 기억해 봅시다.

  6. 만들기를 클릭합니다.

  7. 클라이언트 ID와 클라이언트 보안 비밀번호가 제공됩니다. 나중에 사용할 수 있도록 저장합니다.

GKE On-Prem 구성 파일에서 oidc 사양 채우기

이 섹션은 클러스터 관리자를 위해 작성되었습니다.

사용자 클러스터를 만들기 전에 gkectl create-config를 사용하여 GKE On-Prem 구성을 생성합니다. 구성에는 다음 oidc 사양이 포함됩니다. oidc에 제공업체 특정 값을 채웁니다.

oidc:
  issuerurl:
  kubectlredirecturl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: "https://accounts.google.com"으로 설정합니다. Kubectl용 Anthos 플러그인과 Google Cloud Console 같은 클라이언트 애플리케이션은 이 URL로 승인 요청을 보냅니다. Kubernetes API 서버는 이 URL을 사용하여 토큰을 확인할 수 있도록 공개 키를 검색합니다.
  • kubectlredirecturl: Kubectl용 Anthos 플러그인에 대해 이전에 구성한 리디렉션 URL입니다.
  • clientid: OpenID 제공업체에 인증을 요청하는 클라이언트 애플리케이션의 ID입니다. Kubectl용 Anthos 플러그인과 Google Cloud Console 모두 이 ID를 사용합니다. Google에 클라이언트 애플리케이션을 등록하면 이 ID가 부여됩니다.
  • clientsecret: 클라이언트 애플리케이션의 보안 비밀입니다. Kubectl용 Anthos 플러그인과 Google Cloud Console 모두 이 보안 비밀을 사용합니다. Google에 클라이언트 애플리케이션을 등록하면 이 ID가 부여됩니다.
  • username: "email"로 설정합니다.
  • usernameprefix: (선택사항) 기존 이름과 충돌하지 않도록 사용자 이름 클레임에 추가되는 프리픽스입니다. 이 필드를 제공하지 않고 username이 email 이외의 값이면 기본적으로 issuerurl# 프리픽스가 추가됩니다. - 값을 사용하면 모든 프리픽스 추가가 중지될 수 있습니다.
  • group: 비워둡니다.
  • groupprefix: 비워둡니다.
  • scopes: "email"로 설정합니다.
  • extraparams: "prompt=consent,access_type=offline"으로 설정합니다.
  • usehttpproxy: "false"로 설정합니다.
  • capath: 비워둡니다.

사용자 클러스터의 RBAC 정책 만들기

이 섹션은 클러스터 관리자를 위해 작성되었습니다.

클러스터를 만든 후 Kubernetes 역할 기반 액세스 제어(RBAC)를 사용하여 인증된 클러스터 사용자에게 액세스 권한을 부여합니다. 특정 네임스페이스의 리소스에 대한 액세스 권한을 부여하려면 Role과 RoleBinding을 만듭니다. 전체 클러스터에서 리소스에 대한 액세스 권한을 부여하려면 ClusterRole과 ClusterRoleBinding을 만듭니다.

Google을 OpenID 제공업체로 사용하는 경우 개별 사용자에게 액세스 권한을 부여해야 합니다. 그룹에 대한 액세스 권한을 부여할 수 없습니다. 이는 Google OpenID 제공업체가 반환하는 토큰에 개별 사용자가 속하는 그룹에 대한 정보가 없기 때문입니다.

예를 들어 jane@example.com이 클러스터 전체에서 모든 보안 비밀 객체를 볼 수 있게 하려고 한다고 가정합니다.

다음은 secret-viewer라는 ClusterRole의 매니페스트입니다. 이 역할이 부여된 사람은 클러스터의 모든 보안 비밀을 가져오고, 보고, 나열할 수 있습니다.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: secret-viewer
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "watch", "list"]

다음은 people-who-view-secrets라는 ClusterRoleBinding의 매니페스트입니다. Binding은 jane@example.com이라는 사용자에게 secret-viewer 역할을 부여합니다.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: people-who-view-secrets
subjects:
- kind: User
  name: jane@example.com
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-viewer
  apiGroup: rbac.authorization.k8s.io

ClusterRole을 만들려면 매니페스트를 secret-viewer-cluster-role.yaml 파일에 저장하고 다음 명령어를 입력합니다.

kubectl --kubeconfig [USER_CLUSTER_KUBECONFIG] apply -f secret-viewer-cluster-role.yaml

여기서 [USER_CLUSTR_KUBECONFIG]는 사용자 클러스터의 kubeconfig 파일입니다.

ClusterRoleBinding을 만들려면 매니페스트를 secret-viewer-cluster-role-binding.yaml 파일에 저장하고 다음 명령어를 입력합니다.

kubectl --kubeconfig [USER_CLUSTER_KUBECONFIG] apply -f secret-viewer-cluster-role-binding.yaml

첫 번째 인증 구성 파일 만들기

이 섹션은 클러스터 관리자를 위해 작성되었습니다.

사용자 클러스터를 만든 후 클러스터에 대해 인증 구성 파일을 만듭니다.

gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG]

여기서 [USER_CLUSTER_KUBECONFIG]는 사용자 클러스터의 kubeconfig 파일 경로입니다. 사용자 클러스터를 만들 때 gkectl create cluster는 클러스터의 kubeconfig 파일을 생성했습니다.

위 명령어는 현재 디렉터리에 kubectl-anthos-config.yaml이라는 파일을 만듭니다.

인증 구성 파일에 클러스터 추가

이 섹션은 클러스터 관리자를 위해 작성되었습니다.

여러 클러스터에 대한 인증 구성을 단일 파일로 저장할 수 있습니다. 그런 다음 이 하나의 파일을 이 모든 클러스터에 액세스해야 하는 개발자들에게 배포할 수 있습니다.

기존 인증 구성 파일로 시작합니다. 그런 후 다음 명령어를 사용하여 이 파일을 추가 클러스터를 위한 구성과 병합합니다.

gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG] \
    --merge-from [IN_AUTH_CONFIG_FILE] --output [OUT_AUTH_CONFIG_FILE]

각 항목의 의미는 다음과 같습니다.

  • [USER_CLUSTER_KUBECONFIG]는 추가 클러스터의 kubeconfig 파일입니다.

  • [IN_AUTH_CONFIG_FILE]은 기존 인증 구성 파일의 경로입니다.

  • [OUT_AUTH_CONFIG_FILE]은 병합된 구성이 포함된 파일을 저장할 경로입니다. [IN_AUTH_CONFIG_FILE]과 동일할 수 있습니다.

인증 구성 파일 배포

이 섹션은 클러스터 관리자를 위해 작성되었습니다.

개발자에게 배포하는 인증 구성 파일은 이름을 kubectl-anthos-config.yaml로 지정해야 합니다. 인증 구성 파일은 여러 방법으로 배포할 수 있습니다.

  • 파일을 각 개발자에게 수동으로 제공합니다.

  • 개발자가 다운로드할 수 있도록 파일을 URL에 호스팅합니다.

  • 파일을 각 개발자의 머신에 푸시합니다.

배포 방법에 관계없이 인증 구성 파일은 각 개발자의 머신에서 이 위치에 있어야 합니다.

Linux

$HOME/.config/google/anthos/kubectl-anthos-config.yaml

macOS

$HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

Windows

%APPDATA%\google\anthos\kubectl-anthos-config.yaml

인증 구성 파일 배치

이 섹션은 개발자를 위해 작성되었습니다.

인증 구성 파일에는 인증 가능한 모든 클러스터에 대한 세부정보가 포함되어 있습니다. 이 파일의 내용을 수정하지 마세요.

클러스터 관리자가 사용자에게 인증 구성 파일을 제공한 경우 이 파일을 올바른 디렉터리에 두세요. 클러스터 관리자가 사용자의 머신에 구성을 이미 배치한 경우 이 섹션을 건너뛸 수 있습니다.

인증 구성 파일을 해당 기본 위치에 복사합니다.

Linux

mkdir -p  $HOME/.config/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/.config/google/anthos/kubectl-anthos-config.yaml

여기서 [AUTH_CONFIG_FILE]은 인증 구성 파일의 이름입니다.

macOS

mkdir -p  $HOME/Library/Preferences/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

여기서 [AUTH_CONFIG_FILE]은 인증 구성 파일의 이름입니다.

Windows

md "%APPDATA%\google\anthos"
copy [AUTH_CONFIG_FILE] "%APPDATA%\google\anthos\kubectl-anthos-config.yaml"

여기서 [AUTH_CONFIG_FILE]은 인증 구성 파일의 이름입니다.

Kubectl용 Anthos 플러그인 가져오기

이 섹션은 클러스터 관리자를 위해 작성되었습니다.

Kubectl용 Anthos 플러그인은 다음 위치에서 관리자 워크스테이션에 포함되어 있습니다.

Linux

/usr/bin/kubectl_anthos/v1.0beta/linux_amd64/kubectl-anthos

macOS

/usr/bin/kubectl_anthos/v1.0beta/darwin_amd64/kubectl-anthos

Windows

/usr/bin/kubectl_anthos/v1.0beta/windows_amd64/kubectl-anthos

개발자에게 플러그인을 배포하거나 개발자가 플러그인을 직접 다운로드하도록 설정할 수 있습니다.

Kubectl용 Anthos 플러그인 다운로드

이 섹션은 클러스터 관리자 및 개발자를 위해 작성되었습니다.

각 개발자는 자신의 고유 머신에 Kubectl용 Anthos 플러그인이 있어야 합니다. 개발자가 플러그인을 개별적으로 다운로드하거나, 클러스터 관리자가 플러그인을 다운로드한 후 이를 개발자에게 배포할 수 있습니다.

개발자 참고: 클러스터 관리자에게 사용할 플러그인 버전을 확인하세요.

Kubectl용 Anthos 플러그인 다운로드:

Linux

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/linux_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

macOS

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/darwin_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

Windows

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/windows_amd64/kubectl-anthos ./
rename kubectl-anthos kubectl-anthos.exe.

Kubectl용 Anthos 플러그인 설치

이 섹션은 개발자를 위해 작성되었습니다.

클러스터 관리자가 사용자에게 Kubectl용 Anthos 플러그인을 제공할 수 있습니다. 또는 클러스터 관리자가 사용자에게 플러그인을 직접 다운로드하라고 알려줄 수 있습니다.

Kubectl용 Anthos 플러그인을 설치하려면 실행 파일을 PATH에 있는 위치로 이동합니다. 실행 파일의 이름은 kubectl-anthos여야 합니다. 자세한 내용은 kubectl 플러그인 설치를 참조하세요.

Kubectl용 Anthos 플러그인이 설치되었는지 확인합니다.

kubectl plugin list
kubectl anthos version

사용 가능한 클러스터 나열

이 섹션은 개발자를 위해 작성되었습니다.

인증 구성 파일이 기본 경로에 있으면 다음 명령어를 입력하여 인증할 수 있는 클러스터를 나열합니다.

kubectl anthos listclusters

인증 구성 파일이 기본 경로에 없으면 다음 명령어를 입력하여 클러스터를 나열합니다.

kubectl anthos listclusters --loginconfig [AUTH_CONFIG_FILE]

여기서 [AUTH_CONFIG_FILE]은 인증 구성 파일의 경로입니다.

Kubectl용 Anthos 플러그인을 사용하여 인증

이 섹션은 개발자를 위해 작성되었습니다.

사용자 클러스터에 로그인합니다.

kubectl anthos login --cluster [CLUSTER_NAME] --user [USER_NAME] \
    --loginconfig [AUTH_CONFIG_FILE] --kubeconfig [USER_CLUSTER_KUBECONFIG]

각 항목의 의미는 다음과 같습니다.

  • [CLUSTER_NAME]은 사용자 클러스터의 이름입니다. 이 이름은 kubectl anthos listclusters 명령어로 제공된 목록에서 선택해야 합니다.

  • [USER_NAME]은 kubeconfig 파일에 저장된 사용자 인증 정보의 사용자 이름을 지정하는 선택적 매개변수입니다. 기본값은 [CLUSTER_NAME]-anthos-default-user입니다.

  • [AUTH_CONFIG_FILE]은 인증 구성 파일의 경로입니다. 인증 구성 파일이 기본 위치에 있으면 이 매개변수를 생략할 수 있습니다.

  • [USER_CLUSTER_KUBECONFIG]는 사용자 클러스터의 kubeconfig 파일 경로입니다. kubeconfig 파일이 없으면 명령어가 인증 구성 파일로부터 새로운 kubeconfig 파일을 생성하고 클러스터 세부정보 및 토큰을 kubeconfig 파일에 추가합니다.

kubectl anthos login은 사용자 인증 정보를 입력할 수 있는 브라우저를 시작합니다.

이제 kubeconfig 파일에 kubectl이 사용자 클러스터의 Kubernetes API 서버에 인증하는 데 사용할 수 있는 ID 토큰이 포함됩니다.

kubectl anthos login 명령어에는 선택적 --dry-run 플래그가 있습니다. --dry-run 플래그를 포함하면 명령어가 kubeconfig 파일에 토큰을 추가하는 kubectl 명령어를 출력하지만 실제로 kubeconfig 파일에 토큰을 저장하지 않습니다.

kubectl 명령어를 입력하여 인증이 성공했는지 확인합니다. 예를 들면 다음과 같습니다.

kubectl get nodes --kubeconfig [USER_CLUSTER_KUBECONFIG]

Google Cloud 콘솔에서 OIDC 사용

이 섹션은 개발자를 위해 작성되었습니다.

  1. 클러스터가 OIDC용으로 구성되었는지 확인합니다.

  2. 클러스터 생성 중에 자동으로 또는 수동으로 클러스터가 Google Cloud에 등록되었는지 확인합니다.

  3. Google Cloud 콘솔에서 Kubernetes 클러스터 페이지를 방문합니다.

    Kubernetes 클러스터 페이지로 이동

  4. 클러스터 목록에서 GKE On-Prem 클러스터를 찾아 로그인을 클릭합니다.

  5. 클러스터에 구성된 ID 공급업체로 인증을 선택하고 로그인을 클릭합니다.

    ID 공급업체로 리디렉션됩니다. 여기서 계정에 액세스하는 Google Cloud console에 로그인하거나 동의해야 할 수 있습니다. 그러면 Google Cloud console에서 Kubernetes 클러스터 페이지로 다시 리디렉션됩니다.

커스텀 구성

기본적으로 Kubectl용 Anthos 플러그인에서는 인증 구성 파일이 특정 위치에 있어야 합니다. 기본 위치에 인증 구성 파일을 두지 않으려면 --login-config 플래그를 사용하여 인증 구성 파일의 경로를 플러그인 명령어에 수동으로 전달할 수 있습니다. 예를 들어 Kubectl용 Anthos 플러그인을 사용하여 인증을 참조하세요.

GKE On-Prem에서 OIDC 문제 해결

잘못된 구성

Google Cloud console이 클러스터에서 OIDC 구성을 읽을 수 없으면 로그인 버튼이 중지됩니다.

잘못된 제공업체 구성

ID 공급업체 구성이 잘못된 경우 로그인을 클릭하면 ID 공급업체의 오류 화면이 표시됩니다. 공급업체별 안내에 따라 제공업체 또는 클러스터를 올바르게 구성합니다.

잘못된 권한

인증 절차를 완료했지만 클러스터의 세부정보가 여전히 표시되지 않는 경우 OIDC와 함께 사용한 계정에 올바른 RBAC 권한을 부여했는지 확인하세요. 이 계정은 Google Cloud console에 액세스하는 계정과 다른 계정일 수 있습니다.

Error: missing 'RefreshToken' field in 'OAuth2Token' in credentials struct

승인 서버에서 동의를 요청하지만 필요한 인증 매개변수가 제공되지 않으면 이 오류가 발생할 수 있습니다. GKE On-Prem 구성 파일의 oidc: extraparams 필드에 prompt=consent 매개변수를 제공하고 --extra-params prompt=consent 플래그를 사용하여 클라이언트 인증 파일을 다시 생성합니다.

다음 단계