Add more detailed steps to nest integration instructions (#16047)

Co-authored-by: Franck Nijhof <git@frenck.dev>

source/_integrations/nest.markdown

@@ -66,16 +66,37 @@ For the first phase, you will turn on the API and create the necessary credentia
 1. Now the "Device Access Console" should be visible. Click on **Create project**.
     ![Screenshot of creating a project](/images/integrations/nest/create_project.png)
 
-1. Give your project a name and click **Next**.
+1. Give your Device Access project a name and click **Next**.
     ![Screenshot of naming a project](/images/integrations/nest/project_name.png)
 
-1. Next you will be asked for an *OAuth client ID*. It is a good idea to go create that now. Open a new tab to the [Google Cloud Console](https://console.developers.google.com/apis/credentials) **Credentials** page and click **Create
-Credentials**.
+1. Next you will be asked for an *OAuth client ID*. It is a good idea to go create that now. Open a new tab to the [Google API Console](https://console.developers.google.com/apis/credentials).
+
+1. If this is your first time here, you likely need to create a new Google API project. Click **Create Project** then **New
+Project**. Note: This is a different type of project from the Device Access project you are also creating.
+    ![Screenshot of APIs and Services Cloud Console with no existing project](/images/integrations/nest/api_project_needed.png)
+
+1. Give your API Project a name then click **Create**. Note: You can ignore the *Project ID* here as Home Assistant does not need it.
+
+1. Click *OAuth consent screen* and make sure you have that configured, otherwise, you can do that now.
+    ![Screenshot of OAuth consent screen creation](/images/integrations/nest/oauth_consent_create.png)
+
+1. Select **External** (the only choice if you are not a G-Suite user) then click **Create**.  While you are here, you may click the *Let us know what you think* to give Google's OAuth team any feedback about your experience configuring credentials for self-hosted software. They make regular improvements to this flow and appear to value feedback.
+
+1. The *App Information* screen needs you to enter an **App name** and **User support email**, then enter your email again under **Developer contact email**. These are only shown while you later go through the OAuth flow to authorize Home Assistant to access your account. Click **Save and Continue**.
+
+1. On the *Scopes* step click **Save and Continue**.
+
+1. On the *Test Users* step, you need to add your Google Account (e.g., your @gmail.com address) to the list. Click *Save* on your test account then **Save and Continue** to finish the consent flow.
+    ![Screenshot of OAuth consent screen test users](/images/integrations/nest/oauth_consent_test_users.png)
+
+1. Navigate to the **Credentials** page and click **Create Credentials**.
     ![Screenshot of APIs and Services Cloud Console](/images/integrations/nest/create_credentials.png)
 
 1. From the drop-down list select *OAuth client ID*.
     ![Screenshot of OAuth client ID selection](/images/integrations/nest/oauth_client_id.png)
 
+1. Enter *Web Application* for the Application typex, since you will use this with Home Assistant.
+
 1. Pick a name for your credential.
 
 1. Add **Authorized redirect URIs** for your Home Assistant URL, including the OAuth callback path e.g., `https://<your_home_assistant_url>:<port>/auth/external/callback`. See [Troubleshooting](#troubleshooting) below for more details on the subtle requirements for what kinds of URLs work here.
@@ -92,8 +113,6 @@ Credentials**.
 
 1. Take note of the *Project ID* as you will need it later. At this point you have the `project_id`, `client_id` and `client_secret` configuration options needed for Home Assistant.
 
-1. At this point you should have a `Project ID`, `OAuth Client ID`, and an `OAuth Secret`.
-
 1. Go back to the [Google Cloud Console: API & Services](https://console.developers.google.com/apis/dashboard)
 
 1. Click on **Enable APIs and Services**
@@ -162,15 +181,21 @@ subscriber_id:
 
 Once your developer account is set up and you have a valid `nest` entry in `configuration.yaml`, you need to connect devices with the following steps:
 
-1. From the Home Assistant front-end, navigate to **Configuration** then *Integrations**. Under **Set up a new integration** locate 'Nest'.
+1. From the Home Assistant front-end, navigate to **Configuration** then **Integrations**. Click **Add Integration** then locate 'Nest'.
 
 1. You should get redirected to Google to choose an account. This should be the same developer account you configured above.
 
-1. The *Google Nest permissions* screen will allow you to choose which devices to configure. You can leave out any device that you do not wish to use with Home Assistant.
+1. The *Google Nest permissions* screen will allow you to choose which devices to configure. You likely want to enable
+everything, however, you can leave out any feature you do not wish to use with Home Assistant.
+
     ![Screenshot of Nest permissions authorization](/images/integrations/nest/oauth_approve.png)
 
 1. You will get redirected back to another account selection page. See [Troubleshooting](#troubleshooting) below if you get a `redirect_uri_mismatch` error.
 
+1. You may see a warning screen that says *Google hasn't verified this app* since you just set up an un-verified developer workflow. Click *Advanced* then *Go to your domain (unsafe)* to proceed.
+
+    ![Screenshot OAuth warning](/images/integrations/nest/oauth_app_verification.png)
+
 1. Then you will be asked to grant access to additional permissions. Click *Allow*.
     ![Screenshot 1 of granting permissions](/images/integrations/nest/oauth_grant1.png)
     ![Screenshot 2 of granting permissions](/images/integrations/nest/oauth_grant2.png)
@@ -186,15 +211,28 @@ Once your developer account is set up and you have a valid `nest` entry in `conf
 
 - For general trouble with the SDM API OAuth authorization flow with Google, see [Troubleshooting](https://developers.google.com/nest/device-access/authorize#troubleshooting).
 
-- *Error 400: Invalid Request* This error typically happens when there is a mismatch between how you are accessing Home Assistant and the Authorized Redirect URI you entered for OAuth. If you used a publicly facing URL, make sure that you are accessing Home Assistant with the same URL when you set up the integration. You will definitely hit this error if you are accessing Home Assistant by local IP during the initial setup.
+- *Error 400: redirect_uri_mismatch* means that your OAuth Client ID is not configured to match your Home Assistant URL.
 
-- *Error 500: redirect_uri_mismatch* means that you need to visit the [GCP credentials](https://console.developers.google.com/apis/credentials) page and modify your OAuth2.0 Client ID to add the correct Home Assistant callback URL. The error message tells you the exact URL that needs to be added, including any ports or paths like `/auth/external/callback` path. See [Redirect URI mismatch](https://developers.google.com/nest/device-access/authorize#redirect_uri_mismatch) for more details.
+    - To resolve this, copy and paste the redirect URI in the error message (`https://<your_home_assistant_url>:<port>/auth/external/callback`).
+
+      ![Screenshot of success](/images/integrations/nest/redirect_uri_mismatch.png)
+
+    - Go back to the [API Console](https://console.developers.google.com/apis/credentials) and select your *OAuth 2.0 Client ID*.
+    - Add the URL to the list of *Authorized redirect URIs* and click **Save** and start the flow over.
+
+      ![Screenshot of success](/images/integrations/nest/redirect_uris_fix.png)
+
+- When configuring the OAuth Client ID redirect URI, you may see an error such as *must end with a public top-level
+  domain (such as .com or .org)* or *must use a valid domain that is a valid top private domain*. This means that you
+  may need to change the URL you use to access Home Assistant in order to access your devices.
 
     - A convienent solution is to use [Nabu Casa](https://www.nabucasa.com/)
     - There are subtle rules for what types of URLs are allowed, namely that they must use a publicly known hostname, though your Home Assistant ports do not need to be exposed to the internet.
     - You can use any publicly known hostname you own
     - As a hack, you can use hosts tricks to temporarily assign a public hostname to your Home Assistant IP address.
 
+- *Error 403: access_denied* means that you need to visit the [OAuth Consent Screen](https://console.developers.google.com/apis/credentials/consent) and add your Google Account as a *Test User*.
+
 - *Error: invalid_client no application name* means the [OAuth Consent Screen](https://console.developers.google.com/apis/credentials/consent) has not been fully configured for the project. Enter the required fields (App Name, Support Email, Developer Email) and leave everything else as default.
 
 - *No devices or entities are created* if the SDM API is not returning any devices for the authorized account. Double-check that GCP is configured correctly to [Enable the API](https://developers.google.com/nest/device-access/get-started#set_up_google_cloud_platform) and authorize at least one device in the OAuth setup flow. If you have trouble here, then you may want to walk through the Google instructions and issue commands directly against the API until you successfully get back the devices.