Merge branch 'update-github-oauth-doc' into 'master'

Update GitHub OAuth / OmniAuth Config Process

See merge request gitlab-org/gitlab!22499

doc/integration/github.md

@@ -4,57 +4,31 @@ You can integrate your GitLab instance with GitHub.com as well as GitHub Enterpr
 
 ## Enabling GitHub OAuth
 
-To enable GitHub OmniAuth provider, you must use GitHub's credentials for your GitLab instance.
-To get the credentials (a pair of Client ID and Client Secret), you must register an application as an OAuth App on GitHub.
+To enable the GitHub OmniAuth provider, you'll need an OAuth 2 Client ID and Client Secret from GitHub. To get these credentials, sign into GitHub and follow their procedure for [Creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).
 
-1. Sign in to GitHub.
+When you create an OAuth 2 app in GitHub, you'll need the following information:
 
-1. Navigate to your individual user or organization settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or an organization - that is entirely up to you.
+- The URL of your GitLab instance, such as `https://gitlab.example.com`.
+- The authorization callback URL; in this case, `https://gitlab.example.com/users/auth`. Include the port number if your GitLab instance uses a non-default port.
 
-   - For individual accounts, select **Developer settings** from the left menu, then select **OAuth Apps**.
-   - For organization accounts, directly select **OAuth Apps** from the left menu.
+NOTE: **Note:**
+To prevent an [OAuth2 covert redirect](http://tetraph.com/covert_redirect/) vulnerability, append `/users/auth` to the end of the GitHub authorization callback URL.
 
-1. Select **Register an application** (if you don't have any OAuth App) or **New OAuth App** (if you already have OAuth Apps).
-   ![Register OAuth App](img/github_app_entry.png)
+See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
 
-1. Provide the required details.
-   - Application name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive.
-   - Homepage URL: The URL of your GitLab installation. For example, `https://gitlab.example.com`.
-   - Application description: Fill this in if you wish.
-   - Authorization callback URL: `http(s)://${YOUR_DOMAIN}/users/auth`. Please make sure the port is included if your GitLab instance is not configured on default port.
-   ![Register OAuth App](img/github_register_app.png)
+Once you have configured the GitHub provider, you'll need the following information, which you'll need to substitute in the GitLab configuration file, in the steps shown next.
 
-   NOTE: Be sure to append `/users/auth` to the end of the callback URL
-   to prevent a [OAuth2 convert
-   redirect](http://tetraph.com/covert_redirect/) vulnerability.
+| Setting from GitHub  |  Substitute in the GitLab configuration file | Description |
+|:---------------------|:-----------------------------------------------|:------------|
+| Client ID            | `YOUR_APP_ID`     |  OAuth 2 Client ID     |
+| Client Secret        | `YOUR_APP_SECRET` |  OAuth 2 Client Secret |
+| URL                  | `https://github.example.com/` |  GitHub Deployment URL |
 
-1. Select **Register application**.
+Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server:
 
-1. You should now see a pair of **Client ID** and **Client Secret** near the top right of the page (see screenshot).
-   Keep this page open as you continue configuration.
-   ![GitHub app](img/github_app.png)
+**For Omnibus installations**
 
-1. On your GitLab server, open the configuration file.
-
-   For Omnibus package:
-
-   ```sh
-   sudo editor /etc/gitlab/gitlab.rb
-   ```
-
-   For installations from source:
-
-   ```sh
-   cd /home/git/gitlab
-
-   sudo -u git -H editor config/gitlab.yml
-   ```
-
-1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
-
-1. Add the provider configuration:
-
-   For Omnibus package:
+1. Edit `/etc/gitlab/gitlab.rb`:
 
    For GitHub.com:
 
@@ -83,7 +57,15 @@ To get the credentials (a pair of Client ID and Client Secret), you must registe
    ]
    ```
 
-   For installation from source:
+   **Replace `https://github.example.com/` with your GitHub URL.**
+
+1. Save the file and [reconfigure](../administration/restart_gitlab.html#omnibus-gitlab-reconfigure) GitLab for the changes to take effect.
+
+---
+
+**For installations from source**
+
+1. Navigate to your repository and edit `config/gitlab.yml`:
 
    For GitHub.com:
 
@@ -102,20 +84,15 @@ To get the credentials (a pair of Client ID and Client Secret), you must registe
      args: { scope: 'user:email' } }
    ```
 
-   __Replace `https://github.example.com/` with your GitHub URL.__
-
-1. Change `YOUR_APP_ID` to the Client ID from the GitHub application page from step 6.
+   **Replace `https://github.example.com/` with your GitHub URL.**
 
-1. Change `YOUR_APP_SECRET` to the Client Secret from the GitHub application page from step 6.
+1. Save the file and [restart](../administration/restart_gitlab.html#installations-from-source) GitLab for the changes to take effect.
 
-1. Save the configuration file.
+---
 
-1. [Reconfigure GitLab][] or [restart GitLab][] for the changes to take effect if you
-   installed GitLab via Omnibus or from source respectively.
+1. Refresh the GitLab sign in page. You should now see a GitHub icon below the regular sign in form.
 
-On the sign in page there should now be a GitHub icon below the regular sign in form.
-Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application.
-If everything goes well the user will be returned to GitLab and will be signed in.
+1. Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application.
 
 ## GitHub Enterprise with self-signed Certificate