Merge branch 'update_omniauth_integration_document' into 'master'

Update omniauth integration documentation

See merge request !1522

6 files changed, 168 insertions, 81 deletions

diff --git a/doc/integration/github.md b/doc/integration/github.md
index a586334b98d..c9c27859c5e 100644
--- a/doc/integration/github.md
+++ b/doc/integration/github.md
@@ -21,20 +21,44 @@ To enable the GitHub OmniAuth provider you must register your application with G
 
 1.  On your GitLab server, open the configuration file.
 
+    For omnibus package:
+
+    ```sh
+      sudo editor /etc/gitlab/gitlab.rb
+    ```
+
+    For instalations from source:
+
     ```sh
-    cd /home/git/gitlab
+      cd /home/git/gitlab
 
-    sudo -u git -H editor config/gitlab.yml
+      sudo -u git -H editor config/gitlab.yml
     ```
 
-1.  Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for more details.
+1.  See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for inital settings.
+
+1.  Add the provider configuration:
+
+    For omnibus package:
+
+    ```ruby
+      gitlab_rails['omniauth_providers'] = [
+        {
+          "name" => "github",
+          "app_id" => "YOUR APP ID",
+          "app_secret" => "YOUR APP SECRET",
+          "url" => "https://github.com/",
+          "args" => { "scope" => "user:email" } }
+        }
+      ]
+    ```
 
-1.  Under `providers:` uncomment (or add) lines that look like the following:
+    For installation from source:
 
     ```
-        - { name: 'github', app_id: 'YOUR APP ID',
-          app_secret: 'YOUR APP SECRET',
-          args: { scope: 'user:email' } }
+      - { name: 'github', app_id: 'YOUR APP ID',
+        app_secret: 'YOUR APP SECRET',
+        args: { scope: 'user:email' } }
     ```
 
 1.  Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7.
diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md
index b3b1d897225..b95ef5c0af3 100644
--- a/doc/integration/gitlab.md
+++ b/doc/integration/gitlab.md
@@ -12,35 +12,60 @@ To enable the GitLab OmniAuth provider you must register your application with G
 
 1.  Provide the required details.
     - Name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or something else descriptive.
-    - Redirect URI: 
-    
+    - Redirect URI:
+
     ```
     http://gitlab.example.com/import/gitlab/callback
     http://gitlab.example.com/users/auth/gitlab/callback
     ```
 
-    The first link is required for the importer and second for the authorization. 
+    The first link is required for the importer and second for the authorization.
 
 1.  Select "Submit".
 
 1.  You should now see a Application ID and Secret. Keep this page open as you continue configuration.
 
+1.  You should now see a Client ID and Client Secret near the top right of the page (see screenshot). Keep this page open as you continue configuration. ![GitHub app](github_app.png)
+
 1.  On your GitLab server, open the configuration file.
 
+    For omnibus package:
+
     ```sh
-    cd /home/git/gitlab
+      sudo editor /etc/gitlab/gitlab.rb
+    ```
+
+    For instalations from source:
 
-    sudo -u git -H editor config/gitlab.yml
+    ```sh
+      cd /home/git/gitlab
+
+      sudo -u git -H editor config/gitlab.yml
     ```
 
-1.  Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for more details.
+1.  See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for inital settings.
+
+1.  Add the provider configuration:
+
+    For omnibus package:
+
+    ```ruby
+      gitlab_rails['omniauth_providers'] = [
+        {
+          "name" => "gitlab",
+          "app_id" => "YOUR APP ID",
+          "app_secret" => "YOUR APP SECRET",
+          "args" => { "scope" => "api" } }
+        }
+      ]
+    ```
 
-1.  Under `providers:` uncomment (or add) lines that look like the following:
+    For installations from source:
 
     ```
-        - { name: 'gitlab', app_id: 'YOUR APP ID',
-          app_secret: 'YOUR APP SECRET',
-          args: { scope: 'api' } }
+      - { name: 'gitlab', app_id: 'YOUR APP ID',
+        app_secret: 'YOUR APP SECRET',
+        args: { scope: 'api' } }
     ```
 
 1.  Change 'YOUR APP ID' to the Application ID from the GitLab application page.
diff --git a/doc/integration/google.md b/doc/integration/google.md
index 7a78aff8ea4..76beac16c49 100644
--- a/doc/integration/google.md
+++ b/doc/integration/google.md
@@ -27,22 +27,45 @@ To enable the Google OAuth2 OmniAuth provider you must register your application
     - Authorized redirect URI: 'https://gitlab.example.com/users/auth/google_oauth2/callback'
 1. Under the heading "Client ID for web application" you should see a Client ID and Client secret (see screenshot). Keep this page open as you continue configuration. ![Google app](google_app.png)
 
-1. On your GitLab server, open the configuration file.
+1.  On your GitLab server, open the configuration file.
+
+    For omnibus package:
+
+    ```sh
+      sudo editor /etc/gitlab/gitlab.rb
+    ```
+
+    For instalations from source:
 
     ```sh
-    cd /home/git/gitlab
+      cd /home/git/gitlab
 
-    sudo -u git -H editor config/gitlab.yml
+      sudo -u git -H editor config/gitlab.yml
     ```
 
-1.  Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for more details.
+1.  See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for inital settings.
+
+1.  Add the provider configuration:
+
+    For omnibus package:
+
+    ```ruby
+      gitlab_rails['omniauth_providers'] = [
+        {
+          "name" => "google_oauth2",
+          "app_id" => "YOUR APP ID",
+          "app_secret" => "YOUR APP SECRET",
+          "args" => { "access_type" => "offline", "approval_prompt" => '' } }
+        }
+      ]
+    ```
 
-1.  Under `providers:` uncomment (or add) lines that look like the following:
+    For installations from source:
 
     ```
-           - { name: 'google_oauth2', app_id: 'YOUR APP ID',
-             app_secret: 'YOUR APP SECRET',
-             args: { access_type: 'offline', approval_prompt: '' } }
+     - { name: 'google_oauth2', app_id: 'YOUR APP ID',
+       app_secret: 'YOUR APP SECRET',
+       args: { access_type: 'offline', approval_prompt: '' } }
     ```
 
 1.  Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7.
diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md
index 7911cd3e84d..7433de33909 100644
--- a/doc/integration/omniauth.md
+++ b/doc/integration/omniauth.md
@@ -1,8 +1,8 @@
 # OmniAuth
 
-GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and other popular services. Configuring
+GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and other popular services.
 
-OmniAuth does not prevent standard GitLab authentication or LDAP (if configured) from continuing to work. Users can choose to sign in using any of the configured mechanisms.
+Configuring OmniAuth does not prevent standard GitLab authentication or LDAP (if configured) from continuing to work. Users can choose to sign in using any of the configured mechanisms.
 
 - [Initial OmniAuth Configuration](#initial-omniauth-configuration)
 - [Supported Providers](#supported-providers)
@@ -11,9 +11,37 @@ OmniAuth does not prevent standard GitLab authentication or LDAP (if configured)
 
 ## Initial OmniAuth Configuration
 
-Before configuring individual OmniAuth providers there are a few global settings that need to be verified.
+Before configuring individual OmniAuth providers there are a few global settings that are in common for all providers that we need to consider.
 
-1.  Open the configuration file.
+- Omniauth needs to be enabled, see details below for example.
+- `allow_single_sign_on` defaults to `false`. If `false` users must be created manually or they will not be able to
+sign in via OmniAuth.
+- `block_auto_created_users` defaults to `true`. If `true` auto created users will be blocked by default and will
+have to be unblocked by an administrator before they are able to sign in.
+- **Note:** If you set `allow_single_sign_on` to `true` and `block_auto_created_users` to `false` please be aware
+that any user on the Internet will be able to successfully sign in to your GitLab without administrative approval.
+
+If you want to change these settings:
+
+* **For omnibus package**
+
+    Open the configuration file:
+
+    ```sh
+    sudo editor /etc/gitlab/gitlab.rb
+    ```
+
+    and change
+
+    ```
+    gitlab_rails['omniauth_enabled'] = true
+    gitlab_rails['omniauth_allow_single_sign_on'] = false
+    gitlab_rails['block_auto_created_users'] = true
+    ```
+
+* **For installations from source**
+
+    Open the configuration file:
 
     ```sh
     cd /home/git/gitlab
@@ -21,13 +49,13 @@ Before configuring individual OmniAuth providers there are a few global settings
     sudo -u git -H editor config/gitlab.yml
     ```
 
-1.  Find the section dealing with OmniAuth. The section will look similar to the following.
+    and change the following section
 
     ```
-      ## OmniAuth settings
+     ## OmniAuth settings
       omniauth:
         # Allow login via Twitter, Google, etc. using OmniAuth providers
-        enabled: false
+        enabled: true
 
         # CAUTION!
         # This allows users to login without having a user account first (default: false).
@@ -35,43 +63,9 @@ Before configuring individual OmniAuth providers there are a few global settings
         allow_single_sign_on: false
         # Locks down those users until they have been cleared by the admin (default: true).
         block_auto_created_users: true
-
-        ## Auth providers
-        # Uncomment the following lines and fill in the data of the auth provider you want to use
-        # If your favorite auth provider is not listed you can use others:
-        # see https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations
-        # The 'app_id' and 'app_secret' parameters are always passed as the first two
-        # arguments, followed by optional 'args' which can be either a hash or an array.
-        providers:
-        # - { name: 'google_oauth2', app_id: 'YOUR APP ID',
-        #     app_secret: 'YOUR APP SECRET',
-        #     args: { access_type: 'offline', approval_prompt: '' } }
-        # - { name: 'twitter', app_id: 'YOUR APP ID',
-        #     app_secret: 'YOUR APP SECRET'}
-        # - { name: 'github', app_id: 'YOUR APP ID',
-        #     app_secret: 'YOUR APP SECRET',
-        #     args: { scope: 'user:email' } }
-        # - {"name": 'shibboleth',
-        #     args: { shib_session_id_field: "HTTP_SHIB_SESSION_ID",
-        #     shib_application_id_field: "HTTP_SHIB_APPLICATION_ID",
-        #     uid_field: "HTTP_EPPN",
-        #     name_field: "HTTP_CN",
-        #     info_fields: {"email": "HTTP_MAIL" } } }
-
     ```
 
-1.  Change `enabled` to `true`.
-
-1.  Consider the next two configuration options: `allow_single_sign_on` and `block_auto_created_users`.
-
-    - `allow_single_sign_on` defaults to `false`. If `false` users must be created manually or they will not be able to
-    sign in via OmniAuth.
-    - `block_auto_created_users` defaults to `true`. If `true` auto created users will be blocked by default and will
-    have to be unblocked by an administrator before they are able to sign in.
-    - **Note:** If you set `allow_single_sign_on` to `true` and `block_auto_created_users` to `false` please be aware
-    that any user on the Internet will be able to successfully sign in to your GitLab without administrative approval.
-
-1.  Choose one or more of the Supported Providers below to continue configuration.
+Now we can choose one or more of the Supported Providers below to continue configuration.
 
 ## Supported Providers
 
diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md
index ea11f1afeab..6258e5f1030 100644
--- a/doc/integration/shibboleth.md
+++ b/doc/integration/shibboleth.md
@@ -2,12 +2,12 @@
 
 This documentation is for enabling shibboleth with gitlab-omnibus package.
 
-In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however I did not found way to easily configure Nginx that is bundled in gitlab-omnibus package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider. 
+In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however I did not found way to easily configure Nginx that is bundled in gitlab-omnibus package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider.
 
 
 To enable the Shibboleth OmniAuth provider you must:
 
-1. Configure Apache shibboleth module. Installation and configuration of module it self is out of scope of this document. 
+1. Configure Apache shibboleth module. Installation and configuration of module it self is out of scope of this document.
 Check https://wiki.shibboleth.net/ for more info.
 
 1. You can find Apache config in gitlab-recipes (https://github.com/gitlabhq/gitlab-recipes/blob/master/web-server/apache/gitlab-ssl.conf)
@@ -37,15 +37,15 @@ exclude shibboleth URLs from rewriting, add "RewriteCond %{REQUEST_URI} !/Shibbo
   # Apache equivalent of Nginx try files
   RewriteEngine on
   RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
-  RewriteCond %{REQUEST_URI} !/Shibboleth.sso 
-  RewriteCond %{REQUEST_URI} !/shibboleth-sp 
+  RewriteCond %{REQUEST_URI} !/Shibboleth.sso
+  RewriteCond %{REQUEST_URI} !/shibboleth-sp
   RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA]
   RequestHeader set X_FORWARDED_PROTO 'https'
 ```
 
-1.  Edit /etc/gitlab/gitlab.rb configuration file, your shibboleth attributes should be in form of "HTTP_ATTRIBUTE" and you should addjust them to your need and environment. Add any other configuration you need. 
+1.  Edit /etc/gitlab/gitlab.rb configuration file, your shibboleth attributes should be in form of "HTTP_ATTRIBUTE" and you should addjust them to your need and environment. Add any other configuration you need.
 
-File it should look like this:
+File should look like this:
 ```
 external_url 'https://gitlab.example.com'
 gitlab_rails['internal_api_url'] = 'https://gitlab.example.com'
@@ -70,7 +70,7 @@ gitlab_rails['omniauth_providers'] = [
 ]
 
 ```
-1. Save changes and reconfigure gitlab: 
+1. Save changes and reconfigure gitlab:
 ```
 sudo gitlab-ctl reconfigure
 ```
diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md
index b9e501c5ec1..2d517b2fbc9 100644
--- a/doc/integration/twitter.md
+++ b/doc/integration/twitter.md
@@ -33,20 +33,41 @@ To enable the Twitter OmniAuth provider you must register your application with
 
 1.  On your GitLab server, open the configuration file.
 
+    For omnibus package:
+
+    ```sh
+      sudo editor /etc/gitlab/gitlab.rb
+    ```
+
+    For instalations from source:
+
     ```sh
-    cd /home/git/gitlab
+      cd /home/git/gitlab
 
-    sudo -u git -H editor config/gitlab.yml
+      sudo -u git -H editor config/gitlab.yml
     ```
 
-1.  Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration)
-for more details.
+1.  See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for inital settings.
+
+1.  Add the provider configuration:
+
+    For omnibus package:
+
+    ```ruby
+      gitlab_rails['omniauth_providers'] = [
+        {
+          "name" => "twitter",
+          "app_id" => "YOUR APP ID",
+          "app_secret" => "YOUR APP SECRET"
+        }
+      ]
+    ```
 
-1.  Under `providers:` uncomment (or add) lines that look like the following:
+    For installations from source:
 
     ```
-       - { name: 'twitter', app_id: 'YOUR APP ID',
-         app_secret: 'YOUR APP SECRET' }
+      - { name: 'twitter', app_id: 'YOUR APP ID',
+        app_secret: 'YOUR APP SECRET' }
     ```
 
 1.  Change 'YOUR APP ID' to the API key from Twitter page in step 11.