Allow JIRA to login using email and API token

6 files changed, 78 insertions, 51 deletions

diff --git a/doc/user/project/integrations/img/jira_api_token.png b/doc/user/project/integrations/img/jira_api_token.png
new file mode 100644
index 00000000000..2c64f7bc44f
--- /dev/null
+++ b/doc/user/project/integrations/img/jira_api_token.png
diff --git a/doc/user/project/integrations/img/jira_api_token_menu.png b/doc/user/project/integrations/img/jira_api_token_menu.png
new file mode 100644
index 00000000000..20655ba3c0e
--- /dev/null
+++ b/doc/user/project/integrations/img/jira_api_token_menu.png
diff --git a/doc/user/project/integrations/img/jira_service_page.png b/doc/user/project/integrations/img/jira_service_page.png
index c75c11888a8..869d562ed5b 100644
--- a/doc/user/project/integrations/img/jira_service_page.png
+++ b/doc/user/project/integrations/img/jira_service_page.png
diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md
index 30f49fefc41..bc4bba40e59 100644
--- a/doc/user/project/integrations/jira.md
+++ b/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.
+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)
 
-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 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
diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md
new file mode 100644
index 00000000000..2e6e8278e64
--- /dev/null
+++ b/doc/user/project/integrations/jira_cloud_configuration.md
@@ -0,0 +1,19 @@
+# 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).
+
diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md
new file mode 100644
index 00000000000..7d84ad0b07c
--- /dev/null
+++ b/doc/user/project/integrations/jira_server_configuration.md
@@ -0,0 +1,53 @@
+# 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).