OIDC 및 A DFS로 인증

이 페이지에서는 OpenID Connect(OIDC)와 Active Directory Federation Services(AD FS)를 사용하여 GKE On-Prem 사용자 클러스터용으로 인증을 구성하는 방법을 보여줍니다.

인증 흐름에 대한 개요는 인증을 참조하세요. AD FS 대신 OpenID 공급업체 사용에 대한 자세한 내용은 OpenID Connect로 인증을 참조하세요.

개요

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

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

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

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

이 연습에서는 kubectl 및 Google Cloud console의 두 가지 옵션을 모두 구성합니다. AD FS 관리 마법사 집합을 사용하여 AD FS 서버와 AD 직원 데이터베이스를 구성합니다.

시작하기 전에

이 주제에서는 개발자가 OAuth 2.0 및 OpenID Connect에 익숙하다고 가정합니다. 이 주제에서는 개발자가 OpenID 범위 및 클레임에 익숙하다고 가정합니다.

이 주제는 다음 인프라가 있는 기업에 적용됩니다.

  • 직원 데이터베이스에 Active Directory(AD)를 사용하는 기업
  • Active Directory Federation Services(AD FS) 서버를 실행하는 기업
  • OpenID 공급자 역할을 하는 AD FS 서버

OIDC용 Kubectl 플러그인 다운로드

이 섹션은 OIDC용 Kubectl 플러그인을 사용하려는 관리자와 직원을 위해 작성되었습니다.

플러그인을 다운로드하고 액세스 권한을 설정합니다.

Linux

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/linux_amd64/kubectl-oidc .
chmod +x kubectl-oidc

Windows

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/windows_amd64/kubectl-oidc .

macOS

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/darwin_amd64/kubectl-oidc .
chmod +x kubectl-oidc

플러그인 설치

실행 파일을 원하는 PATH 위치로 이동시켜 플러그인을 설치합니다. 실행 파일의 이름은 kubectl-oidc여야 합니다. 자세한 내용은 kubectl 플러그인 설치를 참조하세요.

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

이 섹션은 관리자용입니다.

AD FS 서버와의 관계를 설정하려면 AD FS 서버가 OIDC용 Kubectl 플러그인에 ID 토큰을 반환하는데 사용할 수 있는 리디렉션 URL을 지정해야 합니다. OIDC용 Kubectl 플러그인은 각 직원의 로컬 머신에서 실행되며 원하는 포트에서 수신 대기합니다. 이 목적에 적합한 1024를 초과하는 포트 번호를 선택하세요. 리디렉션 URL은 다음과 같습니다.

http://localhost:[PORT]/callback

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

AD FS 서버를 구성할 때는 http://localhost:[PORT]/callback을 리디렉션 URL 중 하나로 지정합니다.

Google Cloud 콘솔의 리디렉션 URL 구성

이 섹션은 관리자용입니다.

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

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

AD FS 서버를 구성할 때는 https://console.cloud.google.com/kubernetes/oidc를 리디렉션 URL 중 하나로 지정합니다.

AD FS 구성

다음 섹션에서는 GKE On-Prem용으로 AD FS를 구성하는 방법을 설명합니다.

리디렉션 URL 설정

  1. AD FS 관리 창을 엽니다.

  2. 애플리케이션 그룹 > 작업 > 애플리케이션 그룹 추가를 선택합니다.

  3. 서버 애플리케이션을 선택합니다. 원하는 이름과 설명을 입력합니다. 다음을 클릭합니다.

  4. 2개의 리디렉션 URL을 입력합니다. 클라이언트 ID가 제공됩니다. 이렇게 하면 AD FS 서버가 OIDC 및 Google Cloud 콘솔용 Kubectl 플러그인을 식별할 수 있습니다. 나중을 위해 클라이언트 ID를 저장합니다.

  5. 공유 보안 비밀 생성을 선택합니다. OIDC 및 Google Cloud 콘솔용 Kubectl 플러그인은 이 보안 비밀을 사용하여 AD FS 서버에 인증합니다. 나중을 위해 이 보안 비밀을 저장합니다.

보안 그룹 구성(선택사항)

  1. AD FS 관리에서 신뢰 당사자 트러스트 또는 새 신뢰 당사자 트러스트 추가를 선택합니다.

  2. 클레임 인식을 선택하고 시작을 클릭합니다.

  3. 신뢰 당사자에 대한 수동 데이터 입력을 선택합니다.

  4. 표시 이름을 입력합니다.

  5. 다음 두 단계를 건너뜁니다.

  6. 신뢰 당사자 트러스트 식별자를 입력합니다. 제안사항: token-groups-claim

  7. 액세스 제어 정책에 모두 허용을 선택합니다. 즉, 모든 직원이 OIDC 및 Google Cloud 콘솔용 Kubectl 플러그인과 보안 그룹 정보를 공유합니다.

  8. 마침을 클릭합니다.

클레임 이름에 LDAP 속성 매핑

  1. AD FS 관리에서 신뢰 당사자 트러스트 > 클레임 발급 정책 편집을 선택합니다.

  2. LDAP 특성을 클레임으로 보내기를 선택하고 다음을 클릭합니다.

  3. 클레임 규칙 이름에 groups를 입력합니다.

  4. 속성 저장소에 Active Directory를 선택합니다.

  5. 표에서 LDAP 속성에 대해 다음을 선택합니다.

    • AD FS 버전 5.0 이상: 도메인 이름으로 정규화된 토큰 그룹
    • 5.0 이전의 AD FS 버전: 토큰 그룹 - 정규화된 이름

  6. 보내는 클레임 유형에서 다음을 선택합니다.

    • AD FS 버전 5.0 및 이후: Group
    • AD FS 버전 5.0 이전: groups

  7. 마침을 클릭하고 적용을 클릭합니다.

AD FS를 사용하여 OIDC 및 Google Cloud 콘솔용 Kubectl 플러그인 등록

관리자 모드에서 PowerShell 창을 열고 다음 명령어를 입력합니다.

Grant-AD FSApplicationPermission `
    -ClientRoleIdentifier "[CLIENT_ID]" `
    -ServerRoleIdentifier [SERVER_ROLE_IDENTIFIER] `
    -ScopeName "allatclaims", "openid"

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

  • [CLIENT_ID]는 이전에 가져온 클라이언트 ID입니다.

  • [SERVER_ROLE_IDENTIFIER]는 이전에 입력한 클레임 식별자입니다. 제안된 식별자는 token-groups-claim이었다는 것을 기억하세요.

클러스터 구성 파일에 oidc 사양 채우기

이 섹션은 OIDC를 사용하도록 구성된 클러스터를 만들려는 직원을 위한 것입니다.

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

oidc:
  issuerurl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: (필수사항) OpenID 제공업체의 URL입니다(예: https://example.com/adfs). OIDC용 Kubectl 플러그인 및 Google Cloud 콘솔과 같은 클라이언트 애플리케이션은 이 URL로 승인 요청을 보냅니다. Kubernetes API 서버는 이 URL을 사용하여 토큰을 확인할 수 있도록 공개 키를 검색합니다. HTTPS를 사용해야 합니다.
  • clientid: 필수. OpenID 제공업체에 인증을 요청하는 클라이언트 애플리케이션의 ID입니다. OIDC용 Kubectl 플러그인과 Google Cloud 콘솔 모두 이 ID를 사용합니다.
  • clientsecret: 선택사항. 클라이언트 애플리케이션의 보안 비밀입니다. OIDC용 Kubectl 플러그인과 Google Cloud 콘솔 모두 이 보안 비밀을 사용합니다.
  • username: 선택사항. 사용자 이름으로 사용할 JWT 클레임입니다. 기본값은 sub입니다. 이 값은 최종 사용자의 고유 식별자로 사용됩니다. OpenID 제공업체에 따라 email 또는 name과 같은 다른 클레임을 선택할 수 있습니다. 하지만 email 이외의 클레임은 다른 플러그인과의 이름 충돌을 방지하기 위해 발급기관 URL이 프리픽스로 추가됩니다.
  • usernameprefix: (선택사항) 기존 이름과 충돌하지 않도록 사용자 이름 클레임에 추가되는 프리픽스입니다. 이 필드를 제공하지 않고 username이 email 이외의 값이면 기본적으로 issuerurl# 프리픽스가 추가됩니다. - 값을 사용하면 모든 프리픽스 추가가 중지될 수 있습니다.
  • group: (선택사항) 제공업체가 보안 그룹을 반환하기 위해 사용할 JWT 클레임입니다.
  • groupprefix: (선택사항) 기존 이름과 충돌을 방지하기 위해 그룹 클레임에 추가된 프리픽스입니다. 예를 들어 그룹이 foobar이고 프리픽스가 gid-이면 gid-foobar가 됩니다.
  • scopes: 선택사항. OpenID 공급업체에 쉼표로 구분된 목록으로 전송할 추가 범위입니다.
  • extraparams: 선택사항. OpenID 제공업체에 쉼표로 구분된 목록으로 전송할 추가적인 키-값 매개변수입니다.
  • usehttpproxy: 선택사항. Connect Agent가 사용자 인증을 위해 온프레미스 OIDC 제공업체에 액세스하도록 허용하기 위해 클러스터에 역방향 프록시를 배포할지 여부를 지정합니다. 값은 문자열 "true" 또는 "false"여야 합니다.
  • capath: 선택사항. ID 공급업체의 웹 인증서를 발급한 인증 기관(CA)의 인증서 경로입니다. 이 값은 필수가 아닐 수 있습니다. 예를 들어 ID 공급업체의 인증서가 잘 알려진 공개 CA에서 발급된 경우 여기에 값을 제공할 필요가 없습니다.

예: 사용자 및 그룹 승인

대부분의 제공업체는 이메일 및 사용자 ID와 같은 사용자 식별 속성을 토큰에 인코딩합니다. 그러나 다음 속성은 인증 정책에 암시적 위험이 있습니다.

  • 사용자 ID는 정책을 읽고 감사하기 어렵게 만들 수 있습니다.
  • 이메일로 인해 가용성 위험(사용자가 기본 이메일을 변경하는 경우) 및 잠재적 보안 위험(이메일을 다시 할당할 수 있는 경우)이 생길 수 있습니다.

따라서 그룹 ID는 영구적이고 감사하기 쉬울 수 있으므로 그룹 정책을 사용하는 것이 좋습니다.

제공업체에서 다음 필드를 포함하는 ID 토큰을 생성한다고 가정합니다.

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList: ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}
이 토큰 형식을 사용하면 다음과 같이 구성 파일의 oidc 사양을 채웁니다. 
issueruri: 'https://server.example.com'
username: 'sub'
usernameprefix: 'uid-'
group: 'groupList'
groupprefix: 'gid-'
extraparams: 'resource=token-groups-claim'
...

사용자 클러스터를 만든 후 Kubernetes 역할 기반 액세스 제어(RBAC)를 사용하여 인증된 사용자에게 액세스 권한을 부여할 수 있습니다. 예를 들어 사용자에게 클러스터의 보안 비밀에 대한 읽기 전용 액세스 권한을 부여하는 ClusterRole을 만들고, ClusterRoleBinding 리소스를 만들어 인증된 그룹에 역할을 바인딩할 수 있습니다.

ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: secret-reader
rules:
- apiGroups: [""]
  # The resource type for which access is granted
  resources: ["secrets"]
  # The permissions granted by the ClusterRole
  verbs: ["get", "watch", "list"]

ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-secrets-admins
subjects:
  # Allows anyone in the "us-east1-cluster-admins" group to
  # read Secrets in any namespace within this cluster.
- kind: Group
  name: gid-us-east1-cluster-admins # Name is case sensitive
  apiGroup: rbac.authorization.k8s.io
  # Allows this specific user to read Secrets in any
  # namespace within this cluster
- kind: User
  name: uid-u98523-4509823
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

Kubernetes API 서버의 CA 인증서 저장

이 섹션은 사용자 클러스터를 만든 후 이제 OIDC용 Kubectl 플러그인을 사용하려는 직원을 위해 작성되었습니다.

사용자 클러스터에 Kubernetes API 서버가 있습니다. 사용자 클러스터의 kubeconfig 파일은 Kubernetes API 서버에 인증서를 발급한 CA의 인증서를 저장합니다. CA의 인증서는 certificate-authority-data 필드의 base-64 인코딩 값입니다. 이 값을 디코딩하여 server-ca-cert와 같은 로컬 파일에 저장해야 합니다.

cat [USER_CLUSTER_KUBECONFIG]  | grep certificate-authority-data | awk '{ print $2}' | base64 --decode > server-ca-cert

클라이언트 인증 구성 파일 생성

이 섹션은 사용자 클러스터를 만든 후 이제 OIDC용 Kubectl 플러그인을 사용하려는 직원을 위해 작성되었습니다.

클라이언트 인증 구성 파일을 생성하려면 다음 명령어를 입력합니다.

Linux

kubectl oidc client-config \
--issuer-uri [ISSUER_URI] \
--redirect-uri [REDIRECT_URL] \
--client-id [CLIENT_ID] \
--client-secret [CLIENT_SECRET] \
--scopes "[CUSTOM_SCOPES]" \
--cluster-name [USER_CLUSTER_NAME] \
--server [CLUSTER_URL] \
--server-ca-file [SERVER_CA_CERT] \
--issuer-ca-file [PROVIDER_CA_CERT] \
--extra-params [KEY]=[VALUE], ... # e.g. --extra-params "resource=token-groups-claim"
> client-config.yaml

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

  • [ISSUER_URI]는 발급기관 URI입니다.
  • [REDIRECT_URL]은 OIDC용 Kubectl 플러그인의 리디렉션 URL입니다.
  • [CLIENT_ID]는 OIDC용 Kubectl 플러그인의 클라이언트 ID입니다.
  • [CLIENT_SECRET]은 OIDC용 Kubectl 플러그인의 클라이언트 보안 비밀번호입니다.
  • [USER_CLUSTER_NAME]은 사용자 클러스터의 이름입니다.
  • [CLUSTER_URL]은 사용자 클러스터의 Kubernetes API 서버 URL입니다.
  • [SERVER_CA_FILE]은 Kubernetes API 서버에 인증서를 발급한 CA의 인증서 경로입니다. 이전 섹션에서 만든 인증서 파일입니다.
  • [PROVIDER_CA_CERT]는 OpenID 제공업체의 인증서에 서명한 CA의 인증서 경로입니다. 이 값은 클러스터 구성 파일의 oidc:cacert 값과 동일합니다.
  • [CUSTOM_SCOPES]는 보안 그룹을 위한 커스텀 범위를 쉼표로 구분한 목록입니다. 이 값은 클러스터 구성 파일의 oidc:scopes 값과 동일합니다.
  • --extra-params [KEY]=[VALUE], ...는 OpenID 제공업체의 승인 요청에 포함할 쉼표로 구분된 키-값 쌍의 목록입니다.

PowerShell

kubectl oidc client-config `
--issuer-uri [ISSUER_URI] `
--redirect-uri [REDIRECT_URL] `
--client-id [CLIENT_ID] `
--client-secret [CLIENT_SECRET] `
--scopes "[CUSTOM_SCOPES]" `
--cluster-name [USER_CLUSTER_NAME] `
--server [CLUSTER_URL] `
--server-ca-file [SERVER_CA_CERT] `
--issuer-ca-file [PROVIDER_CA_CERT] `
--extra-params [KEY]=[VALUE]
> client-config.yaml

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

  • [ISSUER_URI]는 발급기관 URI입니다.
  • [REDIRECT_URL]은 OIDC용 Kubectl 플러그인의 리디렉션 URL입니다.
  • [CLIENT_ID]는 OIDC용 Kubectl 플러그인의 클라이언트 ID입니다.
  • [CLIENT_SECRET]은 OIDC용 Kubectl 플러그인의 클라이언트 보안 비밀번호입니다.
  • [USER_CLUSTER_NAME]은 사용자 클러스터의 이름입니다.
  • [CLUSTER_URL]은 사용자 클러스터의 Kubernetes API 서버 URL입니다.
  • [SERVER_CA_FILE]은 Kubernetes API 서버에 인증서를 발급한 CA의 인증서 경로입니다. 이전 섹션에서 만든 인증서 파일입니다.
  • [PROVIDER_CA_CERT]는 OpenID 제공업체의 인증서에 서명한 CA의 인증서 경로입니다. 이 값은 클러스터 구성 파일의 oidc:cacert 값과 동일합니다.
  • [CUSTOM_SCOPES]는 보안 그룹을 위한 커스텀 범위를 쉼표로 구분한 목록입니다. 이 값은 클러스터 구성 파일의 oidc:scopes 값과 동일합니다.
  • --extra-params [KEY]=[VALUE], ...는 OpenID 제공업체의 승인 요청에 포함할 쉼표로 구분된 키-값 쌍의 목록입니다.

이 명령어는 client-config.yaml이라는 클라이언트 인증 구성 파일을 생성합니다. 이 파일을 수동으로 수정하지 마세요.

OIDC용 Kubectl 플러그인을 사용하여 사용자 클러스터에 인증

이 섹션은 사용자 클러스터를 만든 후 이제 OIDC용 Kubectl 플러그인을 사용하려는 직원을 위해 작성되었습니다.

  1. client-config.yaml 파일을 사용하여 플러그인을 초기화합니다.

    kubectl oidc login --clientconfig-file=client-config.yaml --user [NAME] \
    --kubeconfig [KUBECONFIG_OUTPUT_PATH]

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

    • [NAME]은 사용자 이름입니다.
    • [KUBECONFIG_OUTPUT_PATH]는 OIDC용 Kubectl 플러그인이 사용자 인증 정보를 저장하는 kubeconfig 파일의 경로입니다.

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

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

    참고: Windows 사용자는 kubectl oidc login 대신 kubectl-oidc.exe 로그인으로 명령어를 실행해야 할 수도 있습니다.

  2. 인증을 성공적으로 수행했는지 확인하려면 kubectl 명령어를 실행합니다. 예를 들면 다음과 같습니다.

    kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]

Google Cloud Console에서 OIDC 사용

이 섹션은 사용자 클러스터를 만든 후 이제 클러스터에 대해 인증하기 위해 Google Cloud Console을 사용하려는 직원을 위해 작성되었습니다.

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

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

  3. Google Cloud 콘솔에서 Kubernetes 클러스터 페이지로 이동합니다.

    Kubernetes 클러스터 페이지로 이동

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

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

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

요약

기업에서 OpenID 제공업체 역할을 하는 AD FS 서버를 실행합니다. OpenID 제공업체는 두 클라이언트 애플리케이션인 OIDC용 Kubectl 플러그인과 Google Cloud 콘솔에 대해 알고 있습니다. OpenID 제공업체는 클라이언트 애플리케이션이 openid 및 allatclaims 범위를 요청할 수 있음을 알고 있습니다.

5.0 이전의 AD FS 버전에서 AD 데이터베이스의 Token-Groups Qualified Names LDAP 특성은 OpenID 제공업체의 groups 클레임에 매핑됩니다. 5.0 및 이후 버전에서는 특성이 Token-Groups Qualified by Domain name입니다. 제공업체는 직원 ID, 발급자 ID, openid 클레임, groups 클레임이 포함된 토큰을 반환합니다. groups(5.0의 경우 Group) 클레임에는 직원이 속하는 보안 그룹이 나열됩니다.

GKE On-Prem에서 OIDC 문제 해결

잘못된 구성

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

잘못된 제공업체 구성

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

잘못된 권한

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

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

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

다음 단계