Update extension OAuth docs with ability to redirect to the extension with query params (#16391)

Signed-off-by: Guillaume Tardif <guillaume.tardif@gmail.com>

Signed-off-by: Guillaume Tardif <guillaume.tardif@gmail.com>

desktop/extensions-sdk/guides/oauth2-flow.md

@@ -14,7 +14,7 @@ Learn how you can let users authenticate from your Docker Extension using OAuth
 
 In OAuth 2.0, the term "grant type" refers to the way an application gets an access token. Although OAuth 2.0 defines several grant types, this page only describes how to authorize users from your Docker Extension using the Authorization Code grant type.
 
-## Authorization Code grant flow
+## Authorization code grant flow
 
 The Authorization Code grant type is used by confidential and public clients to exchange an authorization code for an access token.
 
@@ -23,6 +23,7 @@ After the user returns to the client via the redirect URL, the application gets
 ![Flow for OAuth 2.0](images/oauth2-flow.png){: style=width:80% }
 
 The image above shows that:
+
 - The Docker Extension asks the user to authorize access to their data.
 - If the user grants access, the Docker Extension then requests an access token from the service provider, passing the access grant from the user and authentication details to identify the client.
 - The service provider then validates these details and returns an access token.
@@ -33,9 +34,9 @@ The image above shows that:
 - Auth URL: The endpoint for the API provider authorization server, to retrieve the auth code.
 - Redirect URI: The client application callback URL to redirect to after auth. This must be registered with the API provider.
 
-Once the user enters the username and password, they are successfully authenticated.
+Once the user enters the username and password, they're successfully authenticated.
 
-## Step One: Open a browser page to authenticate the user
+## Open a browser page to authenticate the user
 
 From the extension UI, you can provide a button that, when selected, opens a new window in a browser to authenticate the user.
 
@@ -46,46 +47,29 @@ example:
 window.ddClient.openExternal("https://authorization-server.com/authorize?
   response_type=code
   &client_id=T70hJ3ls5VTYG8ylX3CZsfIu
-  &redirect_uri=${REDIRECT_URI}
+  &redirect_uri=${REDIRECT_URI});
-  &scope=photo+offline_access
-  &state=kH_0FdAtjCfYjOkF);
 ```
 
-## Step Two: Get the authorization code and access token
+## Get the authorization code and access token
 
-### From the extension UI
+You can get the authorization code from the extension UI by listing `docker-desktop://dashboard/extension-tab?extensionId=awesome/my-extension` as the `redirect_uri` in the OAuth app you're using and concatenating the authorization code as a query parameter. The extension UI code will then be able to read the corresponding code query-param.
 
-> **Passing the access token**
+> Note
->
+> using this feature requires the extension SDK 0.3.2 in Docker Desktop. You need to ensure that the required SDK version for your extension set with `com.docker.desktop.extension.api.version` in [image labels](../extensions/labels.md) is higher than 0.3.2.
-> Currently, passing the authorization code as a query parameter to the `docker-desktop://dashboard/open` URL is not supported.
 {: .important}
 
-You cannot get the authorization code from the extension UI by listing `docker-desktop://dashboard/open` as the `redirect_uri` in the OAuth app you're using and concatenating the authorization code as a query parameter.
-
-See [from backend service](#from-a-backend-service) instead.
-
-### From a backend service
-
-You need a backend service running as part of your extension to handle the OAuth 2.0 flow. For this, you must ensure the Redirect URI is registered with the API provider to redirect to that location after OAuth has completed, e.g. `http://localhost:8080/callback`.
-
-The default communication is socket-based. The backend service needs to expose the port in order for the browser to connect to it.
-
 #### Authorization
 
-This step is where the user enters their credentials in the browser. After the authorization is complete, the user is redirected back to your backend service, and you'll consume the authorization code that is part of the query parameters in the URL.
+This step is where the user enters their credentials in the browser. After the authorization is complete, the user is redirected back to your extension user interface, and the extension UI code can consume the authorization code that's part of the query parameters in the URL.
-
-How you consume the query parameters depends on the technology that is used by the backend service.
 
 #### Exchange the Authorization Code
 
 Next, you exchange the authorization code for an access token.
 
-The backend service must build a `POST` request to the token endpoint with the following parameters:
+The extension must send a `POST` request to the oauth authorization server with the following parameters:
 
 ```
 POST https://authorization-server.com/token
-
-grant_type=authorization_code
 &client_id=T70hJ3ls5VTYG8ylX3CZsfIu
 &client_secret=YABbyHQShPeO1T3NDQZP8q5m3Jpb_UPNmIzqhLDCScSnRyVG
 &redirect_uri=${REDIRECT_URI}
@@ -94,7 +78,7 @@ grant_type=authorization_code
 
 > **Note**
 >
-> The client's credentials are included in the `POST` body in this example. Other authorization servers may require that the credentials are sent as a HTTP Basic Authentication header.
+> The client's credentials are included in the `POST` query params in this example. OAuth authorization servers may require that the credentials are sent as a HTTP Basic Authentication header or might support different formats. See your OAuth provider docs for details.
 
 #### Token Endpoint Response
 
@@ -102,7 +86,6 @@ Finally, you can read the access token from the HTTP response and pass it to the
 
 ## Step three: Store the access token
 
-
 The Docker Extensions SDK doesn't currently provide a specific mechanism to store secrets.
 
 It's highly recommended that you use an external source of storage to store the access token.