diff --git a/ReadMe.md b/ReadMe.md index c482352..89e4b7b 100644 --- a/ReadMe.md +++ b/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). diff --git a/configuration.md b/configuration.md deleted file mode 100644 index a6186f9..0000000 --- a/configuration.md +++ /dev/null @@ -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 diff --git a/docs/config-github.md b/docs/config-github.md new file mode 100644 index 0000000..fc3a389 --- /dev/null +++ b/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" + } + } +} +``` diff --git a/docs/config-google.md b/docs/config-google.md new file mode 100644 index 0000000..d23c562 --- /dev/null +++ b/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 + + + +* 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 diff --git a/docs/config-twitter.md b/docs/config-twitter.md new file mode 100644 index 0000000..61d6079 --- /dev/null +++ b/docs/config-twitter.md @@ -0,0 +1,5 @@ +## Twitter + +### Step 1 + +### Step 2 diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..455daf8 --- /dev/null +++ b/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) diff --git a/docs/images/github-app-summary.png b/docs/images/github-app-summary.png new file mode 100644 index 0000000..fff9fda Binary files /dev/null and b/docs/images/github-app-summary.png differ diff --git a/docs/images/github-new-app.png b/docs/images/github-new-app.png new file mode 100644 index 0000000..0784081 Binary files /dev/null and b/docs/images/github-new-app.png differ diff --git a/docs/images/google-new-app.png b/docs/images/google-new-app.png new file mode 100644 index 0000000..878b82c Binary files /dev/null and b/docs/images/google-new-app.png differ diff --git a/docs/images/google-oauth-consent.png b/docs/images/google-oauth-consent.png new file mode 100644 index 0000000..6259c61 Binary files /dev/null and b/docs/images/google-oauth-consent.png differ