summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorMarin Jankovski <maxlazio@gmail.com>2015-02-13 14:49:19 -0800
committerMarin Jankovski <maxlazio@gmail.com>2015-02-13 14:49:19 -0800
commitd76c5824bc05640d276be96f7853f2d266fd6750 (patch)
treec783924f16e6423e5085d0578b6614c7583b987a /doc
parentd0f045eb860f819a736d76622d8d9c546a9610ee (diff)
downloadgitlab-ce-d76c5824bc05640d276be96f7853f2d266fd6750.tar.gz
Update oauth documenatation with examples for omnibus package and installations from source.
Diffstat (limited to 'doc')
-rw-r--r--doc/integration/github.md38
-rw-r--r--doc/integration/gitlab.md45
-rw-r--r--doc/integration/google.md39
-rw-r--r--doc/integration/omniauth.md78
-rw-r--r--doc/integration/shibboleth.md14
-rw-r--r--doc/integration/twitter.md35
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.