OS 登入疑難排解

本文說明如何使用中繼資料伺服器排解 OS 登入問題。如要瞭解如何設定 OS 登入或查看逐步說明,請參閱「設定 OS 登入」。

您可以從 Compute Engine 執行個體內部查詢中繼資料伺服器。詳情請參閱「儲存及擷取執行個體中繼資料」。

事前準備

  • 如果尚未設定驗證,請先完成設定。驗證程序會確認您的身分,以便您存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例,您可以選取下列其中一個選項,向 Compute Engine 進行驗證:

    請根據您打算如何使用本頁範例,選取對應的分頁標籤:

    控制台

    使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時,您不需要設定驗證機制。

    gcloud

    1. 安裝 Google Cloud CLI。 安裝完成後,請執行下列指令,初始化 Google Cloud CLI:

      gcloud init

      若您採用的是外部識別資訊提供者 (IdP),請先使用聯合身分登入 gcloud CLI。

  • 設定預設區域和可用區。
  • REST

    如要在本機開發環境中使用本頁的 REST API 範例,請使用您提供給 gcloud CLI 的憑證。

      安裝 Google Cloud CLI。

      若您採用的是外部識別資訊提供者 (IdP),請先使用聯合身分登入 gcloud CLI。

    詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」一節。

常見錯誤訊息

以下是使用 OS 登入時可能遇到的常見錯誤範例。

找不到群組名稱

在某些使用 OS 登入的運算執行個體上,建立連線後可能會收到下列錯誤訊息:

/usr/bin/id: cannot find name for group ID 123456789

忽略這則錯誤訊息。這項錯誤不會影響運算執行個體。

無法取得群組

建立運算執行個體時,您可能會看到類似下方的記錄:

Dec 10 22:31:05 instance-1 google_oslogin_nss_cache[381]: oslogin_cache_refresh[381]: Refreshing group entry cache
Dec 10 22:31:05 instance-1 google_oslogin_nss_cache[381]: oslogin_cache_refresh[381]: Failure getting groups, quitting

這些記錄指出貴組織未設定 OS 登入 Linux 群組。請忽略這些訊息。

不符合先決條件

使用 SSH 連線至運算執行個體時,您可能會看到類似下列的錯誤:

ERROR: (gcloud.compute.ssh) FAILED_PRECONDITION: The specified username or UID is not unique within given system ID.

如果 OS 登入嘗試產生的使用者名稱已存在於組織中,就會發生這項錯誤。這種情況通常發生在刪除使用者帳戶後,不久又建立具有相同電子郵件地址的新使用者。使用者帳戶刪除後,最多需要 48 小時才能移除使用者的 POSIX 資訊。

如要解決這個問題,請按照下列其中一種做法進行:

OS 登入設定檔大小超過上限

使用 SSH 連線至 Linux 運算執行個體,或使用 SCP 傳輸檔案時,可能會看到下列其中一項錯誤:

ERROR: (gcloud.compute.ssh) FAILED_PRECONDITION: Login profile size exceeds 32 KiB. Delete profile values to make additional space.
ERROR: (gcloud.compute.scp) INVALID_ARGUMENT: Login profile size exceeds 32 KiB. Delete profile values to make additional space.

OS 登入會將使用者資訊 (包括安全殼層公開金鑰) 儲存在 POSIX 帳戶中,每位使用者的儲存空間上限為 32 KiB。如果 OS 登入設定檔超過這項限制,或設定檔中的安全殼層金鑰超過 64 個,就無法再新增安全殼層金鑰,也無法使用安全殼層連線至 VM。

如要解決這些錯誤,請執行下列任一操作:

  1. 檢查 OS 登入設定檔的大小。如要檢查設定檔的大小,請將設定檔匯出至暫存 JSON 檔案,然後執行下列指令來檢查檔案大小:

    gcloud compute os-login describe-profile --format="json" | wc
    

    如果大小接近或超過 32 KiB,請務必移除未使用的安全殼層金鑰。

  2. 查看 OS 登入設定檔,找出未使用的安全殼層金鑰:

    gcloud compute os-login describe-profile
    

    輸出結果會與下列內容相似:

    name: '00000000000000'
    posixAccounts:
    ...
    sshPublicKeys:
     ...:
       fingerprint: ...
       key: |
         ssh-rsa AAAAB3NzaC1yc2...
       name: ...
     ...
    
  3. 使用 gcloud compute os-login ssh-keys remove 指令移除所有未使用的金鑰:

    gcloud compute os-login ssh-keys remove --key=KEY
    

    將 KEY 替換為金鑰的指紋或完整的安全殼層公開金鑰字串。

或者,如要避免在連線至 VM 時產生新金鑰,可以採取下列任一做法:

  • 使用 gcloud compute ssh 指令指定 --ssh-key-file 旗標,重複使用現有的金鑰組:

    gcloud compute ssh VM_NAME --ssh-key-file=PATH_TO_PRIVATE_KEY
    
  • 如果您經常使用 gcloud CLI 透過 SSH 連線至 VM,請在 .ssh/ 目錄中建立名為 google_compute_engine 的預設安全殼層金鑰組。如果這個金鑰組存在,gcloud CLI 指令列就會使用這個金鑰組,而不會在每次連線時產生新的金鑰組。如要產生預設金鑰組,請執行下列指令:

    ssh-keygen -t rsa -f ~/.ssh/google_compute_engine -C USERNAME -b 2048
    

    接著,將公開金鑰新增至 OS 登入設定檔:

    gcloud compute os-login ssh-keys add --key-file=~/.ssh/google_compute_engine.pub
    

Cloud Build

如果您使用 Cloud Build,且服務帳戶的 OS 登入設定檔超過 32 KiB 限制,可能會發生 SSH 連線失敗,並看到下列錯誤訊息:Login profile size exceeds 32 KiB...。如要解決這個問題,您可以將 Cloud Build 設為使用使用者指定的服務帳戶,而非預設的 Cloud Build 服務帳戶。

為避免日後發生這個問題,請為安全殼層金鑰新增到期時間。過期的金鑰會在過期 48 小時後,或您在設定檔中新增金鑰時,自動從登入設定檔中移除。

HTTP 回應代碼:429

嘗試使用 SSH 連線至運算執行個體時,可能會看到下列錯誤:

Failed to validate organization user USERNAME has login permission, got HTTP response code: 429

這個問題是由中繼資料伺服器頻率限制所造成,每個運算執行個體每秒最多只能查詢 100 次。這項限制無法調整。如要解決這個問題,請等待幾秒鐘,然後重新連線。

為避免日後發生這個問題,請嘗試下列做法:

  • 在應用程式程式碼中導入重試機制。詳情請參閱:
  • 重複使用現有的 SSH 連線。
  • 批次傳送指令,減少 SSH 連線和 OS 登入中繼資料查詢。

預設 OS 登入中繼資料項目

Compute Engine 定義了一組預設中繼資料項目,用於提供 OS 登入資訊。預設中繼資料一律由伺服器定義及設定。預設中繼資料鍵會區分大小寫。

下表說明可查詢的項目。

相對於 http://metadata.google.internal/computeMetadata/v1/
中繼資料項目 說明
project/attributes/enable-oslogin 檢查目前的 Google Cloud 專案是否已啟用 OS 登入功能。
instance/attributes/enable-oslogin 檢查目前的運算執行個體是否已啟用 OS 登入功能。
oslogin/users/ 擷取 OS 登入使用者的設定檔資訊。您可以傳遞 username、uid、pagesize 和 pagetoken 等查詢參數。
oslogin/authorize/

擷取 OS 登入使用者的登入或管理層級權限設定。

如要檢查權限,您必須指定 policy 查詢參數。政策參數的值必須設為 login (檢查登入權限) 或 adminLogin (檢查 sudo 存取權)。

檢查是否已設定 OS 登入

使用 Google Cloud 控制台或 Google Cloud CLI 查詢中繼資料,判斷是否已啟用 OS 登入功能。在專案或執行個體中繼資料中,將 enable-oslogin 中繼資料鍵設為 TRUE,即可啟用 OS 登入功能。如果同時設定執行個體和專案中繼資料,系統會優先採用執行個體中繼資料中設定的值。

查看 OS 登入使用者

如要查看多位使用者的個人資料資訊,可以指定 pagesize 參數。將 pagesize 替換為必要的數值。

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize=PAGE_SIZE" -H "Metadata-Flavor: Google"

輸出內容可能包含頁面權杖,可用於後續呼叫,列出更多使用者。

舉例來說,如要將 pagesize 設為 1,請執行下列指令:

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize=1" -H "Metadata-Flavor: Google"

如要取得下一位使用者,請將 pagesize 設為 1,並將 pagetoken 設為上一個指令輸出內容中的頁面權杖。

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize=1&pagetoken=PAGE_TOKEN" -H "Metadata-Flavor: Google"

在大多數發行版中,您也可以執行 Unix 指令 getent passwd,擷取組織使用者的密碼項目。

查看特定 OS 登入使用者

如要查看運算執行個體上特定使用者的設定檔資訊,請執行下列指令:

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=USERNAME" -H "Metadata-Flavor: Google"

將 USERNAME 替換為要查詢的使用者名稱。

舉例來說,您可以執行要求來查詢使用者 user_example_com。下列指令和輸出內容已新增格式,方便閱讀。

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=user_example_com" -H "Metadata-Flavor: Google"

輸出結果會與下列內容相似:

{
    "loginProfiles": [{
        "name": "12345678912345",
        "posixAccounts": [{
            "primary": true,
            "username": "user_example_com",
            "uid": "123451",
            "gid": "123451",
            "homeDirectory": "/home/user_example_com",
            "operatingSystemType": "LINUX"
        }],
        "sshPublicKeys": {
            "204c4b4fb...": {
                "key": "ssh-rsa AAAAB3Nz...",
                "fingerprint": "204c4b4fb..."
            }
        }
    }]
}

在大多數發行版中,您也可以執行 Unix 指令 (例如 getent passwd username 或 getent passwd uid) 來擷取設定檔資訊。

如要擷取使用者的安全殼層金鑰,您也可以執行 /usr/bin/google_authorized_keys USERNAME。如果未傳回任何金鑰,表示使用者可能沒有登入運算執行個體所需的權限。

正在檢查登入權限

如要查看登入和管理層級權限,您必須提供 policy=login&email=LOGIN_NAME 查詢參數。

  1. 查詢使用者個人資料,取得 name 欄位的值:

    curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=user_example_com" -H "Metadata-Flavor: Google"
  2. 在輸出內容中,記下 name。

  3. 使用 name 的值執行下列 login 指令:

    curl "http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?policy=login&email=LOGIN_NAME" -H "Metadata-Flavor: Google"
    

例如,您可以查詢上一節中查看的使用者 user_example_com 的登入權限:

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?policy=login&email=12345678912345" -H "Metadata-Flavor: Google"

指令輸出內容指出,使用者有權登入運算執行個體:

{"success":true}

檢查運算執行個體是否有服務帳戶

您可以查詢中繼資料伺服器,找出與運算執行個體相關聯的服務帳戶。登入運算執行個體,然後執行下列指令:

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/" -H "Metadata-Flavor: Google"

輸出結果會與下列內容相似:

12345-sa@developer.gserviceaccount.com/
default/

如果找不到服務帳戶,輸出內容會是空白。

啟用雙重驗證時的 SSH 問題

以下各節說明如何在執行個體上設定採用雙重驗證 (2FA) 的 OS 登入,以及如何在啟用 2FA 時排解 SSH 連線錯誤。

雙重驗證

雙重驗證可為 OS 登入多添一層防護。如果貴組織內的使用者帳戶遭到入侵,運算執行個體的 SSH 存取權仍會受到保護,直到第二個因素通過驗證為止。

將 enable-oslogin-2fa 中繼資料鍵設為 TRUE 時,客體代理程式會將下列雙重驗證 PAM 設定新增至 /etc/pam.d/sshd 檔案頂端:

auth       [success=done perm_denied=die default=ignore] pam_oslogin_login.so

訪客代理程式也會更新全系統的 OpenSSH 設定檔 /etc/ssh/sshd_config。客體代理程式不會從檔案中刪除先前設定的關鍵字引數組合,但由於 OpenSSH 會使用每個參數的第一個值,因此客體代理程式會在 /etc/ssh/sshd_config 檔案頂端加入下列幾行:

AuthenticationMethods publickey,keyboard-interactive
ChallengeResponseAuthentication yes

排解雙重驗證連線錯誤

使用 SSH 連線至已啟用 2FA 的運算執行個體時,Cloud Shell 可能會傳回一般 Permission denied (keyboard-interactive) 或 not authorized 錯誤訊息,但不會指明失敗原因:

Permission denied (keyboard-interactive)
ERROR: (gcloud.compute.start-iap-tunnel) Error while connecting [4033: 'not authorized'].
kex_exchange_identification: Connection closed by remote host
Connection closed by UNKNOWN port 65535

ERROR: (gcloud.compute.ssh) [/usr/bin/ssh] exited with return code [255].

啟用雙重驗證後,如果無法使用 SSH 連線至運算執行個體,請按照下列步驟操作:

  1. 如要確認問題是否由雙重驗證造成,請取消設定 enable-oslogin-2fa 中繼資料金鑰,或將其設為 FALSE,然後嘗試連線至運算執行個體。如果仍無法存取運算執行個體,問題可能與雙重驗證無關。

  2. 如果停用 2FA 後可以存取運算執行個體,請在 /var/log/ 目錄的記錄檔中尋找 2FA 錯誤訊息,判斷 2FA 失敗的原因。

  3. 連線至執行個體時,請重新啟用 enable-oslogin-2fa,並確認訪客代理程式已更新 /etc/pam.d/sshd 和 /etc/ssh/sshd_config 檔案,例如使用 ls -l 指令檢查修改時間戳記。確認檔案包含雙重驗證一節所述的必要 pam_oslogin_login.so、AuthenticationMethods publickey,keyboard-interactive 和 ChallengeResponseAuthentication yes 項目。

  4. 如要檢查連線失敗是否是因為 Google 帳戶或網域未啟用兩步驟驗證 (2SV),請篩選 OS 登入稽核記錄或 /var/log/ 目錄中的記錄檔,找出下列錯誤訊息:

    "message": "The caller does not have permission"
    
          "@type": "type.googleapis.com/google.cloud.oslogin.v1.StartSessionRequest",
          "supportedChallengeTypes": [
            "INTERNAL_TWO_FACTOR",
            "SECURITY_KEY_OTP",
            "AUTHZEN",
            "TOTP",
            "IDV_PREREGISTERED_PHONE"
          ],
    

    如果未在 Google 帳戶或網域啟用兩步驟驗證,系統就會記錄這則錯誤訊息。SSH 用戶端也可能傳回 No supported authentication methods available (server sent: keyboard-interactive) 錯誤。

    如要確認帳戶是否已啟用兩步驟驗證,請前往 Google 帳戶安全性設定。如果帳戶未啟用兩步驟驗證,系統不會顯示對話方塊提示您輸入安全碼,登入嘗試會失敗,並顯示一般 Permission denied 錯誤。

    您也可以與 Google Workspace 管理員聯絡,確認網域是否已啟用兩步驟驗證。

  5. 如果 OS 登入 ContinueSession 稽核記錄的 response.challenges 屬性顯示 'READY' 以外的任何狀態,可能表示您使用的驗證問題有問題。以下範例說明無法透過語音或簡訊驗證碼完成登入程序的問題:

    "response": {
        "challenges": [
          {
            "challengeId": 2,
            "challengeType": "IDV_PREREGISTERED_PHONE",
            "status": "RETRYABLE_ERROR"
          }
    

    您可以改用其他驗證方法 (例如 Google Authenticator),縮小問題範圍。如果您可以使用其他驗證方法連線,但註冊的手機未收到簡訊驗證碼,且記錄中顯示 IDV_PREREGISTERED_PHONE 的 RETRYABLE_ERROR,請與 Google Workspace 支援團隊聯絡。

後續步驟