# How to Create an OAuth App for Google Workspace Follow the steps below to create an OAuth 2.0 Client ID for your application. _Apideck does not provide shared Google credentials for this connector: the shared application was retired on 11 May 2023. Every application owner registers their own Google Cloud OAuth client, which is what this guide covers._ ## Step 1: Prerequisites Before you begin, make sure you have the following: 1. A Google account 2. An Apideck account 3. A Google Workspace organisation whose directory you can connect. The test calls at the end of this guide read users out of a Workspace directory, so a plain Google account with no Workspace domain behind it has nothing to return. ## Step 2: Go to the Google Cloud console Go to the [Google Cloud console](https://console.cloud.google.com/). ## Step 3: Create a New Project - Click on the project drop-down and select `New Project`. - Give your project a name and click `Create`. ## Step 4: Enable the Google Workspace APIs You Need - In the sidebar, click on `Library`. - Search for `Admin SDK API` and click `Enable`. This is the API behind the Directory endpoints this connector calls. ## Step 5: Create Credentials - Click on `Credentials` in the sidebar. - Click `Create Credentials` and select `OAuth client ID`. ## Step 6: Configure the OAuth Consent Screen - You'll be prompted to configure the `OAuth Consent Screen` before creating the credentials. - The first thing it asks for is the user type, and that answer decides whether Google reviews your application at all, so settle it before you save: - `Internal` keeps the application inside your own Google Workspace organisation. It is exempt from verification entirely, so pick it when the only directory you will ever connect is your own. - `External` lets any organisation connect, which is what you want if you are shipping this integration to customers. It is the route that goes through Google's verification. - Select the user type you need. The rest of this guide follows the `External` route. - Fill in the required details like `App name`, `User support email`, etc. - In the `Scopes` section, add the scopes that your application needs. - https://www.googleapis.com/auth/admin.directory.group.member (View and manage group members on your domain) - https://www.googleapis.com/auth/admin.directory.group.member.readonly (View group subscriptions on your domain) - https://www.googleapis.com/auth/admin.directory.group (View and manage the provisioning of groups on your domain) - https://www.googleapis.com/auth/admin.directory.group.readonly (View groups on your domain) - https://www.googleapis.com/auth/admin.directory.orgunit (View and manage organization units on your domain) - https://www.googleapis.com/auth/admin.directory.orgunit.readonly (View organization units on your domain) - https://www.googleapis.com/auth/admin.directory.user (View and manage the provisioning of users on your domain) - https://www.googleapis.com/auth/admin.directory.user.readonly (View users on your domain) - https://www.googleapis.com/auth/admin.directory.user.alias (View and manage user aliases on your domain) - https://www.googleapis.com/auth/admin.directory.user.alias.readonly (View user aliases on your domain) - https://www.googleapis.com/auth/admin.directory.user.security (View and manage security settings on your domain) - https://www.googleapis.com/auth/cloud-platform (View and manage your data across Google Cloud Platform services) - Click `Save and Continue`. ### Google App Verification Process Details Publishing an `External` application that asks for sensitive scopes, which the Admin SDK Directory scopes above are, puts you in Google's verification queue. Google's [sensitive scope verification documentation](https://developers.google.com/identity/protocols/oauth2/production-readiness/sensitive-scope-verification) covers the detail; the sequence below is what you work through. 1. **Complete your OAuth consent screen**: Ensure all required fields are filled in (app name, support email, developer contact information, privacy policy URL, etc.) 2. **Add appropriate scopes**: For Google Workspace, add the necessary scopes mentioned above 3. **Gather what the submission has to contain**: have all of the following ready before you submit, because Google reviews them together - Valid privacy policy URL that properly describes data collection and usage - A homepage or landing page for your application - Demonstration of legitimate use case for requested scopes - Screenshots or video of your application's OAuth implementation flow 4. **Submit for verification**: click the "Submit for verification" button on the OAuth consent screen page 5. **During the review**: Google corresponds with the developer contact address on the consent screen. That thread is where to ask Google's review team about the state of your submission and the timeline you can plan around. > **What to plan for while you wait.** An unverified application gets you 100 Google accounts through the consent screen in total, and you reach that cap either way: leaving the publishing status at `Testing` does not protect it, since Testing allows at most 100 allowlisted test users, and publishing without completing verification applies the same hard cap of 100 total users. > > Until the review completes, Google also shows everyone you send through the flow a screen warning that your application is not verified, with an `Advanced` link to continue past it. Tell your customers to expect it, so it does not read to them as a security problem with your integration. > > Staying on `Testing` costs you something extra. Google discards the refresh tokens it issues in that state after seven days, so anyone you connect there drops out inside a week and has to sign in again. It reads like a broken integration, but it is the publishing status doing exactly what it is documented to do, and moving the application out of `Testing` is what ends it. > > If you need one customer running properly before your review finishes, ask their Google Workspace administrator to mark your application as Trusted for their organisation. That clears both the 100-account cap and the seven-day expiry for everyone in that organisation, which is how you run a real pilot mid-verification. ## Step 7: Create OAuth Client ID - Choose the application type. If you're creating a Web application, select `Web application`. - Name your OAuth 2.0 client. - Under `Authorized redirect URIs`, click `Add URI` and enter the Apideck Vault callback exactly as written: ``` https://unify.apideck.com/vault/callback ``` - Click `Create`. - Copy the client ID and client secret. You need both in step 9. Google rejects an authorisation attempt from any URI that is not on this list with a `redirect_uri_mismatch` error, and a change to the list [can take a few minutes to a few hours](https://support.google.com/cloud/answer/15549257) to take effect. ## Step 8: Optional: Serve the callback from your own subdomain You can serve the Apideck Vault authorisation flow from a subdomain of your own instead of Apideck's. This is optional whitelabelling: Google's verification does not require a vendor-specific domain, so skip this step if you are happy with the standard callback from step 7. **💡 IMPORTANT**: Once you have applied one of the options, don't forget to update the `Authorized redirect URIs` in your Google Cloud console credentials as described in step 7. ### Setup a custom subdomain for Apideck Vault Add a custom domain name for Apideck Vault. This will allow you to whitelabel the reference to Apideck's Vault. 1. Create a CNAME record Sign in to your DNS name server host and navigate to your DNS settings. Add a CNAME record with the value `cname.vercel-dns.com`. ``` [REPLACE_WITH_DESIRED_SUBDOMAIN] CNAME cname.vercel-dns.com. ``` 2. Contact Apideck Get in touch with your Apideck contact or [Apideck Support](https://help.apideck.com/en/articles/7774658) to let us know about the custom domain you want to use, so we can configure and enable it for Apideck Vault. 3. Wait for the changes to propagate Congratulations! You have now pointed your custom domain to Apideck Vault! When DNS changes are made, you can expect a propagation time up to 24 hours (but mostly much less than that). This is because it takes time for the DNS to take effect across the internet. The actual time of propagation may vary in some locations based on your network setup. 4. Update the "Redirect URI" Update the `Authorized redirect URIs` on your OAuth client as described in step 7, so that the callback runs on your custom domain. 5. Save your changes and submit your consent screen for verification. ## Step 9: Configure your Client ID and Secret in Apideck Now that you've set up your OAuth app, you can configure the Google Workspace connector in Apideck using the client ID and secret generated earlier. Open the [Google Workspace connector settings in the Apideck Dashboard](https://platform.apideck.com/configuration/hris/google-workspace), enable **Use your own client credentials**, paste in the client ID and client secret from step 7, and save. ## Do your first API call to the Google Workspace API via our [HRIS API](https://developers.apideck.com/apis/hris) - Connect your Google Workspace account through [Vault](https://platform.apideck.com/vault) with a test session. - To test the access token, make a query to get [`Employees`](https://developers.apideck.com/apis/hris/reference#operation/employeesAll). ``` curl --location --request GET 'https://unify.apideck.com/hris/employees' \ --header 'x-apideck-consumer-id: test-consumer' \ --header 'x-apideck-app-id: {APIDECK_APP_ID}' \ --header 'x-apideck-service-id: google-workspace' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {APIDECK_API_KEY}' ``` ## Do your first API call to the Google Workspace API via our [Proxy API](https://developers.apideck.com/apis/proxy/reference) - Connect your Google Workspace account through [Vault](https://platform.apideck.com/vault) with a test session. - To test the access token, make a call to the [`List users`](https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer) endpoint using the [Proxy API](https://developers.apideck.com/apis/proxy/reference). ``` curl --location --request GET 'https://unify.apideck.com/proxy' \ --header 'x-apideck-consumer-id: test-consumer' \ --header 'x-apideck-app-id: {APIDECK_APP_ID}' \ --header 'x-apideck-service-id: google-workspace' \ --header 'x-apideck-downstream-url: https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {APIDECK_API_KEY}' ``` ## Start building with the Google Workspace API Learn what else you can [build with the Google Workspace API](https://developers.google.com/admin-sdk/directory/reference/rest). Interested in a personalized demo? [Let us know](https://www.apideck.com/demo-request?from=guide).