documentation, work in progress

ReadMe.md

@@ -6,4 +6,4 @@ This security plug-in is written as a replacement for the Mozilla Persona plugin
 
 *To allow an orderly migration of wiki site ownership this plug-in makes use of the Mozilla Persona plug-in for Passport. This is only presented as a login option on those wiki sites that have already been claimed using Mozilla Persona. See, [migrating from Mozilla Persona](./persona_migration.md)*
 
-In this initial release we make use of Passport's OAuth plug-ins for GitHub, Google, and Twitter. To use one, or more, of these a wiki server administrator will need to register an application with an identity provider from that list, and configure the wiki server. See, [configuring wiki-security-passportjs](./configuration.md).
+In this initial release we make use of Passport's OAuth plug-ins for GitHub, Google, and Twitter. To use one, or more, of these a wiki server administrator will need to register an application with an identity provider from that list, and configure the wiki server. See, [configuring wiki-security-passportjs](./docs/configuration.md).

configuration.md

@@ -1,54 +0,0 @@
-# Federated Wiki - Security Plug-in: Passport (Configuration)
-
-It is recommended that this plug-in is configured using a configuration file, rather than via the command line.
-
-Configuration of Passport security plug-ins is a two stage process:
-
-1. Registering an application with the identity provider, and
-2. Configuration of the wiki software using information returned in step 1.
-
-The legacy Mozilla Persona Passport plug-in does not require any configuration.
-
-This plug-in comes with support for using GitHub, Google, and Twitter. Although the configuration process is broadly the same for each of these, there are some slight differences.
-
-As a wiki server owner you need to pick one, or more, of these that you want to use.
-
-## GitHub
-
-GitHub's OAuth integration only allows us to specify a single callback URL. This means that if you are running a wiki farm with multiple DNS roots, you will need to configure a separate application with GitHub for each wiki domain.
-
-### Register an application with GitHub
-You must register an application with GitHub, a new application can be created at [developer applications](https://github.com/settings/applications/new) within GitHub's settings panel. The fields needed are, `Application name`, `Homepage URL`, `Application description`, and `Authorization callback URL`. The first three will appear on the GitHub login page you get when you log into wiki, though the description is optional. The callback URL must be set to `http://example.wiki/auth/github/callback`, or if you have enabled https `https://example.wiki/auth/github/callback`, replacing `example.wiki` with the root domain for your wiki.
-
-Your application will be issues a `client ID` and `client secret` which we will use in step 2 to configure wiki.
-
-### Configure Wiki
-
-The wiki is configured by adding the `client ID` and `client secret` to the wiki domain part of the configuration.
-
-```JSON
-{
-  "farm": true,
-  "security_type": "passportjs",
-  "wikiDomains": {
-    "example.wiki": {
-      "github_clientID": "CLIENT ID",
-      "github_clientSecret": "CLIENT SECRET"
-    }
-  }
-}
-```
-
-## Google
-
-### Step 1
-
-
-### Step 2
-
-
-## Twitter
-
-### Step 1
-
-### Step 2

docs/config-github.md

@@ -0,0 +1,50 @@
+## GitHub
+
+GitHub's OAuth integration only allows us to specify a single callback URL. This means that if you are running a wiki farm with multiple DNS roots, you will need to configure a separate application with GitHub for each wiki domain.
+
+### Register an application with GitHub
+
+* Log into GitHub
+* Visit the Developer applications tab under OAuth applications in your Personal settings.
+* Click [Register New Application](https://github.com/settings/applications/new). The *new OAuth application* configuration screen is displayed:
+
+![GitHub New OAuth Application](./images/github-new-app.png)
+
+#### Set Application name
+
+* Enter a name related to your wiki server.
+
+#### Set Homepage URL
+
+* Enter the URL of a page that describes your wiki server.
+
+#### Set Authorization callback URL
+
+* Enter `https://example.wiki/auth/github/callback`, replacing `example.wiki` with your wiki server root domain.
+
+Note: If you are not ready to use HTTPS yet, you can use `http://example.wiki/auth/github/callback`
+
+Save your settings by clicking **Register application**. The new application's settings are shown:
+
+![GitHub Application Summary](./images/github-app-summary.png)
+
+This screen also allows you to adjust any settings, and add an logo.
+
+* Record the `Client ID` and `Client Secret` for use in configuring the wiki server.
+
+### Configure Wiki
+
+The wiki is configured by adding the `client ID` and `client secret` to the wiki domain part of the configuration.
+
+```JSON
+{
+  "farm": true,
+  "security_type": "passportjs",
+  "wikiDomains": {
+    "example.wiki": {
+      "github_clientID": "CLIENT ID",
+      "github_clientSecret": "CLIENT SECRET"
+    }
+  }
+}
+```

docs/config-google.md

@@ -0,0 +1,23 @@
+## Google
+
+Google's OAuth integration allows us to specify multiple callback URLs, so we will only need to do this once for each wiki server.
+
+### Register an application with Google
+
+<!-- Notes: Based on Auth0 docs - see https://auth0.com/docs/connections/social/google -->
+
+* While logged onto your Google account, goto the [API Manager](https://console.developers.google.com/)
+* From the project dropdown at the top of the page, select **Create a project...**
+
+![Google APIs Project Selector](./images/google-new-app.png)
+
+* Enter a Project name, in the New Project dialog, and click **Create**
+
+It will take a moment for Google to create your new project. Once it has been created you will receive a notification, and the page should switch to your new project. *Your new project name will appear in the project dropdown. If it does not, select your new project from the project dropdown.*
+
+* Select **Credentials**, in the left sidebar, and then select the **OAuth consent screen** tab.
+
+![Google OAuth consent screen](./images/google-oauth-consent.png)
+
+
+### Step 2

docs/config-twitter.md

@@ -0,0 +1,5 @@
+## Twitter
+
+### Step 1
+
+### Step 2

docs/configuration.md

@@ -0,0 +1,19 @@
+# Federated Wiki - Security Plug-in: Passport (Configuration)
+
+It is recommended that this plug-in is configured using a configuration file, rather than via the command line.
+
+Configuration of Passport security plug-ins is a two stage process:
+
+1. Registering an application with the identity provider, and
+2. Configuration of the wiki software using information returned in step 1.
+
+The legacy Mozilla Persona Passport plug-in does not require any configuration.
+
+This plug-in comes with support for using GitHub, Google, and Twitter. Although the configuration process is broadly the same for each of these, there are some slight differences.
+
+As a wiki server owner you need to pick one, or more, of these that you want to use.
+
+See, depending on which identity provider you choose to use:
+* [GitHub](./config-github.md)
+* [Google](./config-google.md)
+* [Twitter](./config-twitter.md)