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,15 +21,39 @@ To enable the GitHub OmniAuth provider you must register your application with G ...@@ -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. 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',
......
...@@ -25,17 +25,42 @@ To enable the GitLab OmniAuth provider you must register your application with G ...@@ -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 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
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" => "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',
......
...@@ -29,15 +29,38 @@ To enable the Google OAuth2 OmniAuth provider you must register your application ...@@ -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. 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',
......
# 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
......
...@@ -45,7 +45,7 @@ exclude shibboleth URLs from rewriting, add "RewriteCond %{REQUEST_URI} !/Shibbo ...@@ -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. 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'
......
...@@ -33,16 +33,37 @@ To enable the Twitter OmniAuth provider you must register your application with ...@@ -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. 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',
......
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