API_keys: Adding api_keys.md
Moving
https://sites.google.com/a/chromium.org/dev/developers/how-tos/api-keys
closer to source.
BUG=1203173
Change-Id: I98f23d421cb11903db0d386b98660e2ab5f3e33f
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2880798
Commit-Queue: Ben Henry <benhenry@chromium.org>
Reviewed-by: Mihai Sardarescu <msarda@chromium.org>
Cr-Commit-Position: refs/heads/master@{#881002}
diff --git a/docs/README.md b/docs/README.md
index 72b2af24..68e2f0ad 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -157,6 +157,9 @@
you are interested in.
* [Shutdown](shutdown.md) - Explains the steps of Chrome shutdown, to make it
easier to determine where to add a new shutdown operation.
+* [API Keys](api_keys.md) - When you need access to Google APIs for a custom
+ build, fork, integration of stock Chromium, or are building ChromiumOS (for
+ login).
### Testing
* [Running and Debugging Web Tests](testing/web_tests.md)
diff --git a/docs/api_keys.md b/docs/api_keys.md
new file mode 100644
index 0000000..6ed917f
--- /dev/null
+++ b/docs/api_keys.md
@@ -0,0 +1,164 @@
+# API Keys
+
+When using a custom build, fork, or integration of Chromium, or if you're
+building ChromiumOS, you will need access to Google API for key functionality.
+
+[TOC]
+
+*** note
+**Note:** Software distribution with keys acquired for yourself is allowed, but
+the keys themselves cannot be shared with parties outside the legal entity that
+accepted the API ToS. Keep in mind that a number of the APIs will have no or
+very limited quota and not all of the APIs have additional quota available for
+purchase.
+***
+
+**Googlers only:**
+
+* For a simpler approach to API keys, see https://go/chrome-api-key-setup
+* If you need a new API enabled in Chrome, use https://b/new?component=165132
+
+**How-to:**
+First, acquire API keys. Then, specify the API keys to use either when you build
+Chromium, or at runtime using environment variables.
+
+## Acquiring Keys
+
+1. Make sure you are a member of chromium-dev@chromium.org (you can choose
+ not to receive mail).
+ *** note
+ **Note:** the APIs below are only visible to people subscribed to that group.
+ ***
+1. Make sure you are logged in with the Google account associated with the email
+ address that you used to subscribe to chromium-dev.
+1. Go to https://cloud.google.com/console
+1. _optional_ You may add other members of your organization or team on the Team
+ tab.
+1. Open the **APIs and Services > Library** from the hamburger menu, search for
+ all of the following APIs. For each of these APIs:
+ 1. Click on it
+ 1. Click `Enable API` button at the top
+ 1. Read and agree to the Terms of Service
+ 1. Check the `I have read and agree to the <API name> Terms of Service`
+ checkbox
+ 1. Click Accept.
+
+ **List of APIs** (if any are not shown, recheck step 1 above):
+
+ * Cloud Search API
+ * Geolocation API (requires [enabling
+ billing](https://developers.google.com/console/help/#EnableBilling) but
+ is free to use; you can skip this one, in which case geolocation features
+ of Chrome will not work)
+ * Google Drive API (enable this for Files.app on Chrome OS and
+ SyncFileSystem API)
+ * Safe Browsing API
+ * Time Zone API
+ * Optional
+ * Admin SDK
+ * Cloud Translation API
+ * Geocoding API
+ * Google Assistant API
+ * Google Calendar API
+ * Nearby Messages API
+
+1. Go to the **Credentials** sub tab under the **API & Services** section in the
+ hamburger menu.
+1. Click the `Create credentials` button then click on the **OAuth client
+ ID** item in the drop-down list.
+ * Click on the `Configure consent screen` button. Fill in the "product
+ name" (anything you choose) and other details, then click on `Save`.
+ * Return to the Credentials tab and click the `Add credentials` button
+ again, then select "OAuth 2.0 client ID" from the drop-down list.
+ * In the "Application type" section check the **Other** option and give it a
+ name in the "Name" text box, then click `Create`.
+1. In the pop-up window that appears, you'll see a **client ID** and a **Client
+ secret** string. Copy and paste those in a text file on your dev box then
+ click `OK` to dismiss. A new item should now appear in the **OAuth 2.0 client
+ IDs** list. You can click on the name of your client ID to retrieve the ID and
+ secret at any time. In the next few sections, these values will be referred
+ to as the **Client ID** and **Client secret** fields.
+1. Click the `Create credentials` button _again_ on the same page.
+ * In the pop-over window that shows up, click the `API key` button.
+ * A pop-over should show up giving you the API key. Copy/paste in to a text
+ file to save, although you will be able to access this as well.
+ * Click `OK` to dismiss.
+
+You should now have an API key and an OAuth 2.0 client ID in the **Credentials**
+tab. The next sections will refer to the value as the "API key".
+
+*** note
+**Note:** Your keys are not for distribution, and should not be shared with
+others.
+***
+
+## Providing Keys at Build time
+
+If you are building Chromium yourself, you can provide keys as part of your
+build configuration, that way they are always baked into your binary.
+
+Specify three variables in your `args.gn` file (edit by running `gn args
+out/your_out_dir_here`)
+
+```bash
+google_api_key = "your_api_key"
+google_default_client_id = "your_client_id"
+google_default_client_secret = "your_client_secret"
+```
+
+## Providing Keys at Runtime
+
+If you prefer, you can build a Chromium binary (or use a pre-built Chromium
+binary) without API keys baked in, and instead provide them at runtime. To do
+so, set the environment variables `GOOGLE_API_KEY`, `GOOGLE_DEFAULT_CLIENT_ID`
+and `GOOGLE_DEFAULT_CLIENT_SECRET` to your "API key", "Client ID" and "Client
+secret" values respectively.
+
+On Chromium OS to specify the keys as environment variables append them to the
+end of `/etc/chrome_dev.conf`:
+
+```bash
+GOOGLE_API_KEY=your_api_key
+GOOGLE_DEFAULT_CLIENT_ID=your_client_id
+GOOGLE_DEFAULT_CLIENT_SECRET=your_client_secret
+```
+
+## Signing in to Chromium is restricted
+
+Signing in to Chromium requires an OAuth 2.0 token for authentication. As this
+OAuth 2.0 token gives access to various Google services that handle user data
+(e.g. Chrome sync), for security and privacy reasons the generation of this
+OAuth 2.0 token is restricted. This means that signing in to Chromium is
+restricted (as the OAuth 2.0 token cannot be generated). In order to sign in to
+Chromium builds, please add your test account to
+google-browser-signin-testaccounts@chromium.org (accounts in this group are
+allowed to get access tokens bypassing the restriction above).
+
+*** note
+**Note:** Starting with Chromium M69, when the browser is set up with an OAuth
+2.0 client ID and client secret, signing in with your Google Account to any
+Google web property will also attempt to sign you in to Chromium (which will
+fail as explained above). To avoid such errors, remove your OAuth 2.0 client
+ID and client secret from your build to stop generating tokens when users sign
+in to Google web properties (remove `google_default_client_id`,
+`google_default_client_secret` from gn args and `GOOGLE_DEFAULT_CLIENT_ID`
+and `GOOGLE_DEFAULT_CLIENT_SECRET` from your environment settings).
+***
+
+## Getting Keys for Your Chromium Derivative
+
+Many of the Google APIs used by Chrome are specific to Google and not intended
+for use in derived products. In the [API Console](http://developers.google.com/console)
+you may be able to purchase additional quota for some of the APIs listed above.
+**For APIs that do not have a "Pricing" link, additional quota is not available
+for purchase.**
+
+## Polyfilling chrome.identity API in Your Chromium Derivative
+
+The default Chromium `chrome.identity.getAuthToken` API that extensions may
+call to obtain auth tokens will fail outside of Google Chrome as the
+implementation uses restricted APIs.
+
+A prototype CL for Chromium embedders might use to replace the implementation
+with one not dependent upon private APIs can be found attached to
+[this post](https://groups.google.com/a/chromium.org/g/embedder-dev/c/tGCJ3QNVzYE).
