搭配 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

Before you set up your project and IAP, you need an up-to-date version of gcloud CLI. For instructions on how to install the gcloud CLI, see Install the gcloud CLI.

  1. To authenticate, use the Google Cloud CLI and run the following command. 
    gcloud auth login
  2. To sign in, follow the URL that appears.
  3. After you sign in, copy the verification code that appears and paste it in the command line.
  4. Run the following command to specify the project that contains the resource that you want to protect with IAP. 
    gcloud config set project PROJECT_ID
  5. Follow the instructions in Creating OAuth clients for IAP to configure the OAuth consent screen and create the OAuth client.
  6. Save the OAuth client ID and secret.
  7. To enable IAP, run the following command. 
    gcloud iap web enable \
    --oauth2-client-id=CLIENT_ID \
    --oauth2-client-secret=CLIENT_SECRET \
    --resource-type=app-engine

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.

API

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

  2. Save the OAuth client ID and secret.

  3. Run the following command to prepare a settings.json file. 

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

  4. Run the following command to enable 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"

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

GKE

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

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.

負載平衡器後端服務

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

gcloud

Before you set up your project and IAP, you need an up-to-date version of the gcloud CLI. For instructions on how to install the gcloud CLI, see Install the gcloud CLI.

  1. To authenticate, use the Google Cloud CLI and run the following command. 
    gcloud auth login
  2. To sign in, follow the URL that appears.
  3. After you sign in, copy the verification code that appears and paste it in the command line.
  4. Run the following command to specify the project that contains the resource that you want to protect with IAP. 
    gcloud config set project PROJECT_ID
  5. Follow the instructions in Creating OAuth clients for IAP. to configure the OAuth consent screen and create the OAuth client.
  6. Save the OAuth client ID and secret.
  7. To enable IAP, run either the globally or regionally scoped command.

    Global scope 
    gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --global \
    --iap=enabled,oauth2-client-id=CLIENT_ID,oauth2-client-secret=CLIENT_SECRET
     Regional scope 
    gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --region REGION_NAME \
    --iap=enabled,oauth2-client-id=CLIENT_ID,oauth2-client-secret=CLIENT_SECRET

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.

API

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

  2. Save the OAuth client ID and secret.

  3. Run the following command to prepare a settings.json file. 

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

  4. Run the following command to enable 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"

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.

測試存取權

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

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

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