This guide shows you how to manage OAuth-based application integrations with Google Cloud.
At a high level, to integrate an OAuth-based application, you do the following:
- Create an OAuth client.
- Create an OAuth client credential.
- In the OAuth client credential, obtain the client secret. To learn about risks associated with storing and accessing the client secret and strategies that can help mitigate them, see OAuth client and credential security risks and mitigations.
After you have completed these steps, the OAuth-based application can access Google Cloud products and data.
Before you begin
You must have a Google Cloud organization set up.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
You must have set up a workforce identity pool and provider in the organization in which you will register the OAuth application. Learn how to set up workforce identity federation for Microsoft Entra ID, Okta, and other OIDC and SAML 2.0 providers.
Required roles
To get the permissions that you need to register an OAuth application for your organization,
ask your administrator to grant you the
IAM OAuth Client Admin (roles/iam.oauthClientAdmin
) IAM role on the project.
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Manage OAuth clients
This section shows you how to manage OAuth clients.
Create an OAuth client
To create an OAuth client, do the following:
gcloud
gcloud iam oauth-clients create APP_OAUTH_CLIENT_ID \
--project=PROJECT_ID \
--location=global \
--client-type="CONFIDENTIAL_CLIENT" \
--display-name="My OAuth application" \
--description="An application registration for MyApp" \
--allowed-scopes="https://www.googleapis.com/auth/cloud-platform" \
--allowed-redirect-uris="REDIRECT_URI" \
--allowed-grant-types="authorization_code_grant"
Replace the following:
APP_OAUTH_CLIENT_ID
: a client ID to represent this OAuth client.PROJECT_ID
: the ID of the project where you created your workforce identity pool and provider. The project must be created in the organization where your workforce pool and provider were created.REDIRECT_URI
: the redirect URI for the OAuth application—for example,https://myapp.com/signin-callback
.
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
-d "{ \
'allowedGrantTypes': ['AUTHORIZATION_CODE_GRANT'], \
'allowedRedirectUris': ['REDIRECT_URI'], \
'allowedScopes': ['https://www.googleapis.com/auth/cloud-platform'], \
'clientType': 'CONFIDENTIAL_CLIENT', \
'description': 'My OAuth client description', \
'disabled': false, \
'displayName': 'My OAuth client'}" \
https://iam.googleapis.com/v1/projects/PROJECT_ID/locations/global/oauthClients\?oauthClientId\=APP_OAUTH_CLIENT_ID
Replace the following:
PROJECT_ID
: the ID of the project where you created your workforce identity pool and provider. The project must be created in the organization where your workforce pool and provider were created.REDIRECT_URI
: the redirect URI for the OAuth application—for example,https://myapp.com/signin-callback
.APP_OAUTH_CLIENT_ID
: a client ID to represent this OAuth client.
After you register the application, you create the OAuth client credential and obtain the secret that the OAuth application uses to access Google Cloud.
List OAuth clients
To list registered OAuth clients, run the following command:
gcloud
gcloud iam oauth-clients list \
--project=PROJECT_ID \
--location=global
REST
curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
https://iam.googleapis.com/v1/projects/PROJECT_ID/locations/global/oauthClients
Replace PROJECT_ID
with the ID of the project where
your OAuth applications are registered.
Describe an OAuth client
To describe an OAuth client, run the following command:
gcloud
gcloud iam oauth-clients describe APP_OAUTH_CLIENT_ID \
--project PROJECT_ID \
--location global
Replace the following:
APP_OAUTH_CLIENT_ID
: the ID of the OAuth client that you want to to describePROJECT_ID
: the ID of the project where you registered your OAuth application
REST
curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
https://iam.googleapis.com/v1/projects/PROJECT_ID/locations/global/oauthClients/APP_OAUTH_CLIENT_ID
Replace the following:
PROJECT_ID
: the ID of the project where you registered your OAuth applicationAPP_OAUTH_CLIENT_ID
: the ID of the OAuth client that you want to to describe
Update an OAuth client
To update an OAuth client, run the following command.
gcloud
gcloud iam oauth-clients update APP_OAUTH_CLIENT_ID \
--project=PROJECT_ID \
--location=global \
--allowed-redirect-uris="REDIRECT_URI"
Replace the following:
APP_OAUTH_CLIENT_ID
: the OAuth client ID for the OAuth client that you want to updatePROJECT_ID
: the ID of the project where you registered your OAuth applicationREDIRECT_URI
: the redirect URI for the OAuth application
To update other fields, use flags listed in gcloud iam oauth-clients update
.
REST
curl -d'{"allowedRedirectUris":"REDIRECT_URI"}' \
-H "Content-Type: application/json" -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
https://iam.googleapis.com/v1/projects/PROJECT_ID/locations/global/oauthClients/APP_OAUTH_CLIENT_ID?update_mask=allowed_redirect_uris
Replace the following:
PROJECT_ID
: the ID of the project where you registered your OAuth applicationAPP_OAUTH_CLIENT_ID
: the OAuth client ID for the OAuth client that you want to updateREDIRECT_URI
: the redirect URI for the OAuth client
To update other fields, set update_mask
to the field names listed in
gcloud iam oauth-clients update
.
Delete an OAuth client
To delete an OAuth client, run the following command:
gcloud
gcloud iam oauth-clients delete APP_OAUTH_CLIENT_ID \
--project PROJECT_ID \
--location global
Replace the following:
APP_OAUTH_CLIENT_ID
: the OAuth client ID to deletePROJECT_ID
: the ID of the project where you registered your OAuth application
REST
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
https://iam.googleapis.com/v1/projects/PROJECT_ID/locations/global/oauthClients/APP_OAUTH_CLIENT_ID
Replace the following:
PROJECT_ID
: the ID of the project where you registered your OAuth applicationAPP_OAUTH_CLIENT_ID
: the OAuth client ID to delete
Manage OAuth client credentials
This section shows you how to manage OAuth client credentials for the OAuth client.
Create an OAuth client credential
To create an OAuth client credential, run the following command:
gcloud
gcloud iam oauth-clients credentials create APP_OAUTH_CLIENT_CREDENTIAL_ID \
--oauth-client=APP_OAUTH_CLIENT_ID \
--display-name='My OAuth client credential' \
--location='global'
Replace the following:
APP_OAUTH_CLIENT_CREDENTIAL_ID
: an ID that represents this client credentialAPP_OAUTH_CLIENT_ID
: the OAuth client ID you can obtain by describing the registered OAuth client application
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
-d "{'disabled': false, 'displayName': 'My OAuth client credential'}" \
https://iam.googleapis.com/v1/projects/PROJECT_ID/locations/global/oauthClients/APP_OAUTH_CLIENT_ID/credentials\?oauthClientCredentialId=APP_OAUTH_CLIENT_CREDENTIAL_ID
Replace the following:
PROJECT_ID
: the ID of the project where you registered your OAuth applicationAPP_OAUTH_CLIENT_ID
: the OAuth client ID you can obtain by describing the registered OAuth client applicationAPP_OAUTH_CLIENT_CREDENTIAL_ID
: an ID that represents this client credential
List OAuth client credentials
To list OAuth client credentials, run the following command:
gcloud
gcloud iam oauth-clients credentials list \
--oauth-client=APP_OAUTH_CLIENT_ID \
--project=PROJECT_ID \
--location=global
Replace the following:
APP_OAUTH_CLIENT_ID
: the OAuth client ID for which to list credentialsPROJECT_ID
: the ID of the project where you registered your OAuth application
REST
curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
https://iam.googleapis.com/v1/projects/$PROJECT_ID/locations/global/oauthClients/APP_OAUTH_CLIENT_ID/credentials
Replace the following:
PROJECT_ID
: the ID of the project where you registered your OAuth applicationAPP_OAUTH_CLIENT_ID
: the OAuth client ID for which to list credentials
Describe an OAuth client credential
To describe an OAuth client credential, run the following command. You can obtain the client secret by inspecting the output.
gcloud
gcloud iam oauth-clients credentials describe APP_OAUTH_CLIENT_CREDENTIAL_ID \
--oauth-client=APP_OAUTH_CLIENT_ID \
--location='global'
Replace the following:
APP_OAUTH_CLIENT_CREDENTIAL_ID
: the redirect URI for the OAuth clientAPP_OAUTH_CLIENT_ID
: the OAuth client ID you can obtain by describing the client application registration
REST
curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
https://iam.googleapis.com/v1/projects/PROJECT_ID/locations/global/oauthClients/APP_OAUTH_CLIENT_ID/credentials/APP_OAUTH_CLIENT_CREDENTIAL_ID
Replace the following:
PROJECT_ID
: the ID of the project where you registered your OAuth applicationAPP_OAUTH_CLIENT_CREDENTIAL_ID
: the redirect URI for the OAuth clientAPP_OAUTH_CLIENT_ID
: the OAuth client ID you can obtain by describing the client application registration
In the output, clientSecret
is the client secret. This is the secret that the
OAuth application uses to access Google Cloud.
Update an OAuth client credential
To update an OAuth client credential, run the following command:
gcloud
gcloud iam oauth-clients credentials update APP_OAUTH_CLIENT_CREDENTIAL_ID \
--client-id=APP_OAUTH_CLIENT_ID \
--display-name="My new credential name" \
--location=global
REST
curl -d'{"displayName":"My new credential name"}' -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
https://staging-iam.sandbox.googleapis.com/v1/projects/PROJECT_ID/locations/global/oauthClients/APP_OAUTH_CLIENT_ID/credentials/APP_OAUTH_CLIENT_CREDENTIAL_ID?update_mask=display_name
Replace the following:
PROJECT_ID
: the ID of the project where you registered your OAuth applicationAPP_OAUTH_CLIENT_CREDENTIAL_ID
: the redirect URI for the OAuth clientAPP_OAUTH_CLIENT_ID
: the OAuth client ID that you can obtain by describing the client application registration
Disable an OAuth client credential
Before you can delete an OAuth client credential, you must disable it. To disable the OAuth client credential, run the following command:
gcloud
gcloud iam oauth-clients credentials update APP_OAUTH_CLIENT_CREDENTIAL_ID \
--oauth-client=APP_OAUTH_CLIENT_ID \
--disabled \
--project=PROJECT_ID \
--location=global
Replace the following:
PROJECT_ID
: the ID of the project where you registered your OAuth applicationAPP_OAUTH_CLIENT_ID
: the OAuth client IDAPP_OAUTH_CLIENT_CREDENTIAL_ID
: the client credential ID to disable
REST
curl -d'{"disabled":"true"}' \
-H "Content-Type: application/json" -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
https://iam.googleapis.com/v1/projects/PROJECT_ID/locations/global/oauthClients/APP_OAUTH_CLIENT_ID/credentials/APP_OAUTH_CLIENT_CREDENTIAL_ID?update_mask=disabled
Replace the following:
PROJECT_ID
: the ID of the project where you registered your OAuth applicationAPP_OAUTH_CLIENT_ID
: the OAuth client IDAPP_OAUTH_CLIENT_CREDENTIAL_ID
: the client credential ID to disable
Delete an OAuth client credential
To delete an OAuth client credential, run the following command:
gcloud
gcloud iam oauth-clients credentials delete APP_OAUTH_CLIENT_CREDENTIAL_ID \
--project=PROJECT_ID \
--oauth-client=APP_OAUTH_CLIENT_ID \
--location=global
Replace the following:
APP_OAUTH_CLIENT_CREDENTIAL_ID
: the OAuth client IDPROJECT_ID
: the ID of the project where you registered your OAuth applicationAPP_OAUTH_CLIENT_ID
: the client credential ID
REST
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
https://iam.googleapis.com/v1/projects/PROJECT_ID/locations/global/oauthClients/APP_OAUTH_CLIENT_ID/credentials/APP_OAUTH_CLIENT_CREDENTIAL_ID
Replace the following:
PROJECT_ID
: the ID of the project where you registered your OAuth applicationAPP_OAUTH_CLIENT_ID
: the client credential IDAPP_OAUTH_CLIENT_CREDENTIAL_ID
: the OAuth client ID