自訂 OAuth 設定以啟用 IAP

本文說明何時以及如何自訂 Identity-Aware Proxy (IAP) 的 OAuth 設定。

IAP 會使用 Google 代管的 OAuth 用戶端驗證使用者。

Google 代管的 OAuth 用戶端會限制使用者存取權，當使用者透過瀏覽器存取啟用 IAP 的應用程式時，只能由同一機構的使用者存取。

使用自訂 OAuth 設定的時機

您必須使用自訂 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 代管的 OAuth 用戶端啟用 IAP 時，可以忽略 OAuth 用戶端警告。

使用自訂 OAuth 用戶端設定啟用 IAP

以下各節說明如何針對不同資源使用自訂 OAuth 用戶端設定啟用 IAP。

App Engine

控制台

動態包含檔案

如果您尚未設定專案的 OAuth 同意畫面，系統會提示您進行設定。如要設定 OAuth 同意畫面，請參閱「設定 OAuth 同意畫面」。

設定 IAP 存取權

  1. 前往「Identity-Aware Proxy」頁面。
    前往「Identity-Aware Proxy」頁面
  2. 選取要使用 IAP 保護的專案。
  3. 找出您要授予存取權的資源，然後勾選旁邊的核取方塊。
  4. 在右側面板中，按一下「Add principal」(新增管理員)。
  5. 在隨即顯示的「Add principals」(新增主體) 對話方塊中，輸入群組或個別使用者的電子郵件地址，這些群組或個別使用者應擁有專案的「IAP-Secured Web App User」(受 IAP 保護的網路應用程式使用者) 角色。

    以下類型的主體可以擁有這個角色：

    • Google 帳戶：user@gmail.com
    • Google 群組：admins@googlegroups.com
    • 服務帳戶：server@example。gserviceaccount.com
    • Google Workspace 網域：example.com

    請務必新增您可以存取的 Google 帳戶。

  6. 從「Roles」(角色) 下拉式清單中選取「Cloud IAP」>「IAP-secured Web App User」(受 IAP 保護的網路應用程式使用者)。
  7. 按一下「Save」(儲存)。

正在啟用 IAP

  1. 在「Identity-Aware Proxy」頁面的「APPLICATIONS」下方，尋找您要限制存取權的應用程式。如要為資源啟用 IAP，請在「IAP」欄中
  2. 在隨即顯示的「Turn on IAP」(開啟 IAP) 視窗中，按一下「Turn On」(開啟)，確認您要使用 IAP 保護資源。啟用 IAP 後，系統會要求您提供負載平衡器所有連線的登入憑證。只有在專案中擁有「IAP-Secured Web App User」角色的帳戶才能取得存取權。

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 存取權政策。進一步瞭解如何管理角色和權限。

Compute Engine

控制台

如果您尚未設定專案的 OAuth 同意畫面，系統會提示您進行設定。如要設定 OAuth 同意畫面，請參閱「設定 OAuth 同意畫面」。

如果您執行的是 GKE 叢集 1.24 以上版本，可以使用 Kubernetes Gateway API 設定 IAP 和 GKE。如要這樣做，請完成下列步驟，然後按照「設定應用程式內購功能」中的操作說明進行。請勿設定 BackendConfig。

設定 IAP 存取權

  1. 前往「Identity-Aware Proxy」頁面。
    前往「Identity-Aware Proxy」頁面
  2. 選取要使用 IAP 保護的專案。

  3. 找出您要授予存取權的資源，然後勾選旁邊的核取方塊。

    如果您沒有看到任何資源，請確認資源已建立，且 BackendConfig Compute Engine ingress 控制器已同步。

    如要確認後端服務可用，請執行下列 gcloud 指令：

    gcloud compute backend-services list
  4. 在右側面板中，按一下「Add principal」。
  5. 在隨即顯示的「Add principals」(新增主體) 對話方塊中，輸入群組或個別使用者的電子郵件地址，這些群組或個別使用者應擁有專案的「IAP-Secured Web App User」(受 IAP 保護的網路應用程式使用者) 角色。

    以下類型的主體可以擁有這個角色：

    • Google 帳戶：user@gmail.com
    • Google 群組：admins@googlegroups.com
    • 服務帳戶：server@example。gserviceaccount.com
    • Google Workspace 網域：example.com

    請務必新增您可以存取的 Google 帳戶。

  6. 從「Roles」(角色) 下拉式清單中選取「Cloud IAP」>「IAP-secured Web App User」(受 IAP 保護的網路應用程式使用者)。
  7. 按一下「Save」(儲存)。

正在啟用 IAP

  1. 在「Identity-Aware Proxy」頁面的「APPLICATIONS」下方，找出您要限制存取權的 instance group 所服務的負載平衡器。如要為資源啟用 IAP，請在「IAP」欄中
    如要啟用 IAP：
    • 負載平衡器前端設定中至少一個通訊協定必須為 HTTPS。瞭解如何設定負載平衡器。
    • 您需要具備 compute.backendServices.update、clientauthconfig.clients.create 和 clientauthconfig.clients.getWithSecret 權限。這些權限係由諸如專案編輯者角色等角色來授予。詳情請參閱「管理受 IAP 保護資源的存取權」。
  2. 在隨即顯示的「Turn on IAP」(開啟 IAP) 視窗中，按一下「Turn On」(開啟)，確認您要使用 IAP 保護資源。啟用 IAP 後，系統會要求您提供負載平衡器所有連線的登入憑證。只有在專案中擁有「IAP-Secured Web App User」角色的帳戶才能取得存取權。

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 存取權政策。進一步瞭解如何管理角色和權限。

Cloud Run

控制台

如果您尚未設定專案的 OAuth 同意畫面，系統會提示您進行設定。如要設定 OAuth 同意畫面，請參閱「設定 OAuth 同意畫面」一文。

設定 IAP 存取權

  1. 開啟「Identity-Aware Proxy」頁面。
    前往 Identity-Aware Proxy
  2. 選取要使用 IAP 保護的專案。
  3. 在「應用程式」下方，選取要新增成員的負載平衡器後端服務旁的核取方塊。
  4. 在右側面板中，按一下「Add member」(新增成員)。

  5. 在「Add members」(新增成員) 對話方塊中，輸入群組或個別使用者的帳戶，這些群組或個別使用者應擁有專案的「IAP-secured Web App User」(受 IAP 保護的網路應用程式使用者) 角色。成員可為以下類型的帳戶：

    • Google 帳戶：user@gmail.com - 這也可以是 Google Workspace 帳戶，例如 user@google.com 或其他 Google Workspace 網域。
    • Google 群組：admins@googlegroups.com
    • 服務帳戶：server@example.gserviceaccount.com
    • Google Workspace 網域：example.com

  6. 從「Roles」清單中選取「Cloud IAP」>「IAP-secured Web App User」。

  7. 按一下 [儲存]。

正在啟用 IAP

  1. 在 IAP 頁面的「Applications」下方，找出您要限制存取權的負載平衡器後端服務。按一下「IAP」切換按鈕，為資源啟用 IAP。
  2. 在隨即顯示的「Turn on IAP」(開啟 IAP) 視窗中，按一下「Turn On」(開啟)，確認您要使用 IAP 保護資源。啟用 IAP 後，系統會要求您提供負載平衡器所有連線的登入憑證。只有在專案中擁有「IAP-Secured Web App User」角色的帳戶才能取得存取權。

  3. 如要授權 IAP 將流量傳送至後端 Cloud Run 服務，請按照「將主體新增至服務」中的指示，新增下列主體和角色。

    • Principal：service-[PROJECT-NUMBER]@gcp-sa-iap.iam.gserviceaccount.com
    • 角色：Cloud Run 叫用者

gcloud

  1. 請按照「為 IAP 建立 OAuth 用戶端」一文中的指示設定 OAuth 同意畫面，並建立 OAuth 用戶端。
  2. 儲存 OAuth 用戶端 ID 和密碼。
  3. 如果您尚未建立服務帳戶，請執行下列指令。如果您先前已建立服務帳戶，執行這項指令不會建立重複的服務帳戶。
    gcloud beta services identity create \
    --service=iap.googleapis.com --project=PROJECT_ID
  4. 執行下列指令，為先前步驟建立的服務帳戶授予叫用者權限。
    gcloud run services add-iam-policy-binding SERVICE-NAME \
    --member='serviceAccount:service-PROJECT-NUMBER@gcp-sa-iap.iam.gserviceaccount.com' \
    --role='roles/run.invoker'

  5. 視負載平衡器後端服務是全球性或地區性而定，執行全域或區域範圍的指令來啟用 IAP。使用上一個步驟中的 OAuth 用戶端 ID 和密鑰。

    全域範圍

    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
    取代下列內容：

    • BACKEND_SERVICE_NAME：後端服務名稱。
    • CLIENT_ID：上一個步驟中的 OAuth 用戶端 ID。
    • CLIENT_SECRET：上一個步驟的 OAuth 用戶端密鑰。
    • REGION_NAME：您要啟用 IAP 的地區。

啟用 IAP 後，您可以使用 Google Cloud CLI，以身分與存取權管理角色 roles/iap.httpsResourceAccessor 修改 IAP 存取權政策。詳情請參閱「管理角色和權限」。

Google Kubernetes Engine

控制台

如果您尚未設定專案的 OAuth 同意畫面，系統會提示您進行設定。如要設定 OAuth 同意畫面，請參閱「設定 OAuth 同意畫面」。

如果您執行的是 GKE 叢集 1.24 以上版本，可以使用 Kubernetes Gateway API 設定 IAP 和 GKE。如要這樣做，請完成下列步驟，然後按照「設定應用程式內購功能」中的操作說明進行。請勿設定 BackendConfig。

設定 IAP 存取權

  1. 前往「Identity-Aware Proxy」頁面。
    前往「Identity-Aware Proxy」頁面
  2. 選取要使用 IAP 保護的專案。

  3. 找出您要授予存取權的資源，然後勾選旁邊的核取方塊。

    如果您沒有看到任何資源，請確認資源已建立，且 BackendConfig Compute Engine ingress 控制器已同步。

    如要確認後端服務可用，請執行下列 gcloud 指令：

    gcloud compute backend-services list
  4. 在右側面板中，按一下「Add principal」。
  5. 在隨即顯示的「Add principals」(新增主體) 對話方塊中，輸入群組或個別使用者的電子郵件地址，這些群組或個別使用者應擁有專案的「IAP-Secured Web App User」(受 IAP 保護的網路應用程式使用者) 角色。

    以下類型的主體可以擁有這個角色：

    • Google 帳戶：user@gmail.com
    • Google 群組：admins@googlegroups.com
    • 服務帳戶：server@example。gserviceaccount.com
    • Google Workspace 網域：example.com

    請務必新增您可以存取的 Google 帳戶。

  6. 從「Roles」(角色) 下拉式清單中選取「Cloud IAP」>「IAP-secured Web App User」(受 IAP 保護的網路應用程式使用者)。
  7. 按一下「Save」(儲存)。

正在啟用 IAP

  1. 在「Identity-Aware Proxy」頁面的「APPLICATIONS」下方，找出您要限制存取權的 instance group 所服務的負載平衡器。如要為資源啟用 IAP，請在「IAP」欄中
    如要啟用 IAP：
    • 負載平衡器前端設定中至少一個通訊協定必須為 HTTPS。瞭解如何設定負載平衡器。
    • 您需要具備 compute.backendServices.update、clientauthconfig.clients.create 和 clientauthconfig.clients.getWithSecret 權限。這些權限係由諸如專案編輯者角色等角色來授予。詳情請參閱「管理受 IAP 保護資源的存取權」。
  2. 在隨即顯示的「Turn on IAP」(開啟 IAP) 視窗中，按一下「Turn On」(開啟)，確認您要使用 IAP 保護資源。啟用 IAP 後，系統會要求您提供負載平衡器所有連線的登入憑證。只有在專案中擁有「IAP-Secured Web App User」角色的帳戶才能取得存取權。

GKE

Configure the BackendConfig

If you are running GKE clusters version 1.24 or later, you can configure IAP and GKE by using the Kubernetes Gateway API. See Configure IAP for instructions.

  1. Follow the instructions in Creating OAuth clients for IAP to configure the OAuth consent screen and create the OAuth client.

  2. Create a Kubernetes Secret to wrap the OAuth client. 

    kubectl create secret generic MY_SECRET --from-literal=client_id=CLIENT_ID \
  --from-literal=client_secret=CLIENT_SECRET
    Replace the following:

    • MY_SECRET: The name of the secret to create
    • CLIENT_ID: The OAuth client ID
    • CLIENT_SECRET: The OAuth client secret

    You should receive confirmation, like the following output, that the Secret was successfully created: 

    secret "MY_SECRET" created

  3. Add the OAuth credentials to the BackendConfig. 

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

  4. Enable IAP by associating Service ports with your BackendConfig. See Associating BackendConfig with your Ingress. One way to make this association is to make all ports for the service default to your BackendConfig, which you can do by adding the following annotation to your Service resource: 

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

After you enable IAP, you can use the gcloud CLI to modify the IAP access policy using the IAM role roles/iap.httpsResourceAccessor. Learn more about managing roles and permissions.

Troubleshooting

If the secretName you referenced doesn't exist or isn't structured properly, one of the following error messages will display:

  • BackendConfig default/config-default is not valid: error retrieving secret "foo": secrets "foo" not found. To resolve this error, make sure that you've created the Kubernetes Secret correctly as described in step 2.

  • BackendConfig default/config-default is not valid: secret "foo" missing client_secret data. To resolve this error, make sure that you've created the OAuth credentials correctly. Also, make sure that you referenced the correct client_id and client_secret keys.