Commit f53cb79d authored by Evan Read's avatar Evan Read
Browse files

Merge branch 'docs-code-block-style-2' into 'master'

Docs: Fix whitespace in administration docs

See merge request gitlab-org/gitlab-ce!30554
......@@ -8,47 +8,48 @@ Authentiq will generate a Client ID and the accompanying Client Secret for you t
1. On your GitLab server, open the configuration file:
For omnibus installation
```sh
sudo editor /etc/gitlab/gitlab.rb
```
For omnibus installation
For installations from source:
```sh
sudo editor /etc/gitlab/gitlab.rb
```
```sh
sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
```
For installations from source:
```sh
sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
```
1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings to enable single sign-on and add Authentiq as an OAuth provider.
1. Add the provider configuration for Authentiq:
For Omnibus packages:
```ruby
gitlab_rails['omniauth_providers'] = [
{
"name" => "authentiq",
"app_id" => "YOUR_CLIENT_ID",
"app_secret" => "YOUR_CLIENT_SECRET",
"args" => {
"scope": 'aq:name email~rs address aq:push'
}
}
]
```
For installations from source:
```yaml
- { name: 'authentiq',
app_id: 'YOUR_CLIENT_ID',
app_secret: 'YOUR_CLIENT_SECRET',
args: {
scope: 'aq:name email~rs address aq:push'
}
}
```
For Omnibus packages:
```ruby
gitlab_rails['omniauth_providers'] = [
{
"name" => "authentiq",
"app_id" => "YOUR_CLIENT_ID",
"app_secret" => "YOUR_CLIENT_SECRET",
"args" => {
"scope": 'aq:name email~rs address aq:push'
}
}
]
```
For installations from source:
```yaml
- { name: 'authentiq',
app_id: 'YOUR_CLIENT_ID',
app_secret: 'YOUR_CLIENT_SECRET',
args: {
scope: 'aq:name email~rs address aq:push'
}
}
```
1. The `scope` is set to request the user's name, email (required and signed), and permission to send push notifications to sign in on subsequent visits.
See [OmniAuth Authentiq strategy](https://github.com/AuthentiqID/omniauth-authentiq/wiki/Scopes,-callback-url-configuration-and-responses) for more information on scopes and modifiers.
......
......@@ -6,55 +6,56 @@
1. Go through the 'Add application' steps, entering the appropriate details.
The screenshot below shows an example configuration.
![Example Crowd application configuration](img/crowd_application.png)
![Example Crowd application configuration](img/crowd_application.png)
## Configure GitLab
1. On your GitLab server, open the configuration file.
**Omnibus:**
**Omnibus:**
```sh
sudo editor /etc/gitlab/gitlab.rb
```
```sh
sudo editor /etc/gitlab/gitlab.rb
```
**Source:**
**Source:**
```sh
cd /home/git/gitlab
```sh
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
```
sudo -u git -H editor config/gitlab.yml
```
1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration)
for initial settings.
1. Add the provider configuration:
**Omnibus:**
```ruby
gitlab_rails['omniauth_providers'] = [
{
"name" => "crowd",
"args" => {
"crowd_server_url" => "CROWD_SERVER_URL",
"application_name" => "YOUR_APP_NAME",
"application_password" => "YOUR_APP_PASSWORD"
}
}
]
```
**Source:**
```
- { name: 'crowd',
args: {
crowd_server_url: 'CROWD_SERVER_URL',
application_name: 'YOUR_APP_NAME',
application_password: 'YOUR_APP_PASSWORD' } }
```
**Omnibus:**
```ruby
gitlab_rails['omniauth_providers'] = [
{
"name" => "crowd",
"args" => {
"crowd_server_url" => "CROWD_SERVER_URL",
"application_name" => "YOUR_APP_NAME",
"application_password" => "YOUR_APP_PASSWORD"
}
}
]
```
**Source:**
```
- { name: 'crowd',
args: {
crowd_server_url: 'CROWD_SERVER_URL',
application_name: 'YOUR_APP_NAME',
application_password: 'YOUR_APP_PASSWORD' } }
```
1. Change `CROWD_SERVER_URL` to the URL of your Crowd server.
1. Change `YOUR_APP_NAME` to the application name from Crowd applications page.
1. Change `YOUR_APP_PASSWORD` to the application password you've set.
......@@ -77,4 +78,4 @@ could not authorize you from Crowd because invalid credentials
Please make sure the Crowd users who need to login to GitLab are authorized to [the application](#configure-a-new-crowd-application) in the step of **Authorisation**. This could be verified by try "Authentication test" for Crowd as of 2.11.
![Example Crowd application authorisation configuration](img/crowd_application_authorisation.png)
\ No newline at end of file
![Example Crowd application authorisation configuration](img/crowd_application_authorisation.png)
......@@ -66,7 +66,7 @@ values obtained during the LDAP client configuration earlier:
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
```ruby
gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = YAML.load <<-EOS # remember to close this block with 'EOS' below
main: # 'main' is the GitLab 'provider ID' of this LDAP server
......@@ -127,7 +127,7 @@ values obtained during the LDAP client configuration earlier:
AcZSFJQjdg5BTyvdEDhaYUKGdRw=
-----END PRIVATE KEY-----
EOS
```
```
1. Save the file and [reconfigure] GitLab for the changes to take effect.
......@@ -137,7 +137,7 @@ values obtained during the LDAP client configuration earlier:
1. Edit `config/gitlab.yml`:
```yaml
```yaml
ldap:
enabled: true
servers:
......
......@@ -3,65 +3,65 @@
To enable the JWT OmniAuth provider, you must register your application with JWT.
JWT will provide you with a secret key for you to use.
1. On your GitLab server, open the configuration file.
1. On your GitLab server, open the configuration file.
For Omnibus GitLab:
For Omnibus GitLab:
```sh
sudo editor /etc/gitlab/gitlab.rb
```
```sh
sudo editor /etc/gitlab/gitlab.rb
```
For installations from source:
For installations from source:
```sh
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
```
```sh
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
```
1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
1. Add the provider configuration.
1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
1. Add the provider configuration.
For Omnibus GitLab:
For Omnibus GitLab:
```ruby
gitlab_rails['omniauth_providers'] = [
{ name: 'jwt',
args: {
secret: 'YOUR_APP_SECRET',
algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
uid_claim: 'email',
required_claims: ['name', 'email'],
info_maps: { name: 'name', email: 'email' },
auth_url: 'https://example.com/',
valid_within: 3600 # 1 hour
}
}
]
```
```ruby
gitlab_rails['omniauth_providers'] = [
{ name: 'jwt',
args: {
secret: 'YOUR_APP_SECRET',
algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
uid_claim: 'email',
required_claims: ['name', 'email'],
info_maps: { name: 'name', email: 'email' },
auth_url: 'https://example.com/',
valid_within: 3600 # 1 hour
}
}
]
```
For installation from source:
For installation from source:
```
- { name: 'jwt',
args: {
secret: 'YOUR_APP_SECRET',
algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
uid_claim: 'email',
required_claims: ['name', 'email'],
info_map: { name: 'name', email: 'email' },
auth_url: 'https://example.com/',
valid_within: 3600 # 1 hour
}
}
```
```
- { name: 'jwt',
args: {
secret: 'YOUR_APP_SECRET',
algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
uid_claim: 'email',
required_claims: ['name', 'email'],
info_map: { name: 'name', email: 'email' },
auth_url: 'https://example.com/',
valid_within: 3600 # 1 hour
}
}
```
NOTE: **Note:** For more information on each configuration option refer to
the [OmniAuth JWT usage documentation](https://github.com/mbleigh/omniauth-jwt#usage).
NOTE: **Note:** For more information on each configuration option refer to
the [OmniAuth JWT usage documentation](https://github.com/mbleigh/omniauth-jwt#usage).
1. Change `YOUR_APP_SECRET` to the client secret and set `auth_url` to your redirect URL.
1. Save the configuration file.
1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
installed GitLab via Omnibus or from source respectively.
1. Change `YOUR_APP_SECRET` to the client secret and set `auth_url` to your redirect URL.
1. Save the configuration file.
1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
installed GitLab via Omnibus or from source respectively.
On the sign in page there should now be a JWT icon below the regular sign in form.
Click the icon to begin the authentication process. JWT will ask the user to
......
......@@ -85,19 +85,19 @@ following.
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['ldap_servers'] = YAML.load <<-EOS
main:
## snip...
##
## Base where we can search for groups
##
## Ex. ou=groups,dc=gitlab,dc=example
##
##
group_base: ou=groups,dc=example,dc=com
EOS
```
```ruby
gitlab_rails['ldap_servers'] = YAML.load <<-EOS
main:
## snip...
##
## Base where we can search for groups
##
## Ex. ou=groups,dc=gitlab,dc=example
##
##
group_base: ou=groups,dc=example,dc=com
EOS
```
1. [Reconfigure GitLab][reconfigure] for the changes to take effect.
......@@ -105,14 +105,14 @@ following.
1. Edit `/home/git/gitlab/config/gitlab.yml`:
```yaml
production:
ldap:
servers:
main:
# snip...
group_base: ou=groups,dc=example,dc=com
```
```yaml
production:
ldap:
servers:
main:
# snip...
group_base: ou=groups,dc=example,dc=com
```
1. [Restart GitLab][restart] for the changes to take effect.
......@@ -140,30 +140,30 @@ group, as opposed to the full DN.
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['ldap_servers'] = YAML.load <<-EOS
main:
## snip...
##
## Base where we can search for groups
##
## Ex. ou=groups,dc=gitlab,dc=example
##
##
group_base: ou=groups,dc=example,dc=com
##
## The CN of a group containing GitLab administrators
##
## Ex. administrators
##
## Note: Not `cn=administrators` or the full DN
##
##
admin_group: my_admin_group
EOS
```
```ruby
gitlab_rails['ldap_servers'] = YAML.load <<-EOS
main:
## snip...
##
## Base where we can search for groups
##
## Ex. ou=groups,dc=gitlab,dc=example
##
##
group_base: ou=groups,dc=example,dc=com
##
## The CN of a group containing GitLab administrators
##
## Ex. administrators
##
## Note: Not `cn=administrators` or the full DN
##
##
admin_group: my_admin_group
EOS
```
1. [Reconfigure GitLab][reconfigure] for the changes to take effect.
......@@ -171,15 +171,15 @@ group, as opposed to the full DN.
1. Edit `/home/git/gitlab/config/gitlab.yml`:
```yaml
production:
ldap:
servers:
main:
# snip...
group_base: ou=groups,dc=example,dc=com
admin_group: my_admin_group
```
```yaml
production:
ldap:
servers:
main:
# snip...
group_base: ou=groups,dc=example,dc=com
admin_group: my_admin_group
```
1. [Restart GitLab][restart] for the changes to take effect.
......@@ -191,7 +191,6 @@ to lock down user abilities to invite new members to a group. When enabled follo
1. Only administrator can manage memberships of any group including access levels.
2. Users are not allowed to share project with other groups or invite members to a project created in a group.
## Adjusting LDAP user sync schedule
> Introduced in GitLab Enterprise Edition Starter.
......@@ -211,9 +210,9 @@ sync to run once every 12 hours at the top of the hour.
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['ldap_sync_worker_cron'] = "0 */12 * * *"
```
```ruby
gitlab_rails['ldap_sync_worker_cron'] = "0 */12 * * *"
```
1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
......@@ -221,11 +220,11 @@ sync to run once every 12 hours at the top of the hour.
1. Edit `config/gitlab.yaml`:
```yaml
cron_jobs:
ldap_sync_worker_cron:
"0 */12 * * *"
```
```yaml
cron_jobs:
ldap_sync_worker_cron:
"0 */12 * * *"
```
1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
......@@ -252,9 +251,9 @@ sync to run once every 2 hours at the top of the hour.
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * * *"
```
```ruby
gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * * *"
```
1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
......@@ -262,11 +261,11 @@ sync to run once every 2 hours at the top of the hour.
1. Edit `config/gitlab.yaml`:
```yaml
cron_jobs:
ldap_group_sync_worker_cron:
"*/30 * * * *"
```
```yaml
cron_jobs:
ldap_group_sync_worker_cron:
"*/30 * * * *"
```
1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
......@@ -283,20 +282,20 @@ task.
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['ldap_servers'] = YAML.load <<-EOS
main:
## snip...
##
## An array of CNs of groups containing users that should be considered external
##
## Ex. ['interns', 'contractors']
##
## Note: Not `cn=interns` or the full DN
##
external_groups: ['interns', 'contractors']
EOS
```
```ruby
gitlab_rails['ldap_servers'] = YAML.load <<-EOS
main:
## snip...
##
## An array of CNs of groups containing users that should be considered external
##
## Ex. ['interns', 'contractors']
##
## Note: Not `cn=interns` or the full DN
##
external_groups: ['interns', 'contractors']
EOS
```
1. [Reconfigure GitLab][reconfigure] for the changes to take effect.
......@@ -304,14 +303,14 @@ task.
1. Edit `config/gitlab.yaml`:
```yaml
production:
ldap:
servers:
main:
# snip...
external_groups: ['interns', 'contractors']
```
```yaml
production:
ldap:
servers:
main:
# snip...
external_groups: ['interns', 'contractors']
```
1. [Restart GitLab][restart] for the changes to take effect.
......@@ -436,66 +435,71 @@ step of the sync.
1. Start a Rails console
```bash
# For Omnibus installations
sudo gitlab-rails console
```bash
# For Omnibus installations
sudo gitlab-rails console
# For installations from source
sudo -u git -H bundle exec rails console production
```
# For installations from source
sudo -u git -H bundle exec rails console production
```
1. Set the log level to debug (only for this session):
```ruby
Rails.logger.level = Logger::DEBUG
```
```ruby
Rails.logger.level = Logger::DEBUG
```
1. Choose a GitLab group to test with. This group should have an LDAP group link
already configured. If the output is `nil`, the group could not be found.
If a bunch of group attributes are output, your group was found successfully.
```ruby
group = Group.find_by(name: 'my_group')
```ruby
group = Group.find_by(name: 'my_group')
# Output
=> #<Group:0x007fe825196558 id: 1234, name: "my_group"...>
```
# Output
=> #<Group:0x007fe825196558 id: 1234, name: "my_group"...>
```
1. Run a group sync for this particular group.
```ruby
EE::Gitlab::Auth::LDAP::Sync::Group.execute_all_providers(group)
```
```ruby
EE::Gitlab::Auth::LDAP::Sync::Group.execute_all_providers(group)
```
1. Look through the output of the sync. See [example log output](#example-log-output)
below for more information about the output.
1. If you still aren't able to see why the user isn't being added, query the
LDAP group directly to see what members are listed. Still in the Rails console,