Configure OAuth Connection

Owned by Helen Kosova (Deactivated)
Apr 28, 2021
6 min read

About

You use OAuth authentication when connecting to Jira Cloud or Jira Server / Data Center. 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 will need a private RSA key rather than OAuth token (or secret) for connection.

Watch video tutorial

 

Below is the textual description.

Requirements

The procedure that will be described below requires you to connect to Jira at some step. The Jira user account you use should have the permissions listed below. Before configuring the connection, log in to Jira and check the permissions there. If needed, ask you Jira administrator for assistance.

  • Browse Project Permissions for All Projects

  • Issue Permissions: Assignable User, Assign Issues, Close Issues, Delete Issues, Edit Issues, Link Issues, Move Issues, Set Issue Security, 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

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.

2. Configure an application link in Jira

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

     

  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


    Click Create new link.

  3. Click Continue in the subsequent confirmation dialog:

     

  4. 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.

    Click Continue.

  5. 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 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.

    Click Continue.

  6. 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: 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 a webhook

During project mapping Zephyr, the latter will automatically create and configure a webhook on the Jira side. This webhook will be used in communication between Zephyr and Jira. You can view it 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.

See Also

Jira Integration