Merge branch 'structure-oauth-docs' into 'master'

Structure oauth docs

Fixes #2010

@valery please let me know if I used the right terminology (GitLab as an OAuth2 client)

See merge request !1545

10 files changed, 36 insertions, 22 deletions

diff --git a/doc/README.md b/doc/README.md
index 932e90e359a..4e00dceac2b 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -10,6 +10,7 @@
 - [SSH](ssh/README.md) Setup your ssh keys and deploy keys for secure access to your projects.
 - [Web hooks](web_hooks/web_hooks.md) Let GitLab notify you when new code has been pushed to your project.
 - [Workflow](workflow/README.md) Using GitLab functionality and importing projects from GitHub and SVN.
+- [GitLab as OAuth2 authentication service provider](integration/oauth_provider.md). It allows you to login to other applications from GitLab.
 
 ## Administrator documentation
 
diff --git a/doc/api/README.md b/doc/api/README.md
index 8cbba8598d5..dec530d0b81 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -22,6 +22,7 @@
 ## Clients
 
 Find API Clients for GitLab [on our website](https://about.gitlab.com/applications/#api-clients).
+You can use [GitLab as an OAuth2 client](oauth2.md) to make API calls.
 
 ## Introduction
 
@@ -67,7 +68,7 @@ curl https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN
 curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user
 ```
 
-Read more about [OAuth2 in GitLab](oauth2.md).
+Read more about [GitLab as an OAuth2 client](oauth2.md).
 
 ## Status codes
 
diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md
index 7bb391054ce..d416a826f79 100644
--- a/doc/api/oauth2.md
+++ b/doc/api/oauth2.md
@@ -1,14 +1,17 @@
-# OAuth2 authentication
+# GitLab as an OAuth2 client
 
-OAuth2 is a protocol that enables us to get access to private details of user's account without getting its password. 
+This document is about using other OAuth authentication service providers to sign into GitLab.
+If you want GitLab to be an OAuth authentication service provider to sign into other services please see the [Oauth2 provider documentation](../integration/oauth_provider.md).
 
-Before using the OAuth2 you should create an application in user's account. Each application getting unique App ID and App Secret parameters. You should not share them.
+OAuth2 is a protocol that enables us to authenticate a user without requiring them to give their password. 
+
+Before using the OAuth2 you should create an application in user's account. Each application gets a unique App ID and App Secret parameters. You should not share these.
 
 This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper)
 
 ## Web Application Flow
 
-This flow is using for authentication from third-party web sites and probably is most used. 
+This flow is using for authentication from third-party web sites and is probably used the most. 
 It basically consists of an exchange of an authorization token for an access token. For more detailed info, check out the [RFC spec here](http://tools.ietf.org/html/rfc6749#section-4.1)
 
 This flow consists from 3 steps.
diff --git a/doc/integration/README.md b/doc/integration/README.md
index 1fc8ab997ec..e5f33d8deed 100644
--- a/doc/integration/README.md
+++ b/doc/integration/README.md
@@ -8,9 +8,8 @@ See the documentation below for details on how to configure these services.
 - [LDAP](ldap.md) Set up sign in via LDAP
 - [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, GitLab, and Google via OAuth.
 - [Slack](slack.md) Integrate with the Slack chat service
-- [OAuth2 provider](oauth_provider.md) OAuth2 application creation
 
-Jenkins support is [available in GitLab EE](http://doc.gitlab.com/ee/integration/jenkins.html).
+GitLab Enterprise Edition contains [advanced JIRA support](http://doc.gitlab.com/ee/integration/jira.html) and [advanced Jenkins support](http://doc.gitlab.com/ee/integration/jenkins.html).
 
 ## Project services
 
diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md
index 53d6898b6e8..96755707dee 100644
--- a/doc/integration/external-issue-tracker.md
+++ b/doc/integration/external-issue-tracker.md
@@ -8,6 +8,8 @@ GitLab has a great issue tracker but you can also use an external issue tracker
 
 ![Jira screenshot](jira-integration-points.png)
 
+GitLab Enterprise Edition contains [advanced JIRA support](http://doc.gitlab.com/ee/integration/jira.html).
+
 ## Configuration
 
 ### Project Service
@@ -23,7 +25,6 @@ Fill in the required details on the page:
 * `issues_url` The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the url. This id is used by GitLab as a placeholder to replace the issue number.
 * `new_issue_url` This is the URL to create a new issue in Redmine for the project linked to this GitLab project.
 
-
 ### Service Template
 
 It is necessary to configure the external issue tracker per project, because project specific details are needed for the integration with GitLab.
diff --git a/doc/integration/github.md b/doc/integration/github.md
index c9c27859c5e..137d7e9d632 100644
--- a/doc/integration/github.md
+++ b/doc/integration/github.md
@@ -35,7 +35,7 @@ To enable the GitHub OmniAuth provider you must register your application with G
       sudo -u git -H editor config/gitlab.yml
     ```
 
-1.  See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for inital settings.
+1.  See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for inital settings.
 
 1.  Add the provider configuration:
 
diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md
index b95ef5c0af3..87400bed5b5 100644
--- a/doc/integration/gitlab.md
+++ b/doc/integration/gitlab.md
@@ -1,10 +1,13 @@
-# GitLab OAuth2 OmniAuth Provider
+# Integrate your server with GitLab.com
 
-To enable the GitLab OmniAuth provider you must register your application with GitLab. GitLab will generate a client ID and secret key for you to use.
+Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account.
 
-1.  Sign in to GitLab.
+To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com. 
+GitLab.com will generate a application ID and secret key for you to use.
 
-1.  Navigate to your settings.
+1.  Sign in to GitLab.com
+
+1.  Navigate to your profile settings.
 
 1.  Select "Applications" in the left menu.
 
@@ -15,17 +18,17 @@ To enable the GitLab OmniAuth provider you must register your application with G
     - Redirect URI:
 
     ```
-    http://gitlab.example.com/import/gitlab/callback
-    http://gitlab.example.com/users/auth/gitlab/callback
+    http://your-gitlab.example.com/import/gitlab/callback
+    http://your-gitlab.example.com/users/auth/gitlab/callback
     ```
 
     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.  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. 
+    ![GitLab app](gitlab_app.png)
 
 1.  On your GitLab server, open the configuration file.
 
@@ -43,7 +46,7 @@ To enable the GitLab OmniAuth provider you must register your application with G
       sudo -u git -H editor config/gitlab.yml
     ```
 
-1.  See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for inital settings.
+1.  See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for inital settings.
 
 1.  Add the provider configuration:
 
@@ -76,4 +79,6 @@ To enable the GitLab OmniAuth provider you must register your application with G
 
 1.  Restart GitLab for the changes to take effect.
 
-On the sign in page there should now be a GitLab icon below the regular sign in form. Click the icon to begin the authentication process. GitLab will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to your GitLab instance and will be signed in.
+On the sign in page there should now be a GitLab.com icon below the regular sign in form. 
+Click the icon to begin the authentication process. GitLab.com will ask the user to sign in and authorize the GitLab application. 
+If everything goes well the user will be returned to your GitLab instance and will be signed in.
diff --git a/doc/integration/gitlab_app.png b/doc/integration/gitlab_app.png
new file mode 100644
index 00000000000..3f9391a821b
--- /dev/null
+++ b/doc/integration/gitlab_app.png
diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md
index 5fdb74a43df..192c321f712 100644
--- a/doc/integration/oauth_provider.md
+++ b/doc/integration/oauth_provider.md
@@ -1,4 +1,8 @@
-## GitLab as OAuth2 provider
+## GitLab as OAuth2 authentication service provider
+
+This document is about using GitLab as an OAuth authentication service provider to sign into other services.
+If you want to use other OAuth authentication service providers to sign into GitLab please see the [OAuth2 client documentation](../api/oauth2.md)
+
 OAuth2 provides client applications a 'secure delegated access' to server resources on behalf of a resource owner. Or you can allow users to sign in to your application with their GitLab.com account.
 In fact OAuth allows to issue access token to third-party clients by an authorization server, 
 with the approval of the resource owner, or end-user. 
diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md
index 7433de33909..c92fa3ee4b7 100644
--- a/doc/integration/omniauth.md
+++ b/doc/integration/omniauth.md
@@ -70,7 +70,7 @@ Now we can choose one or more of the Supported Providers below to continue confi
 ## Supported Providers
 
 - [GitHub](github.md)
-- [GitLab](gitlab.md)
+- [GitLab.com](gitlab.md)
 - [Google](google.md)
 - [Shibboleth](shibboleth.md)
 - [Twitter](twitter.md)