Merge branch 'update_omniauth_integration_document' into 'master'

Update omniauth integration documentation

See merge request !1522

doc/integration/github.md

@@ -21,15 +21,39 @@ 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
 
       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',

doc/integration/gitlab.md

@@ -25,17 +25,42 @@ To enable the GitLab OmniAuth provider you must register your application with G
 
 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
+      sudo editor /etc/gitlab/gitlab.rb
+    ```
+
+    For instalations from source:
+
     ```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',

doc/integration/google.md

@@ -29,15 +29,38 @@ To enable the Google OAuth2 OmniAuth provider you must register your application
 
 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
 
       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',

doc/integration/omniauth.md

 # 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:
         # 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
 

doc/integration/shibboleth.md

@@ -45,7 +45,7 @@ exclude shibboleth URLs from rewriting, add "RewriteCond %{REQUEST_URI} !/Shibbo
 
 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'

doc/integration/twitter.md

@@ -33,16 +33,37 @@ 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
 
       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',