How to share OAuth clients

This page explains how to share an OAuth client with another app within your organization.

Overview

Sharing OAuth clients between projects removes the need to manually create a new OAuth client for every app under your organization. After manually creating one OAuth client, you can programmatically assign it to multiple apps.

OAuth client sharing is also used to share an OAuth client with agents that you want to be able to enable Identity-Aware Proxy (IAP) but not have access to the Credentials page.

OAuth client sharing is also used when the application is using a Google-managed OAuth client for the browser flow and you want to enable programmatic access to the application.

Before you begin

Create a new OAuth client by completing the steps in OAuth client creation or you can use an existing OAuth client.

Programmatic access

This section describes the steps to enable an OAuth client for programmatic access to your application.

  1. Allowlist OAuth clients for programmatic access.

    You can allowlist a list of OAuth client IDs which are owned by your organization and you want to provide programmatic access the application.

    You can allowlist the OAuth clients on resources and services at the organization, project, and folder level.

    gcloud

    1. Run the following command to prepare a SETTING_FILE file. Update the values as needed.

        cat << EOF > SETTING_FILE
    access_settings:
      oauth_settings:
        programmatic_clients: ["clientId1", "clientId2", ..]
  EOF

    2. Use gcloud iap settings set command to allowlist OAuth clients at a desired level.

      gcloud iap settings set SETTING_FILE [--organization=ORGANIZATION --folder=FOLDER --project=/PROJECT --resource-type=RESOURCE_TYPE --service=SERVICE --version=VERSION

      Example commands:

      To allowlist OAuth client IDs on the resources within an organization, run the following command. 

        gcloud iap settings set SETTING_FILE --organization=ORGANIZATION

      To allowlist OAuth client IDs on the resources within a folder, run the following command. 

        gcloud iap settings set SETTING_FILE --folder=FOLDER

      To allowlist OAuth client IDs on all web type resources within a project, run the following command. 

        gcloud iap settings set SETTING_FILE --project=PROJECT --resource-type=iap_web

      To allowlist OAuth client IDs on an App Engine service within a project, run the following command. 

        gcloud iap settings set SETTING_FILE --project=PROJECT --resource-type=app-engine --service=SERVICE

      Replace the following:

      • FOLDER: The folder ID.
      • ORGANIZATION: The organization ID.
      • PROJECT: The project ID.
      • RESOURCE_TYPE: The IAP resource type. Must be app-engine, iap_web, compute, organization, or folder.
      • SERVICE: The service name. This is optional when resource-type is compute or app-engine.
      • VERSION: The version name. This is not applicable for compute, and is optional when resource-type is app-engine.

    API

    1. Run the following command to prepare an iap_settings.json file. Update the values as needed.

      cat << EOF > iap_settings.json
{
  "access_settings": {
      "oauth_settings": {
          programmatic_clients: ["clientId1", "clientId2", ..]
        }
    }
}
EOF

    2. Get the resource name by running the gcloud iap settings get command. Copy the name field from the output.
      You will need the name in the following step.

      gcloud iap settings get [--organization=ORGANIZATION --folder=FOLDER --project=PROJECT --resource-type=RESOURCE_TYPE --service=SERVICE --version=VERSION]

    3. Replace RESOURCE_NAME in the following command with the name from the previous step. The IapSettings will be updated.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d @iap_settings.json \
"https://iap.googleapis.com/v1/RESOURCE_NAME:iapSettings?updateMask=iapSettings.accessSettings.oauthSettings.programmaticClients"

  2. Sign in to the application using any one of the allowlisted OAuth client IDs. See Programmatic authentication.

Browser access

To enable IAP to use your client ID and secret by using the Google Cloud console, complete the following following instructions.

Risks

While sharing a client between your apps is convenient, there are risks. This section outlines potential risks when sharing clients and how to mitigate them.

Single point of failure

Using one OAuth client for many apps creates a single point of failure. If a client is deleted or modified incorrectly, every app that uses that client is impacted.

To mitigate this, only share clients when fulfilling an important use case for shared clients.

Client secret leaks

Sharing a client requires sharing your client secret with people and scripts. This increases the risk of your client secret leaking. IAP can't differentiate between tokens created from your app and tokens created from a leaked client secret.

Access to your IAP resources can be monitored with Cloud Audit Logging. If you believe there's a chance that your client secret leaked, reset it from the Credentials page.

To mitigate this risk, protect client secrets like a password. Limit sharing them and never store them as plaintext.

Impersonation of authorized users

If your client secret is leaked, a malicious app can set the IAP authentication browser cookie on its domain to impersonate an authorized user. With this cookie, IAP authenticates the impersonated user for all apps that share the leaked client secret.

To mitigate this risk, avoid sharing clients between resources that also share authorized users. Set per-resource permissions to ensure that even if an impersonated user is authenticated, IAP won't authorize access.

User identity collection

If your client secret is leaked, a malicious app can use your client ID to collect the identities of your app's users. This is triggered when your users visit the malicious app.

When a user accesses an IAP-protected app for the first time, they're asked to share their identity with the app. This gives users control over their personal information. When a user consents to share their identity, the Google login system records that consent. IAP won't re-prompt the user on subsequent requests from any client ID in the same project.

Any user who has consented to share their identity with your app, and who visits the malicious app, will immediately have their identity shared without their consent.