From 8e3f1fa629a61741282214b293c1bc9438aada59 Mon Sep 17 00:00:00 2001 From: tduehr Date: Wed, 11 Nov 2015 22:25:31 -0600 Subject: add CAS authentication support --- doc/integration/cas.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 doc/integration/cas.md (limited to 'doc/integration') diff --git a/doc/integration/cas.md b/doc/integration/cas.md new file mode 100644 index 00000000000..3490f6a38e0 --- /dev/null +++ b/doc/integration/cas.md @@ -0,0 +1,62 @@ +# CAS OmniAuth Provider + +To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL gitlab will supply to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for backchannel logout. + +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: "cas3", + label: "cas", + args: { + url: 'CAS_SERVER', + login_url: '/CAS_PATH/login', + service_validate_url: '/CAS_PATH/p3/serviceValidate', + logout_url: '/CAS_PATH/logout'} } + } + } + ] + ``` + + For installations from source: + + ``` + - { name: 'cas3', + label: 'cas', + args: { + url: 'CAS_SERVER', + login_url: '/CAS_PATH/login', + service_validate_url: '/CAS_PATH/p3/serviceValidate', + logout_url: '/CAS_PATH/logout'} } + ``` + +1. Change 'CAS_PATH' to the root of your CAS instance (ie. `cas`). + +1. If your CAS instance does not use default TGC lifetimes, update the `cas3.session_duration` to at least the current TGC maximum lifetime. To explicitly disable SLO, regardless of CAS settings, set this to 0. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a CAS tab in the sign in form. \ No newline at end of file -- cgit v1.2.1 From f177aaa5fa789654dc440d6ec4ae3546544c1401 Mon Sep 17 00:00:00 2001 From: Drew Blessing Date: Thu, 17 Dec 2015 16:08:14 -0600 Subject: Backport JIRA service --- doc/integration/README.md | 1 + doc/integration/jira.md | 113 +++++++++++++++++++++++++++ doc/integration/jira_issue_reference.png | Bin 0 -> 39942 bytes doc/integration/jira_project_name.png | Bin 0 -> 60598 bytes doc/integration/jira_service.png | Bin 0 -> 59082 bytes doc/integration/jira_service_close_issue.png | Bin 0 -> 88433 bytes doc/integration/jira_service_page.png | Bin 0 -> 162449 bytes doc/integration/jira_workflow_screenshot.png | Bin 0 -> 121534 bytes 8 files changed, 114 insertions(+) create mode 100644 doc/integration/jira.md create mode 100644 doc/integration/jira_issue_reference.png create mode 100644 doc/integration/jira_project_name.png create mode 100644 doc/integration/jira_service.png create mode 100644 doc/integration/jira_service_close_issue.png create mode 100644 doc/integration/jira_service_page.png create mode 100644 doc/integration/jira_workflow_screenshot.png (limited to 'doc/integration') diff --git a/doc/integration/README.md b/doc/integration/README.md index eff39a626ae..8ea4111bc8a 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -4,6 +4,7 @@ GitLab integrates with multiple third-party services to allow external issue tra See the documentation below for details on how to configure these services. +- [Jira](jira.md) Integrate with the JIRA issue tracker - [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. diff --git a/doc/integration/jira.md b/doc/integration/jira.md new file mode 100644 index 00000000000..624601d0fac --- /dev/null +++ b/doc/integration/jira.md @@ -0,0 +1,113 @@ +# GitLab Jira integration + +GitLab can be configured to interact with Jira. +Configuration happens via username and password. +Connecting to a Jira server via CAS is not possible. + +Each project can be configured to connect to a different Jira instance, configuration is explained [here](#configuration). +If you have one Jira instance you can pre-fill the settings page with a default template. To configure the template [see external issue tracker document](external-issue-tracker.md#service-template)). + +Once the project is connected to Jira, you can reference and close the issues in Jira directly from GitLab. + + +## Table of Contents + +* [Referencing Jira Issues from GitLab](#referencing-jira-issues) +* [Closing Jira Issues from GitLab](#closing-jira-issues) +* [Configuration](#configuration) + +### Referencing Jira Issues + +When GitLab project has Jira issue tracker configured and enabled, mentioning Jira issue in GitLab will automatically add a comment in Jira issue with the link back to GitLab. This means that in comments in merge requests and commits referencing an issue, eg. `PROJECT-7`, will add a comment in Jira issue in the format: + + +``` + USER mentioned this issue in LINK_TO_THE_MENTION +``` + +* `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. +* `LINK_TO_THE_MENTION` Link to the origin of mention with a name of the entity where Jira issue was mentioned. +Can be commit or merge request. + + +![example of mentioning or closing the Jira issue](jira_issue_reference.png) + + +### Closing Jira Issues + +Jira issues can be closed directly from GitLab by using trigger words, eg. `Resolves PROJECT-1`, `Closes PROJECT-1` or `Fixes PROJECT-1`, in commits and merge requests. +When a commit which contains the trigger word in the commit message is pushed, GitLab will add a comment in the mentioned Jira issue. + +For example, for project named PROJECT in Jira, we implemented a new feature and created a merge request in GitLab. + +This feature was requested in Jira issue PROJECT-7. Merge request in GitLab contains the improvement and in merge request description we say that this merge request `Closes PROJECT-7` issue. + +Once this merge request is merged, Jira issue will be automatically closed with a link to the commit that resolved the issue. + +![A Git commit that causes the Jira issue to be closed](merge_request_close_jira.png) + + +![The GitLab integration user leaves a comment on Jira](jira_service_close_issue.png) + + +## Configuration + +### Configuring JIRA + +We need to create a user in JIRA which will have access to all projects that need to integrate with GitLab. +Login to your JIRA instance as admin and under Administration go to User Management and create a new user. +As an example, we'll create a user named `gitlab` and add it to `jira-developers` group. + +**It is important that the user `gitlab` has write-access to projects in JIRA** + +### Configuring GitLab + +### GitLab 7.8 EE and up with JIRA v6.x + +To enable JIRA integration in a project, navigate to the project Settings page and go to Services. Here you will find JIRA. + +Fill in the required details on the page: + +![Jira service page](jira_service_page.png) + +* `description` A name for the issue tracker (to differentiate between instances, for instance). +* `project url` The URL to the JIRA project which is being linked to this GitLab project. +* `issues url` The URL to the JIRA project issues overview for the project that is linked to this GitLab project. +* `new issue url` This is the URL to create a new issue in JIRA for the project linked to this GitLab project. +* `api url` The base URL of the JIRA API. It may be omitted, in which case GitLab will automatically use API version `2` based on the `project url`, i.e. `https://jira.example.com/rest/api/2`. +* `username` The username of the user created in [configuring JIRA step](#configuring-jira). +* `password` The password of the user created in [configuring JIRA step](#configuring-jira). +* `Jira issue transition` This is the id of a transition that moves issues to a closed state. You can find this number under [JIRA workflow administration, see screenshot](jira_workflow_screenshot.png). By default, this id is `2`. (In the example image, this is `2` as well) + +After saving the configuration, your GitLab project will be able to interact with the linked JIRA project. + + +### GitLab 6.x-7.7 with JIRA v6.x + +**Note: GitLab 7.8 and up contain various integration improvements. We strongly recommend upgrading.** + + +In `gitlab.yml` enable [JIRA issue tracker section by uncommenting the lines](https://gitlab.com/subscribers/gitlab-ee/blob/6-8-stable-ee/config/gitlab.yml.example#L111-115). +This will make sure that all issues within GitLab are pointing to the JIRA issue tracker. + +We can also enable JIRA service that will allow us to interact with JIRA issues. + +For example, we can close issues in JIRA by a commit in GitLab. + +Go to project settings page and fill in the project name for the JIRA project: + +![Set the JIRA project name in GitLab to 'NEW'](jira_project_name.png) + +Next, go to the services page and find JIRA. + +![Jira services page](jira_service.png) + +1. Tick the active check box to enable the service. +1. Supply the url to JIRA server, for example http://jira.sample +1. Supply the username of a user we created under `Configuring JIRA` section, for example `gitlab` +1. Supply the password of the user +1. Optional: supply the JIRA api version, default is version +1. Optional: supply the JIRA issue transition ID (issue transition to closed). This is dependant on JIRA settings, default is 2 +1. Save + +Now we should be able to interact with JIRA issues. diff --git a/doc/integration/jira_issue_reference.png b/doc/integration/jira_issue_reference.png new file mode 100644 index 00000000000..15739a22dc7 Binary files /dev/null and b/doc/integration/jira_issue_reference.png differ diff --git a/doc/integration/jira_project_name.png b/doc/integration/jira_project_name.png new file mode 100644 index 00000000000..5986fdb63fb Binary files /dev/null and b/doc/integration/jira_project_name.png differ diff --git a/doc/integration/jira_service.png b/doc/integration/jira_service.png new file mode 100644 index 00000000000..1f6628c4371 Binary files /dev/null and b/doc/integration/jira_service.png differ diff --git a/doc/integration/jira_service_close_issue.png b/doc/integration/jira_service_close_issue.png new file mode 100644 index 00000000000..67dfc6144c4 Binary files /dev/null and b/doc/integration/jira_service_close_issue.png differ diff --git a/doc/integration/jira_service_page.png b/doc/integration/jira_service_page.png new file mode 100644 index 00000000000..69ec44e826f Binary files /dev/null and b/doc/integration/jira_service_page.png differ diff --git a/doc/integration/jira_workflow_screenshot.png b/doc/integration/jira_workflow_screenshot.png new file mode 100644 index 00000000000..8635a32eb68 Binary files /dev/null and b/doc/integration/jira_workflow_screenshot.png differ -- cgit v1.2.1 From 7fc2422c8d660d310b819b2b6ffbca9a9e4d8cd6 Mon Sep 17 00:00:00 2001 From: Douwe Maan Date: Mon, 21 Dec 2015 17:37:55 +0100 Subject: Add link to CAS doc --- doc/integration/README.md | 1 + doc/integration/cas.md | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) (limited to 'doc/integration') diff --git a/doc/integration/README.md b/doc/integration/README.md index eff39a626ae..50213f500b9 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -8,6 +8,7 @@ See the documentation below for details on how to configure these services. - [LDAP](ldap.md) Set up sign in via LDAP - [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, GitLab, and Google via OAuth. - [SAML](saml.md) Configure GitLab as a SAML 2.0 Service Provider +- [CAS](cas.md) Configure GitLab to sign in using CAS - [Slack](slack.md) Integrate with the Slack chat service - [OAuth2 provider](oauth_provider.md) OAuth2 application creation - [Gmail actions buttons](gmail_action_buttons_for_gitlab.md) Adds GitLab actions to messages diff --git a/doc/integration/cas.md b/doc/integration/cas.md index 3490f6a38e0..e6b2071f193 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -1,6 +1,6 @@ # CAS OmniAuth Provider -To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL gitlab will supply to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for backchannel logout. +To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab will supply to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for backchannel logout. 1. On your GitLab server, open the configuration file. @@ -10,7 +10,7 @@ To enable the CAS OmniAuth provider you must register your application with your sudo editor /etc/gitlab/gitlab.rb ``` - For instalations from source: + For installations from source: ```sh cd /home/git/gitlab @@ -59,4 +59,4 @@ To enable the CAS OmniAuth provider you must register your application with your 1. Restart GitLab for the changes to take effect. -On the sign in page there should now be a CAS tab in the sign in form. \ No newline at end of file +On the sign in page there should now be a CAS tab in the sign in form. -- cgit v1.2.1 From 9e0f532f3eca474bbb4bdf49ea744afb23178b82 Mon Sep 17 00:00:00 2001 From: Stan Hu Date: Sun, 27 Dec 2015 20:36:33 -0800 Subject: Add documentation for using reCAPTCHA --- doc/integration/README.md | 1 + doc/integration/recaptcha.md | 56 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 doc/integration/recaptcha.md (limited to 'doc/integration') diff --git a/doc/integration/README.md b/doc/integration/README.md index 6263353851f..2a9f76533b7 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -13,6 +13,7 @@ See the documentation below for details on how to configure these services. - [Slack](slack.md) Integrate with the Slack chat service - [OAuth2 provider](oauth_provider.md) OAuth2 application creation - [Gmail actions buttons](gmail_action_buttons_for_gitlab.md) Adds GitLab actions to messages +- [reCAPTCHA](recaptcha.md) Configure GitLab to use Google reCAPTCHA for new users 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). diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md new file mode 100644 index 00000000000..7e6f7e7e30a --- /dev/null +++ b/doc/integration/recaptcha.md @@ -0,0 +1,56 @@ +# reCAPTCHA + +GitLab leverages [Google's reCAPTCHA](https://www.google.com/recaptcha/intro/index.html) +to protect against spam and abuse. GitLab displays the CAPTCHA form on the sign-up page +to confirm that a real user, not a bot, is attempting to create an account. + +## Configuration + +To use reCAPTCHA, first you must create a public and private key. + +1. Go to the URL: https://www.google.com/recaptcha/admin + +1. Fill out the form necessary to obtain reCAPTCHA keys. + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. Enable reCAPTCHA and add the settings: + + For omnibus package: + + ```ruby + gitlab_rails['recaptcha_enabled'] = true + gitlab_rails['recaptcha_public_key'] = 'YOUR_PUBLIC_KEY' + gitlab_rails['recaptcha_private_key'] = 'YOUR_PUBLIC_KEY' + ``` + + For installation from source: + + ``` + recaptcha: + enabled: true + public_key: 'YOUR_PUBLIC_KEY' + private_key: 'YOUR_PRIVATE_KEY' + ``` + +1. Change 'YOUR_PUBLIC_KEY' to the public key from step 2. + +1. Change 'YOUR_PRIVATE_KEY' to the private key from step 2. + +1. Save the configuration file. + +1. Restart GitLab. -- cgit v1.2.1 From a3469d914aaf28a1184247cbe72e5197ce7ca006 Mon Sep 17 00:00:00 2001 From: Gabriel Mazetto Date: Mon, 28 Dec 2015 18:21:34 -0200 Subject: reCAPTCHA is configurable through Admin Settings, no reload needed. --- doc/integration/recaptcha.md | 47 +++++++------------------------------------- 1 file changed, 7 insertions(+), 40 deletions(-) (limited to 'doc/integration') diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 7e6f7e7e30a..a301d1a613c 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -6,51 +6,18 @@ to confirm that a real user, not a bot, is attempting to create an account. ## Configuration -To use reCAPTCHA, first you must create a public and private key. +To use reCAPTCHA, first you must create a site and private key. 1. Go to the URL: https://www.google.com/recaptcha/admin -1. Fill out the form necessary to obtain reCAPTCHA keys. +2. Fill out the form necessary to obtain reCAPTCHA keys. -1. On your GitLab server, open the configuration file. +3. Login to your GitLab server, with administrator credentials. - For omnibus package: +4. Go to Applications Settings on Admin Area (`admin/application_settings`) - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` +5. Fill all recaptcha fields with keys from previous steps - For installations from source: +6. Check the `Enable reCAPTCHA` checkbox - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. Enable reCAPTCHA and add the settings: - - For omnibus package: - - ```ruby - gitlab_rails['recaptcha_enabled'] = true - gitlab_rails['recaptcha_public_key'] = 'YOUR_PUBLIC_KEY' - gitlab_rails['recaptcha_private_key'] = 'YOUR_PUBLIC_KEY' - ``` - - For installation from source: - - ``` - recaptcha: - enabled: true - public_key: 'YOUR_PUBLIC_KEY' - private_key: 'YOUR_PRIVATE_KEY' - ``` - -1. Change 'YOUR_PUBLIC_KEY' to the public key from step 2. - -1. Change 'YOUR_PRIVATE_KEY' to the private key from step 2. - -1. Save the configuration file. - -1. Restart GitLab. +7. Save the configuration. -- cgit v1.2.1