Merge branch 'issue_49936' into 'master'

Allow JIRA to login using email and API token

Closes #49936

See merge request gitlab-org/gitlab-ce!21726

app/models/project_services/jira_service.rb

@@ -14,6 +14,9 @@ class JiraService < IssueTrackerService
             format: { with: Gitlab::Regex.jira_transition_id_regex, message: "transition ids can have only numbers which can be split with , or ;" },
             allow_blank: true
+  # JIRA cloud version is deprecating authentication via username and password.
+  # We should use username/password for JIRA server and email/api_token for JIRA cloud,
+  # for more information check: https://gitlab.com/gitlab-org/gitlab-ce/issues/49936.
   prop_accessor :username, :password, :url, :api_url, :jira_issue_transition_id, :title, :description
   before_update :reset_password
@@ -95,8 +98,8 @@ class JiraService < IssueTrackerService
     [
       { type: 'text', name: 'url', title: 'Web URL', placeholder: 'https://jira.example.com', required: true },
       { type: 'text', name: 'api_url', title: 'JIRA API URL', placeholder: 'If different from Web URL' },
-      { type: 'text', name: 'username', placeholder: '', required: true },
-      { type: 'password', name: 'password', placeholder: '', required: true },
+      { type: 'text', name: 'username', title: 'Username or Email', placeholder: 'Use a username for server version and an email for cloud version', required: true },
+      { type: 'password', name: 'password', title: 'Password or API token', placeholder: 'Use a password for server version and an API token for cloud version', required: true },
       { type: 'text', name: 'jira_issue_transition_id', title: 'Transition ID(s)', placeholder: 'Use , or ; to separate multiple transition IDs' }
     ]
   end

app/views/shared/_field.html.haml

@@ -24,6 +24,6 @@
     - elsif type == 'select'
       = form.select name, options_for_select(choices, value ? value : default_choice), {}, { class: "form-control", disabled: disabled}
     - elsif type == 'password'
-      = form.password_field name, autocomplete: "new-password", class: "form-control", required: value.blank? && required, disabled: disabled
+      = form.password_field name, autocomplete: "new-password", placeholder: placeholder, class: "form-control", required: value.blank? && required, disabled: disabled
     - if help
       %span.form-text.text-muted= help

changelogs/unreleased/issue_49936.yml

+---
+title: Update JIRA service UI to accept email and API token
+merge_request:
+author:
+type: other

doc/user/project/integrations/jira.md

@@ -45,56 +45,11 @@ project in Jira and then enter the correct values in GitLab.
 ### 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 the `Jira-developers`
-group.
-
-**It is important that the user `gitlab` has 'write' access to projects in Jira**
-
-We have split this stage in steps so it is easier to follow.
-
-1. Log in to your Jira instance as an administrator and under **Administration**
-   go to **User Management** to create a new user.
-
-     ![Jira user management link](img/jira_user_management_link.png)
-
-1. The next step is to create a new user (e.g., `gitlab`) who has write access
-   to projects in Jira. Enter the user's name and a _valid_ e-mail address
-   since Jira sends a verification e-mail to set up the password.
-   _**Note:** Jira creates the username automatically by using the e-mail
-   prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create 
-    an HTTP basic authentication password. You can do this by visiting the user 
-    profile, looking up the username, and setting a password._
-
-     ![Jira create new user](img/jira_create_new_user.png)
-
-1. Now, let's create a `gitlab-developers` group which will have write access
-   to projects in Jira. Go to the **Groups** tab and select **Create group**.
-
-     ![Jira create new user](img/jira_create_new_group.png)
-
-     Give it an optional description and click **Create group**.
-
-     ![Jira create new group](img/jira_create_new_group_name.png)
-
-1. To give the newly-created group 'write' access, go to
-   **Application access ➔ View configuration** and add the `gitlab-developers`
-   group to Jira Core.
-
-     ![Jira group access](img/jira_group_access.png)
-
-1. Add the `gitlab` user to the `gitlab-developers` group by going to
-   **Users ➔ GitLab user ➔ Add group** and selecting the `gitlab-developers`
-   group from the dropdown menu. Notice that the group says _Access_, which is
-   intended as part of this process.
-
-     ![Jira add user to group](img/jira_add_user_to_group.png)
-
-The Jira configuration is complete. Write down the new Jira username and its
-password as they will be needed when configuring GitLab in the next section.
+When connecting to **JIRA Server**, which supports basic authentication, a **username and password** are required. Check the link below and proceed to the next step:
+* [Setting up an user in JIRA server](jira_server_configuration.md)
+When connecting to **JIRA Cloud**, which supports authentication via API token, an **email and API token**, are required. Check the link below and proceed to the next step:
+* [Setting up an user in JIRA cloud](jira_cloud_configuration.md)
 ### Configuring GitLab
@@ -117,8 +72,8 @@ in the table below.
 | ----- | ----------- |
 | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://Jira.example.com`. |
 | `Jira API URL` | The base URL to the Jira instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. |
-| `Username` | The user name created in [configuring Jira step](#configuring-jira). Using the email address will cause `401 unauthorized`. |
-| `Password` |The password of the user created in [configuring Jira step](#configuring-jira). |
+| `Username/Email` | Created when [configuring Jira step](#configuring-jira). Use `username` for **JIRA server** or `email` for **JIRA cloud**. |
+| `Password/API token` |Created in [configuring Jira step](#configuring-jira). Use `password` for **JIRA server** or `API token` for **JIRA cloud**. |
 | `Transition ID` | This is the ID of a transition that moves issues to the desired state. It is possible to insert transition ids separated by `,` or `;` which means the issue will be moved to each state after another using the given order.  **Closing Jira issues via commits or Merge Requests won't work if you don't set the ID correctly.** |
 ### Obtaining a transition ID

doc/user/project/integrations/jira_cloud_configuration.md

+# Creating an API token in JIRA cloud
+
+An API token is needed when integrating with JIRA Cloud, follow the steps
+below to create one:
+
+1. Log in to https://id.atlassian.com with your email.
+2. **Click API tokens**, then **Create API token**.
+
+![JIRA API token](img/jira_api_token_menu.png)
+
+![JIRA API token](img/jira_api_token.png)
+
+3. Make sure to write down your new API token as you will need it in the next [steps](jira.md#configuring-gitlab).
+
+NOTE: **Note**
+It is important that the user associated with this email has 'write' access to projects in JIRA.
+
+The JIRA configuration is complete. You are going to need this new created token and the email you used to log in when [configuring GitLab in the next section](jira.md#configuring-gitlab).
+

doc/user/project/integrations/jira_server_configuration.md

+# Creating a username and password for JIRA server
+
+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 the `Jira-developers`
+group.
+
+NOTE: **Note**
+It is important that the user `gitlab` has 'write' access to projects in Jira.
+
+We have split this stage in steps so it is easier to follow.
+
+1. Log in to your Jira instance as an administrator and under **Administration**
+   go to **User Management** to create a new user.
+
+     ![Jira user management link](img/jira_user_management_link.png)
+
+2. The next step is to create a new user (e.g., `gitlab`) who has write access
+   to projects in Jira. Enter the user's name and a _valid_ e-mail address
+   since Jira sends a verification e-mail to set up the password.
+   _**Note:** Jira creates the username automatically by using the e-mail
+   prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create 
+    an HTTP basic authentication password. You can do this by visiting the user 
+    profile, looking up the username, and setting a password._
+
+     ![Jira create new user](img/jira_create_new_user.png)
+
+3. Create a `gitlab-developers` group which will have write access
+   to projects in Jira. Go to the **Groups** tab and select **Create group**.
+
+     ![Jira create new user](img/jira_create_new_group.png)
+
+     Give it an optional description and click **Create group**.
+
+     ![Jira create new group](img/jira_create_new_group_name.png)
+
+4. To give the newly-created group 'write' access, go to
+   **Application access > View configuration** and add the `gitlab-developers`
+   group to Jira Core.
+
+     ![Jira group access](img/jira_group_access.png)
+
+5. Add the `gitlab` user to the `gitlab-developers` group by going to
+   **Users > GitLab user > Add group** and selecting the `gitlab-developers`
+   group from the dropdown menu. Notice that the group says _Access_, which is
+   intended as part of this process.
+
+     ![Jira add user to group](img/jira_add_user_to_group.png)
+
+The Jira configuration is complete. Write down the new Jira username and its
+password as they will be needed when [configuring GitLab in the next section](jira.md#configuring-gitlab).