GKE Identity Service를 사용하면 타사 ID 공급업체의 사용자 이름과 비밀번호를 사용하여 명령줄에서 구성된 클러스터에 로그인할 수 있습니다. 클러스터 관리자가 정규화된 도메인 이름(FQDN)으로 GKE Identity Service 서버에서 직접 인증하도록 선택한 경우 이 페이지의 안내를 따르세요.
SAML 제공업체의 경우 로그인 액세스는 이 인증 방법을 통해서만 지원됩니다.
이 인증 방법은 버전 1.29부터 VMware 및 베어메탈용 온프렘 클러스터(Google Distributed Cloud)에서만 지원됩니다. 다른 클러스터 유형은 지원되지 않습니다.
제공된 FQDN으로 로그인하는 데 필요한 gcloud CLI 버전은 최소 버전 477.0.0입니다.
로그인 워크플로
사용자가 FQDN 액세스 방법을 사용하여 로그인할 때의 워크플로 단계는 다음과 같습니다.
로그인 시작: 사용자가 gcloud anthos auth login --server APISERVER-URL 명령어를 실행하여 로그인 프로세스를 시작합니다.
ID 공급업체 선택: 구성된 ID 공급업체 목록이 사용자에게 제공됩니다. 사용자는 사용자 인증 정보가 저장된 제공업체를 선택합니다.
ID 공급업체를 통한 인증: 인증 프로세스는 선택한 ID 공급업체 프로토콜에 따라 다릅니다.
OIDC: 사용자가 OIDC 제공업체 로그인 페이지로 리디렉션됩니다. 로그인에 성공하면 공급업체는 GKE Identity Service로 코드를 다시 전송하여 백 채널 통신을 통해 액세스 토큰으로 교환합니다.
SAML: 사용자가 SAML 제공업체 로그인 페이지로 리디렉션됩니다. 로그인에 성공하면 공급업체는 토큰(어설션)을 GKE Identity Service로 직접 전송하므로 추가 콜백을 방지합니다.
LDAP: 외부 제공업체로 리디렉션하는 대신 GKE Identity Service에서 사용자가 인증된 LDAP 자격 증명을 입력하는 로그인 페이지를 표시하며, LDAP 서버에서 직접 확인합니다.
토큰 확인 및 kubeconfig 파일 생성: GKE Identity Service는 수신된 토큰(또는 어설션)을 확인하고, 사용자에 대해 새 토큰을 생성하며, 이 토큰이 포함된 kubeconfig 파일을 다시 보냅니다.
클러스터 액세스: 사용자는 kubectl 명령어를 사용하여 클러스터에 액세스할 수 있습니다.
kubectl 클라이언트는 각 요청과 함께 kubeconfig 파일에서 토큰을 자동으로 전송합니다.
토큰 검증 및 RBAC 승인: Kubernetes API 서버가 토큰을 수신하고, GKE Identity Service가 이 토큰을 확인한 후 사용자의 클레임(사용자 이름 및 그룹)을 검색합니다.
유효성 검사에 성공하면 API 서버는 역할 기반 액세스 제어(RBAC) 검사를 실행하여 사용자가 액세스하도록 승인된 리소스를 확인합니다.
신뢰할 수 있는 SNI 인증서를 사용하여 로그인
SNI 인증서는 회사 기기에 이미 있는 신뢰할 수 있는 인증서를 활용하여 클러스터 액세스를 간소화합니다. 관리자는 클러스터를 만들 때 이 인증서를 지정합니다. 클러스터가 해당 클러스터 수준에서 신뢰할 수 있는 SNI 인증서를 사용하는 경우 이 섹션의 명령어를 관리자가 제공한 FQDN과 함께 사용하여 클러스터에 로그인하고 액세스 토큰을 받습니다. 인증에 성공한 후 토큰이 저장되는 보안 kubeconfig 파일을 사용할 수도 있습니다.
OUTPUT_FILE: kubeconfig 파일이 기본 위치 이외의 위치에 있으면 이 플래그를 사용합니다. 이 플래그를 생략하면 인증 토큰이 기본 위치의 kubeconfig 파일에 추가됩니다. 예를 들면 다음과 같습니다.
--kubeconfig /path/to/custom.kubeconfig.
클러스터 CA 발급 인증서를 사용하여 로그인
클러스터 수준에서 신뢰할 수 있는 SNI 인증서를 사용하지 않으면 ID 서비스에서 사용하는 인증서가 클러스터의 인증 기관(CA)에서 발급됩니다. 관리자가 이 CA 인증서를 사용자에게 배포합니다.
클러스터의 CA 인증서를 통해 다음 명령어를 실행하여 클러스터에 로그인합니다.
GKE ID 서비스는 두 번째 기기에서 로그인할 때 사용해야 하는 명령어를 반환합니다. 다음은 명령어의 예시입니다.
You are authorizing gcloud CLI without access to a web browser. Please run the following command on a machine with a web browser and copy its output back here.
gcloud auth login --server APISERVER-URL --kubeconfig OUTPUT_FILE --remote-bootstrap="URL_TO_COPY_ON_THE_SECOND_DEVICE"
Enter the output of the above command:
gcloud 명령어를 복사합니다.
두 번째 기기에서 클러스터에 로그인
두 번째 기기에서 로그인하기 전에 브라우저가 설치되어 있고 Kubernetes API 서버에 네트워크 연결이 있는지 확인합니다. 이전 단계에서 복사한 명령어를 두 번째 기기에서 실행합니다.
이 기기에서 로그인을 시도하면 경고 메시지가 표시됩니다. 브라우저에 표시된 표준 인증 절차를 따릅니다. 인증에 성공하면 일회성 코드가 제공됩니다. 이 코드를 복사합니다.
WARNING: The following line enables access to your Cluster resources. ONLY COPY IT TO A MACHINE YOU TRUST AND RUN 'gcloud auth login --server APISERVER-URL --kubeconfig OUTPUT_FILE --no-browser' EARLY ON.
Or_mHYQFm90efgJdwhajx0KeC_WXkuvBPuWv_83nFX9J_Eawm3tQcBpxBBWszj6Ix8dAWCgc1QjJBrlt67bzIYIBTexU7dc_ggtkMTNkG7wCIGYZ75zfg9P1gBshP33STe0ks-AoVonzk01YekMbyNugeYSO18CBwFhaDDSMABq4PI-clgbaSh8CPqrvDKRLenbvfD9BSK6SW945I0bOgPURxNzUX4sICWcvFozhQdLYICuwRM0AgarNFwoeh-0wbJGyRqUjq2NJbaYdf-VCaByiZaGPR2B1QVGXO7deKGtUnk1_tTFOnB6sJQvT6UJ8Ge5nkR38rqBeeGkYdlVIBTXShENG80An1Ve524xZupSzCHNSVTJqYg
기본 기기에서 로그인 완료
이전 단계에서 복사한 코드를 기본 기기의 프롬프트에 붙여넣습니다.
Enter the code you received on the other device: Or_mHYQFm90efgJdwhajx0KeC_WXkuvBPuWv_83nFX9J_Eawm3tQcBpxBBWszj6Ix8dAWCgc1QjJBrlt67bzIYIBTexU7dc_ggtkMTNkG7wCIGYZ75zfg9P1gBshP33STe0ks-AoVonzk01YekMbyNugeYSO18CBwFhaDDSMABq4PI-clgbaSh8CPqrvDKRLenbvfD9BSK6SW945I0bOgPURxNzUX4sICWcvFozhQdLYICuwRM0AgarNFwoeh-0wbJGyRqUjq2NJbaYdf-VCaByiZaGPR2B1QVGXO7deKGtUnk1_tTFOnB6sJQvT6UJ8Ge5nkR38rqBeeGkYdlVIBTXShENG80An1Ve524xZupSzCHNSVTJqYg
기기는 이 코드를 사용하여 kubeconfig 파일에 저장되는 사용자 인증 정보를 생성합니다. 이 파일을 사용하면 기본 기기에서 클러스터에 액세스할 수 있습니다. 로그인하면 다음 메시지가 표시됩니다.
You are logged in!
Context is stored under the name '{cluster-name}'
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["# Log in using a fully qualified domain name (FQDN)\n=================================================\n\nGKE Identity Service lets you log in to configured clusters from the command line using a username and password from a third party identity provider. Follow the instructions in this page if your cluster administrator has chosen to let you authenticate directly on the GKE Identity Service server with a fully qualified domain name (FQDN).\nFor SAML providers, login access is supported only through this authentication\napproach.\n\nThis authentication approach is supported only for on-prem clusters (Google Distributed Cloud) on VMware\nand bare metal, from version 1.29. Other cluster types are not supported.\n\nThe `gcloud` CLI version required to log in with your provided FQDN is\natleast version 477.0.0.\n\nLogin workflow\n--------------\n\nHere are the workflow steps when a user logs in using the FQDN access approach:\n\n1. **Initiate login** : The user runs the command `gcloud anthos auth login --server `\u003cvar translate=\"no\"\u003eAPISERVER-URL\u003c/var\u003e to initiate the login process.\n2. **Identity provider selection**: The user is given a list of configured identity providers. The user selects the provider where their credentials are stored.\n3. **Authentication with identity provider:** The authentication process differs based on the identity provider protocol you choose:\n\n - **OIDC**: The user is redirected to the OIDC-provider login page. After a successful login, the provider sends a code back to the GKE Identity Service, which exchanges it for an access token through a back-channel communication.\n - **SAML**: The user is redirected to the SAML-provider login page. After a successful login, the provider directly sends a token (assertion) back to the GKE Identity Service thereby avoiding an additional callback.\n - **LDAP**: Instead of redirecting to an external provider, the GKE Identity Service displays a login page where the user enters their LDAP credentials, which is verified directly with the LDAP server.\n4. **Token verification and kubeconfig file generation**: The GKE Identity Service\n verifies the token received (or assertion), creates a new token for the user, and\n sends back a kubeconfig file containing this token.\n\n5. **Cluster access** : The user can access the cluster using `kubectl` commands.\n The `kubectl` client automatically sends the token from the kubeconfig file with\n each request.\n\n6. **Token validation and RBAC authorization**: The Kubernetes API server receives\n the token, GKE Identity Service verifies this token, and retrieves the user's claims (username and groups).\n After successful validation, the API server runs Role-Based Access Control (RBAC)\n checks to determine the resources that the user is authorized to access.\n\nLog in using trusted SNI certificates\n-------------------------------------\n\nSNI certificates simplify cluster access by leveraging trusted certificates\nalready present on corporate devices. Administrators can specify this certificate at the\ntime of cluster creation. If your cluster uses a trusted SNI certificate at the cluster\nlevel, use the command in this section with the FQDN provided by your\nadministrator to log in to the cluster and receive an access token. You can also\nuse a secure `kubeconfig` file where the token is stored after successful authentication.\n\nRun the following command to authenticate to the server:\n\n`gcloud anthos auth login --server `\u003cvar translate=\"no\"\u003eAPISERVER-URL\u003c/var\u003e` --kubeconfig `\u003cvar translate=\"no\"\u003eOUTPUT_FILE\u003c/var\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eAPISERVER-URL\u003c/var\u003e: FQDN of the cluster's Kubernetes API server.\n- \u003cvar translate=\"no\"\u003eOUTPUT_FILE\u003c/var\u003e: Use this flag if your `kubeconfig` file resides in a location other than the default. If this flag is omitted, authentication tokens are added to the `kubeconfig` file in the default location. For example: `--kubeconfig /path/to/custom.kubeconfig`.\n\nLog in using cluster CA-issued certificates\n-------------------------------------------\n\nIf you don't use a trusted SNI certificate at the cluster level, then\nthe certificate used by the identity service is issued by the cluster's\ncertificate authority (CA). Administrators distribute this CA certificate to users.\nRun the following command using the cluster's CA certificate to log in to your cluster:\n\n`gcloud anthos auth login --server `\u003cvar translate=\"no\"\u003eAPISERVER-URL\u003c/var\u003e` --kubeconfig `\u003cvar translate=\"no\"\u003eOUTPUT_FILE\u003c/var\u003e` --login-config-cert `\u003cvar translate=\"no\"\u003eCLUSTER_CA_CERTIFICATE\u003c/var\u003e\n| **Note:** As a recommendation, users can trust the CA certificate on their devices and browsers by following the device-specific instructions. This is a one-time activity. Once the CA certificate is trusted, you can log in to the cluster without specifying the `--login-config-cert` argument in the command.\n\nCross-device authentication\n---------------------------\n\nCross-device authentication lets you sign in to Google Distributed Cloud (GDC) clusters from devices that don't have a browser installed. You can initiate the authentication process on your primary device (which doesn't have a browser installed) and complete it on a secondary device installed with a browser.\n\nUse the following steps for a cross-device authentication setup.\n\n1. **Log in to your primary device**\n\n Run the following command to authenticate to the server on your primary device.\n Specify the argument `--no-browser` to indicate that the device you need to\n access your cluster from does not have a browser installed.\n\n `gcloud anthos auth login --server `\u003cvar translate=\"no\"\u003eAPISERVER-URL\u003c/var\u003e` --kubeconfig `\u003cvar translate=\"no\"\u003eOUTPUT_FILE\u003c/var\u003e` --no-browser`\n\n GKE Identity Service returns a command that you need to use when you log\n in from the second device. Here's an example of what the command looks like: \n\n You are authorizing gcloud CLI without access to a web browser. Please run the following command on a machine with a web browser and copy its output back here.\n\n gcloud auth login --server \u003cvar translate=\"no\"\u003eAPISERVER-URL\u003c/var\u003e --kubeconfig \u003cvar translate=\"no\"\u003eOUTPUT_FILE\u003c/var\u003e --remote-bootstrap=\"\u003cvar translate=\"no\"\u003eURL_TO_COPY_ON_THE_SECOND_DEVICE\u003c/var\u003e\"\n\n Enter the output of the above command:\n\n Copy the `gcloud` command.\n2. **Log in to clusters on the second device**\n\n Before logging in from the second device, verify that you have the browser installed\n and have network connectivity to the Kubernetes API server. Run the command you copied from\n the previous step on the second device. \n\n gcloud auth login --server \u003cvar translate=\"no\"\u003eAPISERVER-URL\u003c/var\u003e --kubeconfig \u003cvar translate=\"no\"\u003eOUTPUT_FILE\u003c/var\u003e --remote-bootstrap=\"\u003cvar translate=\"no\"\u003eURL_TO_COPY_ON_THE_SECOND_DEVICE\u003c/var\u003e\"\n\n When attempting to log in from this device, a warning message is displayed. Follow the standard authentication process as displayed on the browser. After a successful authentication, you will be provided with a one-time code. Copy this code. \n\n WARNING: The following line enables access to your Cluster resources. ONLY COPY IT TO A MACHINE YOU TRUST AND RUN 'gcloud auth login --server \u003cvar translate=\"no\"\u003eAPISERVER-URL\u003c/var\u003e --kubeconfig \u003cvar translate=\"no\"\u003eOUTPUT_FILE\u003c/var\u003e --no-browser' EARLY ON.\n\n Or_mHYQFm90efgJdwhajx0KeC_WXkuvBPuWv_83nFX9J_Eawm3tQcBpxBBWszj6Ix8dAWCgc1QjJBrlt67bzIYIBTexU7dc_ggtkMTNkG7wCIGYZ75zfg9P1gBshP33STe0ks-AoVonzk01YekMbyNugeYSO18CBwFhaDDSMABq4PI-clgbaSh8CPqrvDKRLenbvfD9BSK6SW945I0bOgPURxNzUX4sICWcvFozhQdLYICuwRM0AgarNFwoeh-0wbJGyRqUjq2NJbaYdf-VCaByiZaGPR2B1QVGXO7deKGtUnk1_tTFOnB6sJQvT6UJ8Ge5nkR38rqBeeGkYdlVIBTXShENG80An1Ve524xZupSzCHNSVTJqYg\n\n3. **Complete log in on your primary device**\n\n Paste the copied code from the previous step into the prompt of your primary\n device. \n\n Enter the code you received on the other device: Or_mHYQFm90efgJdwhajx0KeC_WXkuvBPuWv_83nFX9J_Eawm3tQcBpxBBWszj6Ix8dAWCgc1QjJBrlt67bzIYIBTexU7dc_ggtkMTNkG7wCIGYZ75zfg9P1gBshP33STe0ks-AoVonzk01YekMbyNugeYSO18CBwFhaDDSMABq4PI-clgbaSh8CPqrvDKRLenbvfD9BSK6SW945I0bOgPURxNzUX4sICWcvFozhQdLYICuwRM0AgarNFwoeh-0wbJGyRqUjq2NJbaYdf-VCaByiZaGPR2B1QVGXO7deKGtUnk1_tTFOnB6sJQvT6UJ8Ge5nkR38rqBeeGkYdlVIBTXShENG80An1Ve524xZupSzCHNSVTJqYg\n\n Your device uses this code to generate a credential that is saved in a\n `kubeconfig` file. This file enables access to the cluster on your primary\n device. When you have logged in, the following message is displayed: \n\n You are logged in!\n Context is stored under the name '{cluster-name}'"]]
