diff options
Diffstat (limited to 'doc/integration')
26 files changed, 0 insertions, 975 deletions
diff --git a/doc/integration/README.md b/doc/integration/README.md deleted file mode 100644 index 286bd34a0bd..00000000000 --- a/doc/integration/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# GitLab Integration - -GitLab integrates with multiple third-party services to allow external issue trackers and external authentication. - -See the documentation below for details on how to configure these services. - -- [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc. -- [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 -- [Gmail](gitlab_buttons_in_gmail.md) Adds GitLab actions to messages - -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 - -Integration with services such as Campfire, Flowdock, Gemnasium, HipChat, Pivotal Tracker, and Slack are available in the form of a Project Service. -You can find these within GitLab in the Services page under Project Settings if you are at least a master on the project. -Project Services are a bit like plugins in that they allow a lot of freedom in adding functionality to GitLab, for example there is also a service that can send an email every time someone pushes new commits. -Because GitLab is open source we can ship with the code and tests for all plugins. -This allows the community to keep the plugins up to date so that they always work in newer GitLab versions. -For an overview of what projects services are available without logging in please see the [project_services directory](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/models/project_services). diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md deleted file mode 100644 index d82e1f8b41b..00000000000 --- a/doc/integration/bitbucket.md +++ /dev/null @@ -1,122 +0,0 @@ -# Integrate your server with Bitbucket - -Import projects from Bitbucket and login to your GitLab instance with your Bitbucket account. - -To enable the Bitbucket OmniAuth provider you must register your application with Bitbucket. -Bitbucket will generate an application ID and secret key for you to use. - -1. Sign in to Bitbucket. - -1. Navigate to your individual user settings or a team's settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or a team - that is entirely up to you. - -1. Select "OAuth" in the left menu. - -1. Select "Add consumer". - -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. - - Application description: Fill this in if you wish. - - URL: The URL to your GitLab installation. 'https://gitlab.company.com' -1. Select "Save". - -1. You should now see a Key and Secret in the list of OAuth customers. - Keep this page open as you continue configuration. - -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 - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "bitbucket", - "app_id" => "YOUR_KEY", - "app_secret" => "YOUR_APP_SECRET", - "url" => "https://bitbucket.org/" - } - ] - ``` - - For installation from source: - - ``` - - { name: 'bitbucket', app_id: 'YOUR_KEY', - app_secret: 'YOUR_APP_SECRET' } - ``` - -1. Change 'YOUR_APP_ID' to the key from the Bitbucket application page from step 7. - -1. Change 'YOUR_APP_SECRET' to the secret from the Bitbucket application page from step 7. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Bitbucket icon below the regular sign in form. -Click the icon to begin the authentication process. Bitbucket will ask the user to sign in and authorize the GitLab application. -If everything goes well the user will be returned to GitLab and will be signed in. - -## Bitbucket project import - -To allow projects to be imported directly into GitLab, Bitbucket requires two extra setup steps compared to GitHub and GitLab.com. - -Bitbucket doesn't allow OAuth applications to clone repositories over HTTPS, and instead requires GitLab to use SSH and identify itself using your GitLab server's SSH key. - -### Step 1: Known hosts - -To allow GitLab to connect to Bitbucket over SSH, you need to add 'bitbucket.org' to your GitLab server's known SSH hosts. Take the following steps to do so: - -1. Manually connect to 'bitbucket.org' over SSH, while logged in as the `git` account that GitLab will use: - - ```sh - ssh git@bitbucket.org - ``` - -1. Verify the RSA key fingerprint you'll see in the response matches the one in the [Bitbucket documentation](https://confluence.atlassian.com/display/BITBUCKET/Use+the+SSH+protocol+with+Bitbucket#UsetheSSHprotocolwithBitbucket-KnownhostorBitbucket'spublickeyfingerprints) (the specific IP address doesn't matter): - - ```sh - The authenticity of host 'bitbucket.org (207.223.240.182)' can't be established. - RSA key fingerprint is 97:8c:1b:f2:6f:14:6b:5c:3b:ec:aa:46:46:74:7c:40. - Are you sure you want to continue connecting (yes/no)? - ``` - -1. If the fingerprint matches, type `yes` to continue connecting and have 'bitbucket.org' be added to your known hosts. - -1. Your GitLab server is now able to connect to Bitbucket over SSH. Continue to step 2: - -### Step 2: Public key - -To be able to access repositories on Bitbucket, GitLab will automatically register your public key with Bitbucket as a deploy key for the repositories to be imported. Your public key needs to be at `~/.ssh/bitbucket_rsa.pub`, which will expand to `/home/git/.ssh/bitbucket_rsa.pub` in most configurations. - -If you have that file in place, you're all set and should see the "Import projects from Bitbucket" option enabled. If you don't, do the following: - -1. Create a new SSH key: - - ```sh - sudo -u git -H ssh-keygen - ``` - - When asked `Enter file in which to save the key` specify the correct path, eg. `/home/git/.ssh/bitbucket_rsa`. - Make sure to use an **empty passphrase**. - -2. Restart GitLab to allow it to find the new public key. - -You should now see the "Import projects from Bitbucket" option on the New Project page enabled. diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md deleted file mode 100644 index 96755707dee..00000000000 --- a/doc/integration/external-issue-tracker.md +++ /dev/null @@ -1,39 +0,0 @@ -# External issue tracker - -GitLab has a great issue tracker but you can also use an external issue tracker such as Jira, Bugzilla or Redmine. You can configure issue trackers per GitLab project. For instance, if you configure Jira it allows you to do the following: - -- the 'Issues' link on the GitLab project pages takes you to the appropriate Jira issue index; -- clicking 'New issue' on the project dashboard creates a new Jira issue; -- To reference Jira issue PROJECT-1234 in comments, use syntax PROJECT-1234. Commit messages get turned into HTML links to the corresponding Jira issue. - - - -GitLab Enterprise Edition contains [advanced JIRA support](http://doc.gitlab.com/ee/integration/jira.html). - -## Configuration - -### Project Service - -You can enable an external issue tracker per project. As an example, we will configure `Redmine` for project named gitlab-ci. - -Fill in the required details on the page: - - - -* `description` A name for the issue tracker (to differentiate between instances, for example). -* `project_url` The URL to the project in Redmine which is being linked to this GitLab project. -* `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. -The admin can add a service template that sets a default for each project. This makes it much easier to configure individual projects. - -In GitLab Admin section, navigate to `Service Templates` and choose the service template you want to create: - - - -After the template is created, the template details will be pre-filled on the project service page. - -Support to add your commits to the Jira ticket automatically is [available in GitLab EE](http://doc.gitlab.com/ee/integration/jira.html). diff --git a/doc/integration/github.md b/doc/integration/github.md deleted file mode 100644 index b64501c2aaa..00000000000 --- a/doc/integration/github.md +++ /dev/null @@ -1,79 +0,0 @@ -# Integrate your server with GitHub - -Import projects from GitHub and login to your GitLab instance with your GitHub account. - -To enable the GitHub OmniAuth provider you must register your application with GitHub. -GitHub will generate an application ID and secret key for you to use. - -1. Sign in to GitHub. - -1. Navigate to your individual user settings or an organization's settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or an organization - that is entirely up to you. - -1. Select "Applications" in the left menu. - -1. Select "Register new application". - -1. Provide the required details. - - Application name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or something else descriptive. - - Homepage URL: The URL to your GitLab installation. 'https://gitlab.company.com' - - Application description: Fill this in if you wish. - - Authorization callback URL: 'https://gitlab.company.com/' -1. Select "Register application". - -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. -  - -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 - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial 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" } - } - ] - ``` - - For installation from source: - - ``` - - { 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. - -1. Change 'YOUR_APP_SECRET' to the client secret from the GitHub application page from step 7. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a GitHub icon below the regular sign in form. -Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application. -If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/github_app.png b/doc/integration/github_app.png Binary files differdeleted file mode 100644 index d890345ced9..00000000000 --- a/doc/integration/github_app.png +++ /dev/null diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md deleted file mode 100644 index 216f1f11a9b..00000000000 --- a/doc/integration/gitlab.md +++ /dev/null @@ -1,84 +0,0 @@ -# Integrate your server with GitLab.com - -Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account. - -To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com. -GitLab.com will generate an application ID and secret key for you to use. - -1. Sign in to GitLab.com - -1. Navigate to your profile settings. - -1. Select "Applications" in the left menu. - -1. Select "New application". - -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: - - ``` - 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 Client ID and Client Secret near the top right of the page (see screenshot). - Keep this page open as you continue configuration. -  - -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 - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial 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" } - } - ] - ``` - - For installations from source: - - ``` - - { 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.com application page. - -1. Change 'YOUR_APP_SECRET' to the secret from the GitLab.com application page. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -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_actions.png b/doc/integration/gitlab_actions.png Binary files differdeleted file mode 100644 index b08f54d137b..00000000000 --- a/doc/integration/gitlab_actions.png +++ /dev/null diff --git a/doc/integration/gitlab_app.png b/doc/integration/gitlab_app.png Binary files differdeleted file mode 100644 index 3f9391a821b..00000000000 --- a/doc/integration/gitlab_app.png +++ /dev/null diff --git a/doc/integration/gitlab_buttons_in_gmail.md b/doc/integration/gitlab_buttons_in_gmail.md deleted file mode 100644 index a9885cef109..00000000000 --- a/doc/integration/gitlab_buttons_in_gmail.md +++ /dev/null @@ -1,28 +0,0 @@ -# GitLab buttons in Gmail - -GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). - -If correctly setup, emails that require an action will be marked in Gmail. - - - -To get this functioning, you need to be registered with Google. -[See how to register with google in this document.](https://developers.google.com/gmail/markup/registering-with-google) - -To aid the registering with google, GitLab offers a rake task that will send an email to google whitelisting email address from your GitLab server. - -To check what would be sent to the google email address, run the rake task: - -```bash -bundle exec rake gitlab:mail_google_schema_whitelisting RAILS_ENV=production -``` - -**This will not send the email but give you the output of how the mail will look.** - -Copy the output of the rake task to [google email markup tester](https://www.google.com/webmasters/markup-tester/u/0/) and press "Validate". - -If you receive "No errors detected" message from the tester you can send the email using: - -```bash -bundle exec rake gitlab:mail_google_schema_whitelisting RAILS_ENV=production SEND=true -``` diff --git a/doc/integration/google.md b/doc/integration/google.md deleted file mode 100644 index e1c14c7c948..00000000000 --- a/doc/integration/google.md +++ /dev/null @@ -1,89 +0,0 @@ -# Google OAuth2 OmniAuth Provider - -To enable the Google OAuth2 OmniAuth provider you must register your application with Google. Google will generate a client ID and secret key for you to use. - -1. Sign in to the [Google Developers Console](https://console.developers.google.com/) with the Google account you want to use to register GitLab. - -1. Select "Create Project". - -1. Provide the project information - - Project name: 'GitLab' works just fine here. - - Project ID: Must be unique to all Google Developer registered applications. Google provides a randomly generated Project ID by default. You can use the randomly generated ID or choose a new one. -1. Refresh the page. You should now see your new project in the list. Click on the project. - -1. Select "APIs & auth" in the left menu. - -1. Select "APIs" in the submenu. - - Enable `Contacts API` - - Enable `Google+ API` - -1. Select "Credentials" in the submenu. - -1. Select "Create New Client ID". - -1. Fill in the required information - - Application type: "Web Application" - - Authorized JavaScript origins: This isn't really used by GitLab but go ahead and put 'https://gitlab.example.com' here. - - 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.  - -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 - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial 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" => '' } - } - ] - ``` - - For installations from source: - - ``` - - { 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 Google Developer page from step 10. - -1. Change 'YOUR_APP_SECRET' to the client secret from the Google Developer page from step 10. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Google icon below the regular sign in form. Click the icon to begin the authentication process. Google will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. - -## Further Configuration - -This further configuration is not required for Google authentication to function but it is strongly recommended. Taking these steps will increase usability for users by providing a little more recognition and branding. - -At this point, when users first try to authenticate to your GitLab installation with Google they will see a generic application name on the prompt screen. The prompt informs the user that "Project Default Service Account" would like to access their account. "Project Default Service Account" isn't very recognizable and may confuse or cause users to be concerned. This is easily changeable. - -1. Select 'Consent screen' in the left menu. (See steps 1, 4 and 5 above for instructions on how to get here if you closed your window). -1. Scroll down until you find "Product Name". Change the product name to something more descriptive. -1. Add any additional information as you wish - homepage, logo, privacy policy, etc. None of this is required, but it may help your users. diff --git a/doc/integration/google_app.png b/doc/integration/google_app.png Binary files differdeleted file mode 100644 index 5a62ad35009..00000000000 --- a/doc/integration/google_app.png +++ /dev/null diff --git a/doc/integration/jira-integration-points.png b/doc/integration/jira-integration-points.png Binary files differdeleted file mode 100644 index 0692a7b458a..00000000000 --- a/doc/integration/jira-integration-points.png +++ /dev/null diff --git a/doc/integration/ldap.md b/doc/integration/ldap.md deleted file mode 100644 index b67f793c591..00000000000 --- a/doc/integration/ldap.md +++ /dev/null @@ -1,148 +0,0 @@ -# GitLab LDAP integration - -GitLab can be configured to allow your users to sign with their LDAP credentials to integrate with e.g. Active Directory. - -The first time a user signs in with LDAP credentials, GitLab will create a new GitLab user associated with the LDAP Distinguished Name (DN) of the LDAP user. - -GitLab user attributes such as nickname and email will be copied from the LDAP user entry. - -## Configuring GitLab for LDAP integration - -To enable GitLab LDAP integration you need to add your LDAP server settings in `/etc/gitlab/gitlab.rb` or `/home/git/gitlab/config/gitlab.yml`. -In GitLab Enterprise Edition you can have multiple LDAP servers connected to one GitLab server. - -Please note that before version 7.4, GitLab used a different syntax for configuring LDAP integration. -The old LDAP integration syntax still works in GitLab 7.4. -If your `gitlab.rb` or `gitlab.yml` file contains LDAP settings in both the old syntax and the new syntax, only the __old__ syntax will be used by GitLab. - -```ruby -# For omnibus packages -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 - ## label - # - # A human-friendly name for your LDAP server. It is OK to change the label later, - # for instance if you find out it is too large to fit on the web page. - # - # Example: 'Paris' or 'Acme, Ltd.' - label: 'LDAP' - - host: '_your_ldap_server' - port: 389 - uid: 'sAMAccountName' - method: 'plain' # "tls" or "ssl" or "plain" - bind_dn: '_the_full_dn_of_the_user_you_will_bind_with' - password: '_the_password_of_the_bind_user' - - # This setting specifies if LDAP server is Active Directory LDAP server. - # For non AD servers it skips the AD specific queries. - # If your LDAP server is not AD, set this to false. - active_directory: true - - # If allow_username_or_email_login is enabled, GitLab will ignore everything - # after the first '@' in the LDAP username submitted by the user on login. - # - # Example: - # - the user enters 'jane.doe@example.com' and 'p@ssw0rd' as LDAP credentials; - # - GitLab queries the LDAP server with 'jane.doe' and 'p@ssw0rd'. - # - # If you are using "uid: 'userPrincipalName'" on ActiveDirectory you need to - # disable this setting, because the userPrincipalName contains an '@'. - allow_username_or_email_login: false - - # To maintain tight control over the number of active users on your GitLab installation, - # enable this setting to keep new users blocked until they have been cleared by the admin - # (default: false). - block_auto_created_users: false - - # Base where we can search for users - # - # Ex. ou=People,dc=gitlab,dc=example - # - base: '' - - # Filter LDAP users - # - # Format: RFC 4515 http://tools.ietf.org/search/rfc4515 - # Ex. (employeeType=developer) - # - # Note: GitLab does not support omniauth-ldap's custom filter syntax. - # - user_filter: '' - -# GitLab EE only: add more LDAP servers -# Choose an ID made of a-z and 0-9 . This ID will be stored in the database -# so that GitLab can remember which LDAP server a user belongs to. -# uswest2: -# label: -# host: -# .... -EOS -``` - -If you are getting 'Connection Refused' errors when trying to connect to the LDAP server please double-check the LDAP `port` and `method` settings used by GitLab. -Common combinations are `method: 'plain'` and `port: 389`, OR `method: 'ssl'` and `port: 636`. - -If you are using a GitLab installation from source you can find the LDAP settings in `/home/git/gitlab/config/gitlab.yml`: - -``` -production: - # snip... - ldap: - enabled: false - servers: - main: # 'main' is the GitLab 'provider ID' of this LDAP server - ## label - # - # A human-friendly name for your LDAP server. It is OK to change the label later, - # for instance if you find out it is too large to fit on the web page. - # - # Example: 'Paris' or 'Acme, Ltd.' - label: 'LDAP' - # snip... -``` - -## Enabling LDAP sign-in for existing GitLab users - -When a user signs in to GitLab with LDAP for the first time, and their LDAP email address is the primary email address of an existing GitLab user, then the LDAP DN will be associated with the existing user. - -If the LDAP email attribute is not found in GitLab's database, a new user is created. - -In other words, if an existing GitLab user wants to enable LDAP sign-in for themselves, they should check that their GitLab email address matches their LDAP email address, and then sign into GitLab via their LDAP credentials. - -GitLab recognizes the following LDAP attributes as email addresses: `mail`, `email` and `userPrincipalName`. - -If multiple LDAP email attributes are present, e.g. `mail: foo@bar.com` and `email: foo@example.com`, then the first attribute found wins -- in this case `foo@bar.com`. - -## Using an LDAP filter to limit access to your GitLab server - -If you want to limit all GitLab access to a subset of the LDAP users on your LDAP server you can set up an LDAP user filter. -The filter must comply with [RFC 4515](http://tools.ietf.org/search/rfc4515). - -```ruby -# For omnibus packages; new LDAP server syntax -gitlab_rails['ldap_servers'] = YAML.load <<-EOS -main: - # snip... - user_filter: '(employeeType=developer)' -EOS -``` - -```yaml -# For installations from source; new LDAP server syntax -production: - ldap: - servers: - main: - # snip... - user_filter: '(employeeType=developer)' -``` - -Tip: if you want to limit access to the nested members of an Active Directory group you can use the following syntax: - -``` -(memberOf:1.2.840.113556.1.4.1941:=CN=My Group,DC=Example,DC=com) -``` - -Please note that GitLab does not support the custom filter syntax used by omniauth-ldap. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md deleted file mode 100644 index 192c321f712..00000000000 --- a/doc/integration/oauth_provider.md +++ /dev/null @@ -1,35 +0,0 @@ -## 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. -Mostly, OAuth2 is using for SSO (Single sign-on). But you can find a lot of different usages for this functionality. -For example, our feature 'GitLab Importer' is using OAuth protocol to give an access to repositories without sharing user credentials to GitLab.com account. -Also GitLab.com application can be used for authentication to your GitLab instance if needed [GitLab OmniAuth](gitlab.md). - -GitLab has two ways to add new OAuth2 application to an instance, you can add application as regular user and through admin area. So GitLab actually can have an instance-wide and a user-wide applications. There is no defferences between them except the different permission levels. - -### Adding application through profile -Go to your profile section 'Application' and press button 'New Application' - - - -After this you will see application form, where "Name" is arbitrary name, "Redirect URI" is URL in your app where users will be sent after authorization on GitLab.com. - - - -### Authorized application -Every application you authorized will be shown in your "Authorized application" sections. - - - -At any time you can revoke access just clicking button "Revoke" - -### OAuth applications in admin area - -If you want to create application that does not belong to certain user you can create it from admin area - -
\ No newline at end of file diff --git a/doc/integration/oauth_provider/admin_application.png b/doc/integration/oauth_provider/admin_application.png Binary files differdeleted file mode 100644 index a5f34512aa8..00000000000 --- a/doc/integration/oauth_provider/admin_application.png +++ /dev/null diff --git a/doc/integration/oauth_provider/application_form.png b/doc/integration/oauth_provider/application_form.png Binary files differdeleted file mode 100644 index ae135db2627..00000000000 --- a/doc/integration/oauth_provider/application_form.png +++ /dev/null diff --git a/doc/integration/oauth_provider/authorized_application.png b/doc/integration/oauth_provider/authorized_application.png Binary files differdeleted file mode 100644 index d3ce05be9cc..00000000000 --- a/doc/integration/oauth_provider/authorized_application.png +++ /dev/null diff --git a/doc/integration/oauth_provider/user_wide_applications.png b/doc/integration/oauth_provider/user_wide_applications.png Binary files differdeleted file mode 100644 index 719e1974068..00000000000 --- a/doc/integration/oauth_provider/user_wide_applications.png +++ /dev/null diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md deleted file mode 100644 index 24f7b4bb4b4..00000000000 --- a/doc/integration/omniauth.md +++ /dev/null @@ -1,127 +0,0 @@ -# OmniAuth - -GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and other popular services. - -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) -- [Enable OmniAuth for an Existing User](#enable-omniauth-for-an-existing-user) -- [OmniAuth configuration sample when using Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master#omniauth-google-twitter-github-login) - -## Initial OmniAuth Configuration - -Before configuring individual OmniAuth providers there are a few global settings that are in common for all providers that we need to consider. - -- 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 - - sudo -u git -H editor config/gitlab.yml - ``` - - and change the following section - - ``` - ## OmniAuth settings - omniauth: - # Allow login via Twitter, Google, etc. using OmniAuth providers - enabled: true - - # CAUTION! - # This allows users to login without having a user account first (default: false). - # User accounts will be created automatically when authentication was successful. - allow_single_sign_on: false - # Locks down those users until they have been cleared by the admin (default: true). - block_auto_created_users: true - ``` - -Now we can choose one or more of the Supported Providers below to continue configuration. - -## Supported Providers - -- [GitHub](github.md) -- [Bitbucket](bitbucket.md) -- [GitLab.com](gitlab.md) -- [Google](google.md) -- [Shibboleth](shibboleth.md) -- [Twitter](twitter.md) - -## Enable OmniAuth for an Existing User - -Existing users can enable OmniAuth for specific providers after the account is created. For example, if the user originally signed in with LDAP an OmniAuth provider such as Twitter can be enabled. Follow the steps below to enable an OmniAuth provider for an existing user. - -1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider. -1. Go to profile settings (the silhouette icon in the top right corner). -1. Select the "Account" tab. -1. Under "Social Accounts" select the desired OmniAuth provider, such as Twitter. -1. The user will be redirected to the provider. Once the user authorized GitLab they will be redirected back to GitLab. - -The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on. - -## Using Custom Omniauth Providers - -GitLab uses [Omniauth](http://www.omniauth.org/) for authentication and already ships with a few providers preinstalled (e.g. LDAP, GitHub, Twitter). But sometimes that is not enough and you need to integrate with other authentication solutions. For these cases you can use the Omniauth provider. - -### Steps - -These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation. - -- Stop GitLab: - - sudo service gitlab stop - -- Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/Gemfile): - - gem "omniauth-your-auth-provider" - -- If you're using MySQL, install the new Omniauth provider gem by running the following command: - - sudo -u git -H bundle install --without development test postgres --path vendor/bundle --no-deployment - -- If you're using PostgreSQL, install the new Omniauth provider gem by running the following command: - - sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment - - > These are the same commands you used in the [Install Gems section](#install-gems) with `--path vendor/bundle --no-deployment` instead of `--deployment`. - -- Start GitLab: - - sudo service gitlab start - -### Examples - -If you have successfully set up a provider that is not shipped with GitLab itself, please let us know. - -You can help others by reporting successful configurations and probably share a few insights or provide warnings for common errors or pitfalls by sharing your experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). - -While we can't officially support every possible authentication mechanism out there, we'd like to at least help those with specific needs. diff --git a/doc/integration/redmine_configuration.png b/doc/integration/redmine_configuration.png Binary files differdeleted file mode 100644 index 6b145363229..00000000000 --- a/doc/integration/redmine_configuration.png +++ /dev/null diff --git a/doc/integration/redmine_service_template.png b/doc/integration/redmine_service_template.png Binary files differdeleted file mode 100644 index 1159eb5b964..00000000000 --- a/doc/integration/redmine_service_template.png +++ /dev/null diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md deleted file mode 100644 index 6258e5f1030..00000000000 --- a/doc/integration/shibboleth.md +++ /dev/null @@ -1,78 +0,0 @@ -# Shibboleth OmniAuth Provider - -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. - - -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. -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) - -Following changes are needed to enable shibboleth: - -protect omniauth-shibboleth callback URL: -``` - <Location /users/auth/shibboleth/callback> - AuthType shibboleth - ShibRequestSetting requireSession 1 - ShibUseHeaders On - require valid-user - </Location> - - Alias /shibboleth-sp /usr/share/shibboleth - <Location /shibboleth-sp> - Satisfy any - </Location> - - <Location /Shibboleth.sso> - SetHandler shib - </Location> -``` -exclude shibboleth URLs from rewriting, add "RewriteCond %{REQUEST_URI} !/Shibboleth.sso" and "RewriteCond %{REQUEST_URI} !/shibboleth-sp", config should look like this: -``` - # Apache equivalent of Nginx try files - RewriteEngine on - RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f - 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. - -File should look like this: -``` -external_url 'https://gitlab.example.com' -gitlab_rails['internal_api_url'] = 'https://gitlab.example.com' - -# disable Nginx -nginx['enable'] = false - -gitlab_rails['omniauth_allow_single_sign_on'] = true -gitlab_rails['omniauth_block_auto_created_users'] = false -gitlab_rails['omniauth_enabled'] = true -gitlab_rails['omniauth_providers'] = [ - { - "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. Save changes and reconfigure gitlab: -``` -sudo gitlab-ctl reconfigure -``` - -On the sign in page there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You will be redirected to IdP server (Depends on your Shibboleth module configuration). If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/slack.md b/doc/integration/slack.md deleted file mode 100644 index 2fd22c513ad..00000000000 --- a/doc/integration/slack.md +++ /dev/null @@ -1,42 +0,0 @@ -# Slack integration - -## On Slack - -To enable Slack integration you must create an Incoming WebHooks integration on Slack; - -1. [Sign in to Slack](https://slack.com/signin) - -1. Select **Configure Integrations** from the dropdown next to your team name. - -1. Select the **All Services** tab - -1. Click **Add** next to Incoming Webhooks - -1. Pick Incoming WebHooks - -1. Choose the channel name you want to send notifications to - -1. Click **Add Incoming WebHooks Integration**Add Integrations. - - Optional step; You can change bot's name and avatar by clicking modifying the bot name or avatar under **Integration Settings**. - -1. Copy the **Webhook URL**, we'll need this later for GitLab. - - -## On GitLab - -After Slack is ready we need to setup GitLab. Here are the steps to achieve this. - -1. Sign in to GitLab - -1. Pick the repository you want. - -1. Navigate to Settings -> Services -> Slack - -1. Fill in your Slack details - - - Mark it as active - - Paste in the webhook URL you got from Slack - -Have fun :) - -*P.S. You can set "branch,pushed,Compare changes" as highlight words on your Slack profile settings, so that you can be aware of new commits when somebody pushes them.* diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md deleted file mode 100644 index fe9091ad9a8..00000000000 --- a/doc/integration/twitter.md +++ /dev/null @@ -1,81 +0,0 @@ -# Twitter OAuth2 OmniAuth Provider - -To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client ID and secret key for you to use. - -1. Sign in to [Twitter Developers](https://dev.twitter.com/) area. - -1. Hover over the avatar in the top right corner and select "My applications." - -1. Select "Create new app" - -1. Fill in the application details. - - Name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or - something else descriptive. - - Description: Create a description. - - Website: The URL to your GitLab installation. 'https://gitlab.example.com' - - Callback URL: 'https://gitlab.example.com/users/auth/twitter/callback' - - Agree to the "Rules of the Road." - -  -1. Select "Create your Twitter application." - -1. Select the "Settings" tab. - -1. Underneath the Callback URL check the box next to "Allow this application to be used to Sign in the Twitter." - -1. Select "Update settings" at the bottom to save changes. - -1. Select the "API Keys" tab. - -1. You should now see an API key and API secret (see screenshot). Keep this page open as you continue configuration. - -  - -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 - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial 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" - } - ] - ``` - - For installations from source: - - ``` - - { 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. - -1. Change 'YOUR_APP_SECRET' to the API secret from the Twitter page in step 11. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/twitter_app_api_keys.png b/doc/integration/twitter_app_api_keys.png Binary files differdeleted file mode 100644 index 1076337172a..00000000000 --- a/doc/integration/twitter_app_api_keys.png +++ /dev/null diff --git a/doc/integration/twitter_app_details.png b/doc/integration/twitter_app_details.png Binary files differdeleted file mode 100644 index b95e8af8a74..00000000000 --- a/doc/integration/twitter_app_details.png +++ /dev/null |
