Configure OAuth Connection

About

You use OAuth authentication when connecting to Jira Cloud or Jira Server / Data Center(DC). For Jira Cloud, this is the only supported authentication type.

In Jira, external OAuth consumers are represented by application links. These links use OAuth with RSA-SHA1 keys for authentication. You need a private RSA key rather than OAuth token (or secret) for connection.

This topic enlists the steps to configure OAuth Connection:

• Generate RSA keys

• Configure an application link in Jira Cloud and Jira Server/DC (below version 9.x)

• Configure an application link in Jira Server/DC (above version 9.x)

• Configure connection in Zephyr

Watch video tutorial

Open

Below is the textual description.

Requirements

The procedure that will be described below requires you to connect to Jira at some step. If webhooks will be created automatically, the Jira user account you will use must have the following permissions:

• Browse Project permission for all projects

• Issue Permissions: Assignable User, Assign Issues, Edit Issues, Link Issues, Move Issues, Transition Issues

• Comments Permissions

• Attachment Permissions

• Jira Web-hook Enabled

• Issues Related Events: Updated, Deleted

• Project Version Related Events: Released, Unreleased, Created, Moved, Updated, Deleted

• Project Related Events: Updated, Deleted

Before configuring the connection, log in to Jira and check the permissions there. If needed, ask you Jira administrator for assistance.

The easiest way is to use the Jira administrator account for setting up the integration parameters. You may also want to create a user account in your Jira instance that will specifically be used for integration with Zephyr. This account should have all the needed permissions.

1. Generate RSA keys

To generate the key pair, you can use the OpenSSL command-line utility. You might already have it on your computer, as it is included in many software products like source control systems and their clients, web servers, and others. You can also download it any time from the https://www.openssl.org/ website.

 Open the command line prompt and run the following commands. They will generate the keys in the needed format:

openssl genrsa -out jira_privatekey.pem  1024
openssl req -newkey rsa:1024 -x509 -key jira_privatekey.pem -out jira_publickey.cer -days 365
openssl pkcs8 -topk8 -nocrypt -in jira_privatekey.pem -out jira_privatekey.pcks8
openssl x509 -pubkey -noout -in jira_publickey.cer > jira_publickey.pem

To configure the connection, we will need the private key in the PCKS8 format and the public key in the PEM format.

The 2048-bit key is also supported.

2. Configure an application link in Jira Cloud and Server Data Center

You configure an application link to other Atlassian products, using OAuth1.0 . Zephyr Enterprise does not support OAUTH2.0 which is in an external application. Based on the version of Jira Server DC and Jira Cloud that you want to connect with, the following are ways you can configure an application link:

a. Jira Cloud and Jira Server/DC (below version 9.x)

1. In Jira, go to ⚙ > Products > Application links (under Integrations):

   Open

   

    

2. On the subsequent page, enter the URL of your Zephyr Enterprise instance followed by /flex:
   - If you use Zephyr Enterprise Cloud –
   https://{your-subdomain}.yourzephyr.com/flex
   - If you use Zephyr Enterprise Server –
   http(s)://{your-host-URL-or-IP}:{port}/flex

    

3. Click Create new link.

4. Click Continue in the subsequent confirmation dialog:

5. Now you need to configure the link properties:
   - Enter some name into the Application Name box, for example, Zephyr Ent.
   - Enter the same value into other text boxes in the dialog.
   - Scroll the dialog box down and select the Create incoming link check box.
   It’s important to select this check box.
   
   

    

6. In the next dialog, you need to specify the key.
   - In the Consumer Key text box, enter the key name, for instance, Zephyr Ent.
   You will need the Consumer Key value later. Write it down or remember.
   - Enter some value into the Consumer Name box.
   - Enter the contents of the public key .pem file (jira_publickey.pem) you generated earlier into the Public Key text box.
   To do this, open the key file in any text editor, copy the file contents and paste it in the Public Key box.
   When copying, skip the first and last lines of the file (they have the BEGIN PUBLIC KEY and END PUBLIC KEY phrases).
   Also, make sure you don’t enter leading or trailing characters like spaces or line breaks by accident. A good practice is to clear the text box before pasting the key contents to it.

    

7. Click Continue.

8. The new application link will appear in the list of links in Jira:

   Tip: To check if you specified the app URL correctly, click “Go to remote” for the created link. This should open the Zephyr Login form.

b. Jira Server/DC version 9.x and above

1. In Jira, go to ⚙ > Products > Application links (under Integrations):

On the subsequent page, enter the URL of your Zephyr Enterprise instance followed by /flex:
- If you use Zephyr Enterprise Cloud –
https://{your-subdomain}.yourzephyr.com/flex
- If you use Zephyr Enterprise Server –
http(s)://{your-host-URL-or-IP}:{port}/flex

3. Click Create new link.
4. Select Atlassian product.

5. Click Continue in the subsequent confirmation dialog.

6. Now you need to configure the link properties:
- Enter some name into the Application Name box, for example, Zephyr Ent.
- Enter the same value into other text boxes in the dialog.
- Scroll the dialog box down and select the Create incoming link check box.
It’s important to select this check box.

7. Click Continue.

8. In the next dialog, you need to specify the key.
- In the Consumer Key text box, enter the key name, for instance, Zephyr Ent.
You will need the Consumer Key value later. Write it down or remember.
- Enter some value into the Consumer Name box.
- Enter the contents of the public key .pem file (jira_publickey.pem) you generated earlier into the Public Key text box.
To do this, open the key file in any text editor, copy the file contents and paste it in the Public Key box.
When copying, skip the first and last lines of the file (they have the BEGIN PUBLIC KEY and END PUBLIC KEY phrases).
Also, make sure you don’t enter leading or trailing characters like spaces or line breaks by accident. A good practice is to clear the text box before pasting the key contents to it.

9. Click Continue.

10. The new application link will appear in the list of links in Jira:

Tip: To check if you specified the app URL correctly, click “Go to remote” for the created link. This should open the Zephyr Login form.

3. Configure connection in Zephyr

1. Log in to your Zephyr Enterprise instance as a user with administrator permissions.

2. Go to Administration > Jira Integration (under System Setup).

3. Click + above the Jira instance list:

4. In the subsequent dialog, specify the following values:

   - Auth Mode -Select OAuth (1.0a). To connect to Jira Cloud, you should use this mode.
   - Name – Any descriptive name for the connection. It will be used in the Zephyr UI.
   - Jira URL – The URL of your Jira instance like https://{my-org}.atlassian.nеt.
   - Consumer Key Name – The key name.
   It should be the same as the Consumer Key value you entered in Jira.
   - Consumer Private Key – Specify the contents of the private key you generated earlier. Use the .pcks8 file (jira_privatekey.pcks8): open it in any text editor, copy the key contents and paste them to the Consumer Private Key box.
   When copying, skip the first and last lines of the file (they have the BEGIN PUBLIC KEY and END PUBLIC KEY phrases). Also, make sure you don’t enter leading or trailing characters like spaces or line breaks by accident. A good practice is to clear the text box before pasting the key contents to it.
   
   

   Click Confirm to continue.
   
   

5. Zephyr will display the following message box. Click Confirm to continue:

    

6. Zephyr will show the following dialog box:

   
   If you specified the public and private keys correctly, you will see some valid authorization URL. Otherwise, this value will contain the error message.
   
   In the dialog:
   a. Click the URL specified in Step 1:

   
   b. This will send a request for the authentication code to Jira. The latter will ask for your approval to allow Zephyr access to your Jira project. Click Allow to continue:

   
   c. Jira will show another page with the verification code (the value in quotes):

   
   Copy this code to the clipboard and then switch to Zephyr and paste it into the Step 2 box:

   Click Save.
   
   

7. Zephyr will run some diagnostics and will report the results:

   
   Click Done. You will see the newly created connection in the list of connections:
   
   

    

Further steps

You have not yet completed integration setup. To complete it, you need to map your Zephyr project to a Jira project. Follow this link for details:

Next step: Configure your Zephyr project 

Note about webhooks

Webhooks are an essential part of Zephyr integration with Jira. They are used to synchronize Zephyr and Jira requirements and information about defects.

Webhooks can be created in two ways:

• Zephyr creates a pre-configured webhook automatically when you are mapping a project in Zephyr. In this case, there is no need to perform any additional actions, but you need to have a Jira account with special permissions (for example, Browse Projects). You can view the created webhook in Jira settings: go to > System (under Jira Settings) > Webhooks (under Advanced).

  Don’t delete this webhook, and don’t change its properties. It has all the needed settings enabled. Later, you can update the webhook, if needed.

• You, as an administrator, can create and manage webhooks manually. This can be useful if you do not have (or do not want to create) a Jira service account with permissions required for automatic webhook management.

See Also

Jira Integration