Docs: External Connection via WordPress.com Application

README.md

@@ -16,7 +16,8 @@ _Note:_ The latest stable version of the plugin is the _stable_ branch. [Downloa
 * [Requirements](#requirements)
 * [Installation](#installation)
   * [Registration](#registration)
-  * [Setup External Connections](#setup-external-connections-using-application-passwords)
+  * [Setup External Connection with Application Passwords](#setup-external-connections-using-application-passwords)
+  * [Setup External Connection with WordPress.com](#)
 * [How to Distribute Content](#how-to-distribute-content)
   * [Pushing Content](#pushing-content)
   * [Pulling Content](#pulling-content)
@@ -72,13 +73,30 @@ To help inform our roadmap, keep adopters apprised of major updates and changes
 
 ### Setup External Connections using Application Passwords
 
+If you want tp distribute content within a WordPress multisite network, then you do not need to do anything further as Distributor will detect all sites in the network and display those as options when Pushing or Pulling content.  If you want to distribute content between separate WordPress instances, then you will need to create an External Connection.  In most cases of setting up an External Connection you will utilize the Application Passwords process that's part of WordPress core since version 5.6.
+
 1. Ensure that the current version of Distributor is active on BOTH sites being connected.  We'll refer to these as mainsite.com and remotesite.com.
 1. On mainsite.com, navigate to `Distributor` > `External Connections` and click `Add New`.
 1. Enter a label for the connection (e.g., `remotesite.com`), select `Username / Password` for the `Authentication Method`, and a username from remotesite.com.
 1. On remotesite.com, ensure that [Application Passwords](https://wordpress.org/plugins/application-passwords/) is installed. (_Note: Using this plugin instead of a normal WordPress users password helps limit the use of your primary password and will allow you to revoke access to Distributor in the future if needed._) Then navigate to the user profile that will be used to create the External Connection on mainsite.com and then to the `Application Passwords` section of the user profile (not the `Account Management` section).  Add a label for the New Application Password Name (e.g., `mainsite.com`) and click `Add New`.  Now copy the password provided into mainsite.com's External Connections `Password` field.
 1. On mainsite.com, add the `External Connection URL` (e.g., http://remotesite.com/wp-json).  You should see a green circle and "_Connection established._".
 1. Ensure the roles selected in `Roles Allowed to Push` are the ones you want to support, then press the `Create Connection` button.  You should now be able to push from mainsite.com to remotesite.com.  If you want to pull from remotesite.com to mainsite.com, simply repeat these instructions swapping mainsite.com and remotesite.com.
 
+### Setup External Connections using WordPress.com Application
+
+Distributor enables connecting to websites hosted on the WordPress.com platform including [WordPress VIP](https://wpvip.com/) (Classic) via [OAuth2](https://developer.wordpress.com/docs/oauth2/).
+
+#### Creating a WordPress.com application
+1. Visit the [WordPress.com application manager](https://developer.wordpress.com/apps/) and click the `Create New Application` button.
+1. Name your application. In the "Redirect URLs" field enter your WP Admin's post.php URL (e.g., `https://mydomain.com/wp-admin/post.php`).
+1. Once created, note the application's `Client ID` and `Client Secret` values.
+
+#### OAuth2 Authentication Flow
+1. Add a new External Connection giving the connection a name and select "WordPress.com Application" from the Authentication Method dropdown and click the "Start Setup" button.
+1. Enter the `Client ID` and `Client Secrets` from your WordPress.com application and click the 'Authorize Connection with WordPress.com' button.
+1. On the WordPress.com OAuth2 page, click the 'Approve' button to authorize the connection.
+1. Enter the External Connection URL for the WordPress.com site to connect to and click the `Update Connection` button to save.
+
 ## How to Distribute Content
 
 There are two methods for distributing content between multiple WordPress sites, Push and Pull.  Pushing allows you to share content from your site to one or more connected sites while Pulling allows you to bring content into your site from one of your connected sites.  In either method, once content has been distributed it will stay in sync with any changes made to the origin post (when Pushing the origin is the site being Pushed from, when Pulling the origin is the site being Pulled from).