搭配 IAP 使用自訂 OAuth 用戶端

本文說明何時及如何為 Identity-Aware Proxy (IAP) 使用自訂 OAuth 用戶端。

根據預設，IAP 會使用 Google 代管的 OAuth 用戶端來驗證使用者。Google 代管的 OAuth 用戶端只能用於管理機構內內部使用者的存取權。

您必須使用自訂 OAuth 設定，才能執行下列操作：

  • 管理外部使用者 (非貴機構成員) 對於啟用 IAP 的應用程式的存取權。
  • 管理專案中網頁應用程式的存取權，這些專案不屬於Google Cloud 機構。
  • 在驗證期間的同意畫面上顯示自訂品牌資訊。

您可以在 IAP 或直接在平台上設定自訂 OAuth 用戶端。

使用自訂 OAuth 用戶端時，必須設定 OAuth 同意畫面。 如要在同意畫面中顯示自訂品牌，您必須將應用程式送交 Google 驗證。如要進一步瞭解驗證程序，請參閱「設定 OAuth 同意畫面」。

設定自訂 OAuth 用戶端時，您必須負責建立及管理憑證，包括安全地儲存用戶端密碼，並在必要時與授權用戶端共用。

比較 Google 管理的 OAuth 用戶端和自訂 OAuth 用戶端

Google 代管的 OAuth 用戶端無法透過程式存取受 IAP 保護的應用程式。不過，使用 Google 管理的 OAuth 用戶端的 IAP 保護應用程式，仍可透過 programmatic_clients 設定或服務帳戶 JWT 設定的獨立 OAuth 用戶端，以程式輔助方式存取。

下表比較 Google 管理的 OAuth 用戶端與自訂 OAuth 用戶端。

Google 管理的 OAuth 用戶端 自訂 OAuth 用戶端
使用者 僅供內部使用 內部和外部
品牌 Google Cloud 品牌 客戶擁有的品牌
OAuth 設定 已設定 Google 已設定客戶
OAuth 憑證 Google 代管 客戶自行管理
應用程式存取權 僅限瀏覽器流程 瀏覽器流程和程式輔助存取

設定品牌宣傳頁面

如要使用 Google Cloud 控制台設定自訂品牌宣傳頁面，請按照下列步驟操作：

  1. 前往控制台的 OAuth「品牌」頁面： Google Cloud

    前往「Branding」(品牌宣傳)

  2. 按一下「開始使用」。

  3. 在「應用程式名稱」中，輸入同意畫面上的應用程式名稱。

  4. 在「User support email」(使用者支援電子郵件) 中，輸入支援服務的管理員電子郵件地址。

  5. 在「目標對象」部分，選取「內部」可限制只有貴機構使用者能存取，選取「外部」則允許貴機構外部使用者存取。

  6. 在「聯絡資訊」中，輸入要聯絡的系統管理員電子郵件地址，以便處理受 OAuth 用戶端保護的應用程式。 您會在後續步驟中設定 OAuth 用戶端。

  7. 如要建立 OAuth 設定，請按一下「建立」。

在 IAP 中設定自訂 OAuth 用戶端

本節說明如何在 IAP 中設定自訂 OAuth 用戶端。

建立自訂 OAuth 用戶端

本節說明如何使用Google Cloud 控制台建立自訂 OAuth 用戶端。您可以在資源階層的任何層級設定自訂 IAP OAuth 用戶端。

如要使用 Google Cloud 控制台為資源建立自訂 OAuth 用戶端，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「IAP」頁面。

    前往 IAP

  2. 在「應用程式」分頁的資源清單中，找出要設定的資源。

    專案層級資源：

    • 使用 Google Cloud 控制台建立 OAuth 用戶端：

      1. 在「動作」欄中，依序點選「更多選項」圖示 >「設定」。

      2. 在「設定」對話方塊中，選取「自訂 OAuth」。

      3. 如果您尚未設定同意畫面，請按照下列步驟操作：

        1. 按一下 [Configure consent screen] (設定同意畫面)。

        2. 按照本文件稍早提供的操作說明，設定品牌宣傳頁面。

      4. 在「應用程式內結帳設定」對話方塊中，按一下「自動產生憑證」。IAP 會產生新的 OAuth 用戶端和密鑰，供這個資源使用。在 Google Auth Platform 中，「已授權的重新導向 URI」欄位會包含以下格式的項目：

        https://iap.googleapis.com/v1/oauth/clientIds/CLIENT_ID:handleRedirect

      5. 如要存取用戶端 ID 和密鑰，請按一下「下載憑證」。 憑證會儲存在 JSON 格式的檔案中。由於檔案含有存取資源的機密憑證，請務必保護或刪除檔案。

      6. 如要儲存 IAP OAuth 設定，並將 OAuth 用戶端套用至 IAP，請按一下「儲存」。

將自訂 OAuth 用戶端套用至 IAP

本節說明如何將 OAuth 用戶端套用至 IAP。您可以改用這個方法，不必直接在平台上套用用戶端。

  1. 如要建立自訂 OAuth 用戶端，請按照本文稍早提供的Google Cloud 控制台操作說明操作。

  2. 套用自訂 OAuth 用戶端。

    gcloud

    如要使用 gcloud CLI 套用自訂 OAuth 用戶端，請執行下列步驟：

    1. 建立設定 YAML 檔案。

      cat << EOF > iap-oauth.yaml
accessSettings:
oauthSettings:
  clientId: CLIENT_ID
  clientSecret: CLIENT_SECRET
EOF

      更改下列內容：

      • CLIENT_ID：先前產生的 OAuth 憑證中的用戶端 ID。
      • CLIENT_SECRET：您稍早產生的 OAuth 憑證中的用戶端密鑰。

    2. 如要設定 OAuth，請採取下列其中一種做法：

      • 如要在專案層級設定 OAuth，請執行下列指令：
      gcloud iap settings set iap-oauth.yaml

      如要在資源階層的其他層級設定，請使用下列其中一個旗標，而非 --project 旗標。在資源階層層級設定自訂 OAuth 用戶端，可為該層級內執行的所有服務提供相同的自訂品牌。

      * <code>--folder=<var>FOLDER_ID</var></code>
* <code>--organization=<var>ORGANIZATION_ID</var></code>
      • 如要在特定服務上設定，請執行下列指令：
      gcloud iap settings set iap-oauth.yaml \
    --project=PROJECT_ID \
    --resource-type= RESOURCE_TYPE \
    --region=REGION \
    --service=SERVICE_NAME

      更改下列內容：

      • PROJECT_ID：專案資源的 ID。如要在其他層級設定，請使用下列其中一個標記，而非 --project 標記：

        • --folder=FOLDER_ID
        • --organization=ORGANIZATION_ID

      • RESOURCE_TYPE：視資源而定，替換為下列其中一種資源類型：

        • app-engine
        • backend-services
        • cloud-run
        • compute
        • folder
        • forwarding-rule
        • iap_web
        • organization

      • REGION：執行 Cloud Run 服務的區域。

      • SERVICE_NAME：服務名稱。

    Terraform

    如要使用 Terraform 套用自訂 OAuth 用戶端，請按照下列步驟操作：

    resource "google_iap_settings" "iap_settings" {
name = IAP_RESOURCE_NAME
access_settings {
  oauth_settings {
      oauth_client_id = CLIENT_ID
      oauth_client_secret = CLIENT_SECRET
  }
}
}

    更改下列內容：

    • IAP_RESOURCE_NAME：服務的 iap_settings 資源名稱，格式如下：projects/PROJECT_NUMBER/iap_web/REGION/services/SERVICE_NAME
    • CLIENT_ID：您先前產生的 OAuth 憑證中的用戶端 ID
    • CLIENT_SECRET：您稍早產生的 OAuth 憑證中的用戶端密鑰

    REST API

    1. 建立設定 JSON 檔案。

      cat << EOF > iap-oauth.json
{
"accessSettings": {
  "oauthSettings": {
    "clientId": "CLIENT_ID",
    "clientSecret": "CLIENT_SECRET"
  }
}
}
EOF

      更改下列內容：

      • CLIENT_ID：先前產生的 OAuth 憑證中的用戶端 ID。
      • CLIENT_SECRET：您稍早產生的 OAuth 憑證中的用戶端密鑰。

    2. 套用設定檔。

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/yaml" \
"https://iap.googleapis.com/v1/projects/cb-managed-ingress-demo/iap_web/forwarding_rule-us-central1/services/psc-fr:iapSettings?update_mask=iapSettings.accessSettings.oauthSettings.oauthClientId,iapSettings.accessSettings.oauthSettings.oauthClientSecret" \
-d @iap-oauth.json

如要測試網頁應用程式是否受到 OAuth 用戶端的 IAP 保護，請參閱「測試存取權」。

資源上自訂 OAuth 用戶端的舊版設定

以下各節說明如何使用舊版方法，在 IAP 中為特定資源類型設定自訂 OAuth 用戶端。如果您使用本文稍早所述的方法，可以略過這個部分。

App Engine

本節說明如何在 App Engine 上啟用自訂 OAuth 用戶端。

gcloud

您需要最新版的 gcloud CLI，才能設定專案與 IAP。如需如何安裝 gcloud CLI 的操作說明，請參閱「安裝 gcloud CLI」。

  1. 如要進行驗證，請使用 Google Cloud CLI 執行下列指令。 
    gcloud auth login
  2. 如要登入，請前往顯示的網址。
  3. 登入之後，複製顯示的驗證碼並貼到指令列中。
  4. 執行下列指令，指定要使用 IAP 保護資源的專案。 
    gcloud config set project PROJECT_ID
  5. 請按照「為 IAP 建立 OAuth 用戶端」一文中的操作說明，設定 OAuth 同意畫面並建立 OAuth 用戶端。
  6. 儲存 OAuth 用戶端 ID 和密鑰。
  7. 如要啟用 IAP，請執行下列指令。 
    gcloud iap web enable \
    --oauth2-client-id=CLIENT_ID \
    --oauth2-client-secret=CLIENT_SECRET \
    --resource-type=app-engine

啟用 IAP 之後，您可以使用 gcloud CLI，以 IAM 角色 roles/iap.httpsResourceAccessor 修改 IAP 存取權政策。進一步瞭解如何管理角色與權限。

API

  1. 按照「為 IAP 建立 OAuth 用戶端」一文中的指示，設定 OAuth 同意畫面並建立 OAuth 用戶端。

  2. 儲存 OAuth 用戶端 ID 和密鑰。

  3. 執行下列指令，準備 settings.json 檔案。 

    cat << EOF > settings.json
{
"iap":
  {
    "enabled": true,
    "oauth2ClientId": "CLIENT_ID",
    "oauth2ClientSecret":" CLIENT_SECRET"
  }
}
EOF

  4. 執行下列指令來啟用 IAP。 

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d @settings.json \
"https://appengine.googleapis.com/v1/apps/PROJECT_ID?updateMask=iap"

啟用 IAP 後，您可以使用 Google Cloud CLI，透過 IAM 角色 roles/iap.httpsResourceAccessor 修改 IAP 存取權政策。進一步瞭解如何管理角色與權限。

GKE

本節說明如何在 GKE 上啟用自訂 OAuth 用戶端。

設定 BackendConfig

如果您執行的是 GKE 叢集 1.24 以上版本，可以使用 Kubernetes Gateway API 設定 IAP 和 GKE。如需操作說明，請參閱「設定 IAP」一節。

  1. 按照「為 IAP 建立 OAuth 用戶端」一文中的指示，設定 OAuth 同意畫面並建立 OAuth 用戶端。

  2. 建立 Kubernetes Secret，包裝 OAuth 用戶端。

    kubectl create secret generic MY_SECRET --from-literal=client_id=CLIENT_ID \
  --from-literal=client_secret=CLIENT_SECRET
    更改下列內容：

    • MY_SECRET：要建立的 Secret 名稱
    • CLIENT_ID：OAuth 用戶端 ID
    • CLIENT_SECRET：OAuth 用戶端密鑰

    您應該會收到確認訊息，例如下列輸出內容，表示密鑰已成功建立： 

    secret "MY_SECRET" created

  3. 將 OAuth 憑證新增至 BackendConfig。 

    apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: CONFIG_DEFAULT
  namespace: my-namespace
spec:
iap:
  enabled: true
  oauthclientCredentials:
    secretName: MY_SECRET

  4. 將 Service 通訊埠與 BackendConfig 建立關聯，即可啟用 IAP。請參閱「將 BackendConfig 與 Ingress 建立關聯」。如要建立關聯，其中一個方法是將服務的所有通訊埠預設為 BackendConfig，方法是將下列註解新增至 Service 資源：

    metadata:
  annotations:
      beta.cloud.google.com/backend-config: '{"default": "CONFIG_DEFAULT"}}'

啟用 IAP 之後，您可以使用 gcloud CLI，以 IAM 角色 roles/iap.httpsResourceAccessor 修改 IAP 存取權政策。進一步瞭解如何管理角色與權限。

疑難排解

若您參照的 secretName 不存在或結構不正確，將顯示下列錯誤訊息之一：

  • BackendConfig default/config-default is not valid: error retrieving secret "foo": secrets "foo" not found. 如要解決這個錯誤，請確認您已如步驟 2 所述，正確建立 Kubernetes Secret。

  • BackendConfig default/config-default is not valid: secret "foo" missing client_secret data. 如要解決這個錯誤，請確認您已正確建立 OAuth 憑證。此外，請確認您已參照正確的 client_id 和 client_secret 金鑰。

負載平衡器後端服務

如果您使用 Compute Engine 和 Cloud Run，本節將說明如何在 IAP 中為負載平衡器後端服務設定 OAuth 用戶端。

gcloud

您需要最新版的 gcloud CLI，才能設定專案與 IAP。如需如何安裝 gcloud CLI 的操作說明，請參閱「安裝 gcloud CLI」。

  1. 如要進行驗證，請使用 Google Cloud CLI 執行下列指令。 
    gcloud auth login
  2. 如要登入，請前往顯示的網址。
  3. 登入之後，複製顯示的驗證碼並貼到指令列中。
  4. 執行下列指令，指定要使用 IAP 保護資源的專案。 
    gcloud config set project PROJECT_ID
  5. 按照「為 IAP 建立 OAuth 用戶端」一文中的指示，設定 OAuth 同意畫面並建立 OAuth 用戶端。
  6. 儲存 OAuth 用戶端 ID 和密鑰。
  7. 如要啟用 IAP，請執行全域或區域範圍的指令。

    全球範圍 
    gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --global \
    --iap=enabled,oauth2-client-id=CLIENT_ID,oauth2-client-secret=CLIENT_SECRET
     區域範圍 
    gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --region REGION_NAME \
    --iap=enabled,oauth2-client-id=CLIENT_ID,oauth2-client-secret=CLIENT_SECRET

啟用 IAP 之後，您可以使用 gcloud CLI，以 IAM 角色 roles/iap.httpsResourceAccessor 修改 IAP 存取權政策。進一步瞭解如何管理角色與權限。

API

  1. 按照「為 IAP 建立 OAuth 用戶端」一文中的指示，設定 OAuth 同意畫面並建立 OAuth 用戶端。

  2. 儲存 OAuth 用戶端 ID 和密鑰。

  3. 執行下列指令，準備 settings.json 檔案。 

    cat << EOF > settings.json
{
"iap":
  {
    "enabled": true,
    "oauth2ClientId": "CLIENT_ID",
    "oauth2ClientSecret": "CLIENT_SECRET"
  }
}
EOF

  4. 執行下列指令來啟用 IAP。 

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d @settings.json \
"https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/REGION/backendServices/BACKEND_SERVICE_NAME"

啟用 IAP 之後，您可以使用 gcloud CLI，以 IAM 角色 roles/iap.httpsResourceAccessor 修改 IAP 存取權政策。進一步瞭解如何管理角色與權限。

測試存取權

設定自訂 OAuth 用戶端後，您可以執行下列操作，測試 IAP 是否使用該用戶端保護服務：

  1. 在「IAP」頁面的「應用程式」分頁中，查看 IAP 管理的應用程式。

  2. 存取其中一個應用程式的網址。如果您是自設定同意畫面後首次存取應用程式，系統會顯示您先前設定的同意畫面。