Jira authentication options

SpecSync supports several authentication options for the supported Jira systems. This section provides a summary of how the different authentication options have to be configured:

For Jira Cloud:

• API Token

For Jira Server or Data Center:

• Personal access tokens

• User name and password

The authentication credentials can be specified in multiple ways:

1. During the execution of the SpecSync command using the interactive prompt (password is masked). This method is used by SpecSync if either the user name (token) or the password is not configured anywhere else.

2. Using the --user and --password command line options.

3. In the remote section of the SpecSync configuration file (specsync.json).

4. In the user-specific configuration file.

5. In system environment variables that can be referred to either in the configuration file or from the command prompt (see examples below). The environment variable name has to be specified using the {env:ENV_VAR} format (%ENV_VAR% format is also accepted for backwards compatibility).

Examples

Specifying the user name in the specsync.json configuration file:

specsync.json

{
  ...
 "remote": {
    "serverUrl": "https://specsyncdemo.atlassian.net/",
    "project": "MyCalculator",
    "user": "account01"
  },
  ...
}

Specifying the user name in the command line:

dotnet specsync push --user "account01"

A user-specific configuration file that configures credentials for multiple projects.

specsync.json (in C:\Users\my_user\AppData\SpecSync folder)

{
  "$schema": "http://schemas.specsolutions.eu/specsync-user-config-latest.json",

  "knownRemotes": [
    {
      "projectUrl": "https://dev.azure.com/myorg/*",
      "user": "g2x.....................ac2vx57i4a"
    },
    {
      "projectUrl": "https://dev.azure.com/otherorg/OtherProject",
      "user": "y6s.....................ksuc7tsts"
    }
  ]
}

Specifying the user credentials that refer to an environment variable in the specsync.json configuration file. The example requires the user name to be stored in the environment variable SPECSYNC_REMOTE_USER:

specsync.json

{
  ...
 "remote": {
    "serverUrl": "https://specsyncdemo.atlassian.net/",
    "project": "MyCalculator",
    "user": "{env:SPECSYNC_REMOTE_USER}"
  },
  ...
}

You can also use the environment variables without the shell resolving their values. For that, specify the value in the {env:ENV_VAR} format.

dotnet specsync push --user "{env:SPECSYNC_REMOTE_USER}"

Permissions required for users used by SpecSync

SpecSync creates and manages Test Cases in Jira. Therefore to be able to operate it needs to have

• read/write access for the Test Case issue type

• read access for other issue types the Test Cases are linked to.

More specifically, the following Project permissions are required:

• Browse Projects

• View Read-Only Workflow

The following Issue permissions are required:

• Assign Issues (only if you plan to update the assigned to field)

• Close Issues (only if you plan to update the issue state field)

• Create Issues

• Edit Issues

• Link Issues

• Modify Reporter (only if you plan to update the related field)

• Resolve Issues (only if you plan to update the issue state field)

• Schedule Issues (only if you plan to update the due date field)

• Transition Issues (only if you plan to update the issue state field)

The following Comments permissions are required:

• Add Comments

The following Attachments permissions are required:

• Create Attachments

Jira API Token

In order to connect to Jira Cloud with SpecSync, you can authenticate yourself with Jira API tokens. For that you need to create an API Token in Jira Cloud (see instructions) and then specify your email address as user name and the token as password.

The following example authenticates using the email address [e-mail] and API token Kyu4Wl3twFAa9cAWklTCB476

specsync.json

{
  ...
 "remote": {
    "serverUrl": "https://specsyncdemo.atlassian.net/",
    "project": "MyCalculator",
    "user": "[e-mail]",
    "password": "Kyu4Wl3twFAa9cAWklTCB476"
  },
  ...
}

Personal access tokens

In order to connect to Jira Server or Jira DataCenter with SpecSync, you can authenticate yourself with Personal Access Tokens (PAT). For that you need to create a PAT in Jira Server (see instructions in the section "Creating PATs in the application" of the Jira Documentation page) and then use that as user name without specifying a password.

The following example authenticates using the PAT AGT2OTk3NjMxNDQyOlBfg4kDgqKreys6v0FzrcDBZR89

specsync.json

{
  ...
 "remote": {
    "serverUrl": "http://myjiraserver:9090/",
    "project": "MyCalculator",
    "user": "AGT2OTk3NjMxNDQyOlBfg4kDgqKreys6v0FzrcDBZR89"
  },
  ...
}

User name and password

In order to connect to Jira Server or Jira DataCenter with SpecSync, you can authenticate yourself with user name and password.

It is not recommended to include the password to the configuration file. If you don't specify your password, SpecSync will ask for it using an interactive prompt. Alternatively you can consider using personal access tokens or environment variables.

The following example specifies the user name account01 in the configuration file.

specsync.json

{
  ...
  "remote": {
    "serverUrl": "http://myjiraserver:9090/",
    "project": "MyCalculator",
    "user": "account01"
  },
  ...
}