Merge pull request #6741 from dblessing/omniauth_docs

Add OmniAuth Documentation

config/gitlab.yml.example

@@ -175,7 +175,7 @@ production: &base
     ## 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/Working-custom-omniauth-provider-configurations
+    # 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:

doc/integration/README.md

-+ [External issue tracker](external-issue-tracker.md)
-+ [LDAP](ldap.md)
-+ [oAuth](oauth.md) Login with Twitter, GitHub, etc.
\ No newline at end of file
+# GitLab Integration
+
+GitLab integrates with multiple third-party services to allow external issue trackers and external authentication.
+See the documentation below for details on how to configure these services.
+
++ [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc.
++ [LDAP](ldap.md) Set up sign in via LDAP
++ [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, and Google via OAuth.

doc/integration/github.md

+# GitHub OAuth2 OmniAuth Provider
+
+To enable the GitHub OmniAuth provider you must register your application with GitHub. GitHub will generate a client ID and secret key for you to use.
+
+1. Sign in to GitHub. 
+2. Navigate to your individual user settings or an organization's 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.
+3. Select "Applications" in the left menu.
+4. Select "Register new application".
+5. 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 to your GitLab installation. 'https://gitlab.company.com'
+    * Application description: Fill this in if you wish.
+    * Authorization callback URL: 'https://gitlab.company.com/users/auth/github/callback'
+6. Select "Register application". 
+7. 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)
+8. On your GitLab server, open the configuration file.
+
+    ```sh
+    cd /home/git/gitlab
+
+    sudo -u git -H editor config/gitlab.yml
+    ```
+
+9. Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for more details.
+10. Under `providers:` uncomment (or add) lines that look like the following:
+
+    ```
+        - { name: 'github', app_id: 'YOUR APP ID',
+          app_secret: 'YOUR APP SECRET',
+          args: { scope: 'user:email' } }
+    ```
+
+11. Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7. 
+12. Change 'YOUR APP SECRET' to the client secret from the GitHub application page  from step 7.
+13. Save the configuration file.
+14. Restart GitLab for the changes to take effect.
+
+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.

doc/integration/google.md

+# Google OAuth2 OmniAuth Provider
+
+To enable the Google OAuth2 OmniAuth provider you must register your application with Google. Google will generate a client ID and secret key for you to use.
+
+1. Sign in to the [Google Developers Console](https://console.developers.google.com/) with the Google account you want to use to register GitLab. 
+2. Select "Create Project".
+3. Provide the project information
+    * Project name: 'GitLab' works just fine here. 
+    * Project ID: Must be unique to all Google Developer registered applications. Google provides a randomly generated Project ID by default. You can use the randomly generated ID or choose a new one.
+4. Refresh the page. You should now see your new project in the list. Click on the project.
+5. Select "APIs & auth" in the left menu.
+6. Select "Credentials" in the submenu.
+7. Select "Create New Client ID".
+8. Fill in the required information
+    * Application type: "Web Application"
+    * Authorized JavaScript origins: This isn't really used by GitLab but go ahead and put 'https://gitlab.example.com' here.
+    * Authorized redirect URI: 'https://gitlab.example.com/users/auth/google_oauth2/callback'
+9. 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)
+10. On your GitLab server, open the configuration file.
+    ```sh
+    cd /home/git/gitlab
+
+    sudo -u git -H editor config/gitlab.yml
+    ```
+11. Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for more details.
+12. Under `providers:` uncomment (or add) lines that look like the following:
+
+    ```
+           - { name: 'google_oauth2', app_id: 'YOUR APP ID',
+             app_secret: 'YOUR APP SECRET',
+             args: { access_type: 'offline', approval_prompt: '' } }
+    ```
+
+13. Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7. 
+14. Change 'YOUR APP SECRET' to the client secret from the GitHub application page  from step 7.
+15. Save the configuration file.
+16. Restart GitLab for the changes to take effect.
+
+On the sign in page there should now be a Google icon below the regular sign in form. Click the icon to begin the authentication process. Google 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.
+
+## Further Configuration 
+
+This further configuration is not required for Google authentication to function but it is strongly recommended. Taking these steps will increase usability for users by providing a little more recognition and branding.
+
+At this point, when users first try to authenticate to your GitLab installation with Google they will see a generic application name on the prompt screen. The prompt informs the user that "Project Default Service Account" would like to access their account. "Project Default Service Account" isn't very recognizable and may confuse or cause users to be concerned. This is easily changeable.
+
+1. Select 'Consent screen' in the left menu. (See steps 1, 4 and 5 above for instructions on how to get here if you closed your window).
+2. Scroll down until you find "Product Name". Change the product name to something more descriptive. 
+3. Add any additional information as you wish - homepage, logo, privacy policy, etc. None of this is required, but it may help your users.

doc/integration/oauth.md

-# OAuth
-
-You can use other services to log into GitLab via oAuth.
-
-For this you need: 
-
-* create app in selected services
-* configure gitlab.yml 
-
-## Twitter:
-
-Below are screenshots how to setup your app on Twitter for this:
-
-![Application details](twitter_app_details.png)
-![API Keys](twitter_app_api_keys.png)
-
-## GitHub:
-
-![GitHub app](github_app.png)
-
-## Google:
-
-![Google app](google_app.png)
-
-
-## GitLab config file
-
-Second step is to modify gitlab.yml with app credentials:
-
-```
-production:
-  ...
-
-  omniauth:
-    enabled: true
-  
-    providers:
-      - { 
-        name: 'twitter',
-        app_id: 'XXXXXXXX',
-        app_secret: 'XXXXXXXXXXXXXXXXXXXXXXXX'
-        }
-      - { 
-        name: 'google_oauth2',
-        app_id: 'XXXXXXXXXXX.apps.googleusercontent.com',
-        app_secret: 'XXXXXXXX'
-        }
-      - { 
-        name: 'github',
-        app_id: 'XXXXXXXXXX',
-        app_secret: 'XXXXXXXXXXXXXXXXXXXXXXXX'
-        }
-
-```
-

doc/integration/omniauth.md

+# OmniAuth
+
+GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and other popular services. 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)
++ [Enable OmniAuth for an Existing User](#enable-omniauth-for-an-existing-user)
+
+### Initial OmniAuth Configuration
+
+Before configuring individual OmniAuth providers there are a few global settings that need to be verified.
+
+1. Open the configuration file<br />
+
+    ```sh
+    cd /home/git/gitlab
+
+    sudo -u git -H editor config/gitlab.yml
+    ```
+
+2. Find the section dealing with OmniAuth. The section will look similar to the following.<br />
+    ```
+      ## OmniAuth settings
+      omniauth:
+        # Allow login via Twitter, Google, etc. using OmniAuth providers
+        enabled: false
+
+        # CAUTION!
+        # This allows users to login without having a user account first (default: false).
+        # User accounts will be created automatically when authentication was successful.
+        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' } }
+    ```
+3. Change `enabled` to `true`.
+4. 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.
+5. Choose one or more of the Supported Providers below to continue configuration.
+
+### Supported Providers
+
++ [GitHub](github.md)
++ [Google](google.md)
++ [Twitter](twitter.md)
+
+### Enable OmniAuth for an Existing User
+
+Existing users can enable OmniAuth for specific providers after the account is created. For example, if the user
+originally signed in with LDAP an OmniAuth provider such as Twitter can be enabled. Follow the steps below to enable an
+OmniAuth provider for an existing user.
+
+1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider.
+2. Go to profile settings (the silhouette icon in the top right corner).
+3. Select the "Account" tab.
+4. Under "Social Accounts" select the desired OmniAuth provider, such as Twitter.
+5. The user will be redirected to the provider. Once the user authorized GitLab they will be redirected back to GitLab.
+
+The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on.

doc/integration/twitter.md

+# Twitter OAuth2 OmniAuth Provider
+
+To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client
+ID and secret key for you to use.
+
+1. Sign in to [Twitter Developers](https://dev.twitter.com/) area.
+2. Hover over the avatar in the top right corner and select "My applications."
+3. Select "Create new app"
+4. Fill in the application details.
+    * Name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or
+    something else descriptive.
+    * Description: Create a description.
+    * Website: The URL to your GitLab installation. 'https://gitlab.example.com'
+    * Callback URL: 'https://gitlab.example.com/users/auth/github/callback'
+    * Agree to the "Rules of the Road."
+    ![Twitter App Details](twitter_app_details.png)
+6. Select "Create your Twitter application."
+7. Select the "Settings" tab.
+8. Underneath the Callback URL check the box next to "Allow this application to be used to Sign in the Twitter."
+9. Select "Update settings" at the bottom to save changes.
+10. Select the "API Keys" tab.
+11. You should now see an API key and API secret (see screenshot). Keep this page open as you continue configuration.
+![Twitter app](twitter_app_api_keys.png)
+12. On your GitLab server, open the configuration file.
+
+    ```sh
+    cd /home/git/gitlab
+
+    sudo -u git -H editor config/gitlab.yml
+    ```
+
+13. Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration)
+for more details.
+14. Under `providers:` uncomment (or add) lines that look like the following:
+
+    ```
+       - { name: 'twitter', app_id: 'YOUR APP ID',
+         app_secret: 'YOUR APP SECRET' }
+    ```
+
+15. Change 'YOUR APP ID' to the API key from Twitter page in step 11.
+16. Change 'YOUR APP SECRET' to the API secret from the Twitter page in step 11.
+17. Save the configuration file.
+18. Restart GitLab for the changes to take effect.
+
+On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the
+authentication process. Twitter 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.