Commit 5725b6da authored by Sytse Sijbrandij's avatar Sytse Sijbrandij

Merge branch 'update_omniauth_integration_document' into 'master'

Update omniauth integration documentation

See merge request !1522
parents d785b20c d76c5824
...@@ -21,20 +21,44 @@ To enable the GitHub OmniAuth provider you must register your application with G ...@@ -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. 1. On your GitLab server, open the configuration file.
For omnibus package:
```sh
sudo editor /etc/gitlab/gitlab.rb
```
For instalations from source:
```sh ```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', - { name: 'github', app_id: 'YOUR APP ID',
app_secret: 'YOUR APP SECRET', app_secret: 'YOUR APP SECRET',
args: { scope: 'user:email' } } args: { scope: 'user:email' } }
``` ```
1. Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7. 1. Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7.
......
...@@ -12,35 +12,60 @@ To enable the GitLab OmniAuth provider you must register your application with G ...@@ -12,35 +12,60 @@ To enable the GitLab OmniAuth provider you must register your application with G
1. Provide the required details. 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. - 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/import/gitlab/callback
http://gitlab.example.com/users/auth/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. 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 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. 1. On your GitLab server, open the configuration file.
For omnibus package:
```sh ```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', - { name: 'gitlab', app_id: 'YOUR APP ID',
app_secret: 'YOUR APP SECRET', app_secret: 'YOUR APP SECRET',
args: { scope: 'api' } } args: { scope: 'api' } }
``` ```
1. Change 'YOUR APP ID' to the Application ID from the GitLab application page. 1. Change 'YOUR APP ID' to the Application ID from the GitLab application page.
......
...@@ -27,22 +27,45 @@ To enable the Google OAuth2 OmniAuth provider you must register your application ...@@ -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' - 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. 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 ```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', - { name: 'google_oauth2', app_id: 'YOUR APP ID',
app_secret: 'YOUR APP SECRET', app_secret: 'YOUR APP SECRET',
args: { access_type: 'offline', approval_prompt: '' } } args: { access_type: 'offline', approval_prompt: '' } }
``` ```
1. Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7. 1. Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7.
......
# OmniAuth # 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) - [Initial OmniAuth Configuration](#initial-omniauth-configuration)
- [Supported Providers](#supported-providers) - [Supported Providers](#supported-providers)
...@@ -11,9 +11,37 @@ OmniAuth does not prevent standard GitLab authentication or LDAP (if configured) ...@@ -11,9 +11,37 @@ OmniAuth does not prevent standard GitLab authentication or LDAP (if configured)
## Initial OmniAuth Configuration ## 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 ```sh
cd /home/git/gitlab cd /home/git/gitlab
...@@ -21,13 +49,13 @@ Before configuring individual OmniAuth providers there are a few global settings ...@@ -21,13 +49,13 @@ Before configuring individual OmniAuth providers there are a few global settings
sudo -u git -H editor config/gitlab.yml 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: omniauth:
# Allow login via Twitter, Google, etc. using OmniAuth providers # Allow login via Twitter, Google, etc. using OmniAuth providers
enabled: false enabled: true
# CAUTION! # CAUTION!
# This allows users to login without having a user account first (default: false). # 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 ...@@ -35,43 +63,9 @@ Before configuring individual OmniAuth providers there are a few global settings
allow_single_sign_on: false allow_single_sign_on: false
# Locks down those users until they have been cleared by the admin (default: true). # Locks down those users until they have been cleared by the admin (default: true).
block_auto_created_users: 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`. Now we can choose one or more of the Supported Providers below to continue configuration.
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.
## Supported Providers ## Supported Providers
......
...@@ -2,12 +2,12 @@ ...@@ -2,12 +2,12 @@
This documentation is for enabling shibboleth with gitlab-omnibus package. 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: 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. 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) 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 ...@@ -37,15 +37,15 @@ exclude shibboleth URLs from rewriting, add "RewriteCond %{REQUEST_URI} !/Shibbo
# Apache equivalent of Nginx try files # Apache equivalent of Nginx try files
RewriteEngine on RewriteEngine on
RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_URI} !/Shibboleth.sso RewriteCond %{REQUEST_URI} !/Shibboleth.sso
RewriteCond %{REQUEST_URI} !/shibboleth-sp RewriteCond %{REQUEST_URI} !/shibboleth-sp
RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA] RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA]
RequestHeader set X_FORWARDED_PROTO 'https' 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' external_url 'https://gitlab.example.com'
gitlab_rails['internal_api_url'] = 'https://gitlab.example.com' gitlab_rails['internal_api_url'] = 'https://gitlab.example.com'
...@@ -70,7 +70,7 @@ gitlab_rails['omniauth_providers'] = [ ...@@ -70,7 +70,7 @@ gitlab_rails['omniauth_providers'] = [
] ]
``` ```
1. Save changes and reconfigure gitlab: 1. Save changes and reconfigure gitlab:
``` ```
sudo gitlab-ctl reconfigure sudo gitlab-ctl reconfigure
``` ```
......
...@@ -33,20 +33,41 @@ To enable the Twitter OmniAuth provider you must register your application with ...@@ -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. 1. On your GitLab server, open the configuration file.
For omnibus package:
```sh
sudo editor /etc/gitlab/gitlab.rb
```
For instalations from source:
```sh ```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) 1. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for inital settings.
for more details.
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', - { name: 'twitter', app_id: 'YOUR APP ID',
app_secret: 'YOUR APP SECRET' } app_secret: 'YOUR APP SECRET' }
``` ```
1. Change 'YOUR APP ID' to the API key from Twitter page in step 11. 1. Change 'YOUR APP ID' to the API key from Twitter page in step 11.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment