Jira

Connecting to Jira

To connect set the URL to your Jira endpoint; for example, https://yoursitename.atlassian.net.

Accessing Custom Fields

By default the provider surfaces only system fields. To access the custom fields for Issues, set IncludeCustomFields to true. Or, you can extend the provider schemas to configure access to custom fields; Please note that the server response time can be significantly slower when custom fields are included.

Set the IncludeCustomFields property to True to expose access to all custom fields.

Authenticating to Jira

OAuth 2.0

You can leverage Jira's "three-legged" OAuth 2.0 support (3LO) to connect to data without providing your login credentials.

AuthScheme must be set to OAuth in all OAuth flows.

To obtain the OAuth client credentials, consumer key, and consumer secret:

1. Log in to your JIRA Cloud site.

2. Navigate to application management at https://developer.atlassian.com/apps/ (not your OAuth credentials at yoursitename.atlassian.net/secure/admin/oauth-credentials, which is for self-hosted tools.)

3. Select Create new app, then name the application. This creates the application.

4. If missing, add OAuth 2.0 functionality to your application by navigating to APIS AND FEATURES > + Add > Add OAuth 2.0 (3LO).

5. From APIS AND FEATURES > + Add, add the Jira platform REST API to your application .

6. From APIS AND FEATURES > + Jira platform REST API, add the desired scopes to your application .

7. You'll additionally need to set up your Callback URL. Navigate to APIS AND FEATURES > OAuth 2.0 (3LO). Enter a URL that is accessible to your application and save the changes.

After setting the following connection properties, you are ready to connect:

• OAuthClientId: Set to the consumer key in your application details.

• OAuthClientSecret: Set to the consumer secret in your application details.

• CallbackURL: Set to the callback URL found in your application details under APIS AND FEATURES > OAuth 2.0 (3LO).

• InitiateOAuth: Set to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.

• OAuthVersion: Set to 2.0.

• Url: The URL to your JIRA endpoint; for example, https://yoursitename.atlassian.net.

When you connect, the provider opens Jira's OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

• The provider obtains an access token from Jira and uses it to request data.

• Extracts the access token from the callback URL and authenticates requests.

• Saves OAuth values in the path specified in OAuthSettingsLocation. These values persist across connections.

The provider refreshes the access token automatically when it expires.

OAuth 1.0

To connect to Jira you have to follow the steps below:

1. Generate an RSA public/private key pair. In your terminal, run the following commands:

   -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 -out jira_publickey.pem

2. Create application links in your account. Go to Settings > Applications > Application links.

3. Enter a test URL for the url field, click Create new link.

4. Ignore the error and click continue. You need only configure incoming calls (from the application to Jira).

5. In the Link applications window, filling in the fields is optional, since they are not relevant to this task. But make sure to select Create incoming link. Click Continue. to go to the next page.

6. Fill in the required fields:

   • Consumer Key: Use any string you want. This is required for the OAuthClientId connection property.

   • Consumer Name: Use any string you want.

   • Public key: Enter the key from the jira_publickey.pem file you generated earlier.

7. Click Continue.

To connect set the following properties:

• URL (for example: https://yoursitename.atlassian.net).

• OAuthClientId to the Consumer Key of your application.

• OAuthClientSecret to any value (such as 'testClientSecret').

• CertificateStore to the location of your private key file.

• CertificateStoreType to the appropriate option based on the private key file being used. If using the generated PEM key file, set CertificateStoreType to PEMKEY_FILE.

• InitiateOAuth to GETANDREFRESH.

API Token

You can establish a connection to any Jira Cloud account by setting the AuthScheme to APIToken and providing the User and APIToken. An API token is necessary for basic authentication to Cloud instances. To generate one, log in to your Atlassian account and navigate to Security > Create and manage API tokens > Create API token. The generated token will be displayed.

Basic

You can establish a connection to any Jira Server instance by setting the AuthScheme to Basic. To connect to a Server Instance provide the User and Password. (Note: Password has been deprecated for connecting to a Cloud Account and is now used only to connect to a Server Instance.)

LDAP

You can establish a connection to any Jira Server instance by setting the AuthScheme to LDAP. Additionally provide the URL, User and Password of the Jira instance. (Note: LDAP Authentication is not currently supported for Cloud accounts.)

Crowd

Set the AuthScheme to Crowd. The following connection properties are used to connect to Crowd:

• User: The CROWD user account.

• Password: The password associated with the Crowd account.

• SSOLoginURL: The login URL associated with the Crowd account. You can find the IDP URL by navigating to your application -> SSO -> SSO information -> Identity provider single sign-on URL.

• SSOAppName: The name of the application in which SSO is enabled.

• SSOAppPassword: The password of the application in which SSO is enabled.

• SSOExchangeUrl: The URL used used to exchange the SAML token for Jira cookies. This URL may have the following formats:

  • https://<authority of Jira instance>/plugins/servlet/samlconsumer

  • https://<authority of Jira instance>/plugins/servlet/samlsso

The following is an example connection string:

AuthScheme=Crowd;Url=https://yoursitename.atlassian.net;SSOLoginURL='https://<authority>/crowd/console/secure/saml/sso.action';User=crowdUserName;Password=crowdPassword;SSOExchangeUrl=https://<authority of Jira instance>/plugins/servlet/samlconsumer;SSOAppName=CrowdAppName;SSOAppPassword=CrowdAppPassword;

Okta

Set the AuthScheme to Okta. The following connection properties are used to authenticate through Okta:

• User: Set to your Okta user.

• Password: Set to your Okta password.

• SSOLoginURL: Set to the login URL used by the SSO provider.

• SSOExchangeUrl: The URL used used to exchange the SAML token for Jira cookies. This URL may have the following formats:

  • https://<authority of Jira instance>/plugins/servlet/samlconsumer

  • https://<authority of Jira instance>/plugins/servlet/samlsso

If you are:

• using a trusted application or proxy that overrides the Okta client request

• configuring MFA

then you need to use combinations of SSOProperties input parameters to authenticate using Okta. Otherwise, you do not need to set any of these values.

In SSOProperties when required, set these input parameters:

• APIToken: When authenticating a user via a trusted application or proxy that overrides the Okta client request context, set this to the API Token the customer created from the Okta organization.

• MFAType: Set this if you have configured the MFA flow. Currently we support the following types: OktaVerify, Email, and SMS.

• MFAPassCode: Set this only if you have configured the MFA flow. If you set this to empty or an invalid value, the provider issues a one-time password challenge to your device or email. After the passcode is received, reopen the connection where the retrieved one-time password value is set to the MFAPassCode connection property.

• MFARememberDevice: Okta supports remembering devices when MFA is required. If remembering devices is allowed according to the configured authentication policies, the provider sends a device token to extend MFA authentication lifetime. This property is, by default, set to True. Set this to False only if you do not want MFA to be remembered.

Example connection string:

AuthScheme=Okta;Url=https://yoursitename.atlassian.net;SSOLoginURL='https://example.okta.com/home/appType/0bg4ivz6cJRZgCz5d6/46';User=oktaUserName;Password=oktaPassword;SSOExchangeUrl=https://<authority of Jira instance>/plugins/servlet/samlconsumer;