Jira Software

The purpose of this guide is to provide detailed information regarding the JIRA connector. There are a number of things you can learn about this connector here, including information about its configuration and deployment.

About JIRA Connector

In IDHub, you can create and onboard JIRA applications using the JIRA connector.

Connector Version

JIRA connector is currently at Version 1.0. More JIRA operations and other capabilities will be supported in upcoming updates and releases of the JIRA connector.

Component	Version
JIRA Connector	Ver 1.0
Target System	JIRA
Connector Server	11.1.2.1.0
Connector Server JDK	JDK 1.8 and later

Connector Operations

Operation	Supported
User Management
Create user	Yes
Update user	Yes
Delete User	Yes
Enable user	Yes
Issue Management
Delete Issue	Yes
Update Issue	Yes
Update Issue Status	Yes
Create Issue	Yes

Connector Components

The components of the connector include Connector Application, Connector Application Configuration, Connector Service Provider Interface, Splice, and Splice configuration.

tip

You can learn more about these components by clicking here.

These connection components contain precise connectivity and setup information for your target system. The connector takes information from these files to allow you to quickly and efficiently onboard your applications using a single, streamlined UI.

Connector Architecture

The connector's architecture is constructed in accordance with the diagram below:

As can be seen in the screenshot above, the connector architecture is basically composed of connector application and target system splice. The target system splice takes care of the native communication with the target system using the JIRA Specific connector SPI implementation. This architecture is followed and design as it enables for easy and rapid deployment of the connector as well as more precise versioning capabilities.

The connector is configured to run in one of the following modes:

Target Resource reconciliation
- If you use the JIRA application as the trusted source then in this case users are directly created and modified on IDHub. The ATLASSIAN / JIRA SDK extracts user records that match the reconciliation criteria, which brings the records to IDHub. Each user record fetched from the target system is compared with existing IDHub Users. If a match is found between the target system record and the IDHub User, then the User attributes are updated with changes made to the target system record. If no match is found, then the target system record is used to create an IDHub User.
Account management
- This involves creating, updating, or deleting users on the target system through IDHub. During provisioning, the connector calls the target system ATLASSIAN (JIRA) SDK for provisioning operations. The SDK on the target system accepts provisioning data, carries out the required operation on the target system, and returns the response from the target system back to IDHub. Apps can use the ATLASSIAN (JIRA) SDK to perform create, read, update, and delete (CRUD) operations on the target system.

note

In developing the connector, we adhere to this fundamental architecture. The IDHub team will handle the connector modification section appropriately based on your unique business requirements if there are any improvements, extra specifications, or variations.

Use cases for the connector

JIRA User Management

JIRA is currently being used by your company, and you want to connect it to IDHub. You may want to generate and reconcile accounts from and to JIRA and IDHub. In such a scenario, you would need to create a JIRA connector and use the connector URL to onboard an JIRA-connected application in IDHub. You will be able to provide accounts in the target system after successfully deploying the JIRA connector and creating the JIRA application. Similarly, you can perform further activities such as de-provisioning and updating accounts. IDHub offers a reconciliation feature that allows you to reconcile user identification information to and from JIRA.

JIRA Issue Management

You can create, update, delete, change status of JIRA issues using the connector as well.

Connector Features

Full Reconciliation and Incremental Reconciliation

Full reconciliation can be performed to bring all existing user data from the target system to IDHub. If the target system has an attribute that stores the timestamp at which an item is created or modified, you can configure your connector for incremental reconciliation once the first full reconciliation operation has been completed.

info

The connector's future release version will incorporate incremental recon, which is not supported by the present version of the connector.

Limited Reconciliation

Records from the target system can be reconciled depending on a defined filter condition. You can define the subset of newly added or updated target system records that must be reconciled in order to restrict or filter the records that are fetched into IDHub during a reconciliation process. You can specify the conditions in which the reconciliation will take place.

Support for the Connector Server

Connector Server is one of the features provided by IDHub. By using one or more connector servers, the connector architecture permits your application to communicate with externally deployed bundles. Therefore if you do not want to execute IDHub java connector bundle in the same VM as the application, in that case you have the ability to run the connector on a different host for better performance.

Pre-requisites

You need to have administrator email of your Atlassian or Jira Account
You need to have Atlassian SCIM URL.
You need to have the Directory API key
You need to have the Directory ID (Organization ID)
You need to have the account security api key (token) for atlassian admin account.
You need to have the URL for your Jira (or atlassian) products

info

The steps for creating the API key are as follows:

Go to admin.atlassian.com. Select your organization if you have more than one.
Select Settings > API keys.
Select Create API key in the top right.
Enter a name that you’ll remember to identify the API key.
By default, the key expires one week from today. If you’d like to change the expiration date, pick a new date under Expires on. You’re unable to select a date longer than a year from the date of creation.
Select Create to save the API key.
Copy the values for your Organization ID and API key. You'll need those to use the API key. Note: Make sure you store these values in a safe place, as we won't show them to you again.
Select Done. The key will appear in your list of API keys.

tip

The steps for generating the Api token for Atlassian Admin account is as follows:

Log in to https://id.atlassian.com/manage-profile/security/api-tokens.
Click Create API token.
From the dialog that appears, enter a memorable and concise Label for your token and click Create.
Click Copy to clipboard and store this somewhere safe.

Creating an Application by using the Connector

Onboard the Application in IDHub

tip

Click here for the detailed steps for onboarding the application to IDHub

Configuring the Connector

Connectors use connection-related parameters to connect to IDhub with your target system and perform connector operations when creating a connected application. IDHub requires the following connection-related parameters in order to connect to a JIRA application.

Attribute Mappings for the Connector

JIRA Schema	User Schema in IDHub	Sync Direction	IsVisible	Example	Type of Attribute
organization	organizationName	Target system to IDHub	Visible	Sath
department	department	Target system to IDHub	Visible	Marketing
displayName	displayName	Bi-Directional	Visible	John33
givenName	firstName	Target system to IDHub	Visible	John
title	jobTitle	Target system to IDHub	Visible	Manager
email	email	Target system to IDHub	Visible	John@sath.com	Recon Key
familyName	lastName	Target system to IDHub	Visible	Garret
userName	login	Target system to IDHub	Visible	John_g33	Account name Field
fullName	displayName	Target system to IDHub	Hidden
nickName		Target system to IDHub	Hidden
timezone		Target system to IDHub	Hidden

tip

Sync Direction of the Attributes depends on whether you regard JIRA as your Trusted Source.
You should only synchronize from IDHub to JIRA and not the reverse if JIRA is not a trusted system in your case

Possible Recon Keys and Values

Possible Recon Key	Possible Recon Key Values
userName	John_g33
email	John@sath.com

Connector Application Configuration

Connector application is designed such that it works as the wrapper application to the different scim adapters. This majorly consists of the following:

Authentication

Basic Authentication is required
The encrypted values of username and password will be stored in the properties file

Resource Type

These are the two resource types available for the IDHUB connector. The "resourceName" attribute value in rest api calls will have one of these values.

Account - user account in the target system - this will include entitlement membership
Entitlement -available entitlements in the target system

JIRA Connector Splice configuration

In order to provision, modify, and revoke two main resources, Accounts and Entitlements, the JIRA Connector Splice integrates with the IDHub Connector Application. IDHub's Account translates into a User in SCIM and JIRA, whereas IDHub's Entitlements translate into a Groups or policies in JIRA. JIRA provides SDK for Java to access data on JIRA.

Connector Splice Design

Account Schema

The Account Schema configuration of the JIRA connector Splice is as follows:

{
  "attributes": [
    {
      "name": "department",
      "description": "User department.",
      "multiValued": false,
      "idhubFieldName": "department"
    }, {
      "name": "displayName",
      "description": "User display name.",
      "required": true,
      "multiValued": false,
      "returned": "always",
      "idhubFieldName": "displayName"
    }, {
      "name": "fullName",
      "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.",
      "required": true,
      "multiValued": false,
      "returned": "always",
      "idhubFieldName": "displayName"
    }, {
      "name": "email",
      "description": "The primary email for the user.",
      "multiValued": false,
      "caseExact": true,
      "idhubFieldName": "email"
    }, {
      "name": "familyName",
      "description": "The family name of the User.",
      "multiValued": false,
      "caseExact": true,
      "idhubFieldName": "lastName"
    }, {
      "name": "givenName",
      "description": "The given name of the User.",
      "multiValued": false,
      "caseExact": true,
      "idhubFieldName": "firstName"
    }, {
      "name": "title",
      "description": "User title.",
      "multiValued": false,
      "caseExact": true,
      "idhubFieldName": "jobTitle"
    }, {
      "name": "nickName",
      "description": "User nickname.",
      "multiValued": false,
      "caseExact": true
    }, {
      "name": "organization",
      "description": "User organization.",
      "multiValued": false,
      "idhubFieldName": "organizationName"
    }, {
      "name": "timezone",
      "description": "User timezone. e.g. America/Los_Angeles .",
      "multiValued": false,
      "caseExact": true
    }, {
      "name": "userName",
      "description": "Unique identifier defined by the provisioning client. Atlassian SCIM service will verify the value and guarantee its uniqueness. This field is required during user creation or modification. ",
      "multiValued": false,
      "caseExact": true,
      "required": true
    }
  ]
}

Entitlement Schema

The Entitlement Schema configuration of the JIRA connector Splice is as follows:

{
  "attributes": [
    {
      "name": "description",
      "description": "Description of entitlement",
      "multiValued": false,
      "required": true,
      "returned": "always"
    }, {
      "name": "displayName",
      "description": "The entitlement (Group / Project Role) name",
      "required": true,
      "multiValued": false,
      "returned": "always"
    }, {
      "name": "type",
      "description": "Indicate type of entitlement",
      "multiValued": false,
      "required": true,
      "returned": "always"
    }, {
      "name": "form",
      "description": "Entitlement Form containing Entitlement Attributes",
      "multiValued": true,
      "required": true,
      "returned": "always"
    }
  ]
}

Deploying the JIRA Connector

Deploying using IDHub Connector Onboarding Wizard

tip

The documentation for deploying the connector on your own Cloud Platform is coming soon

Deploy on your own

Deploy on Cloud

tip

The documentation for deploying the connector on your own Cloud Platform is coming soon

Deploy on your Server

Prerequisites

IDHub web hostname.
An IDHub Tenant.
An Ubuntu/Debian Linux VM with Docker engine, Compose plugin, cURL, jq and unzip.
A service URL with valid certificate which points to port 7001 on the above VM.

Step 1 — Creating Connector OAuth Client (ID)

From IDHub Dashboard, go to Admin Settings > Sign-On > Keycloak Administration and do the following steps.

Go to Clients menu.
Create client and set Client ID to ‘JIRA-connector’ and Save.
Set Valid Redirect URIs to '*' and Save.

Step 2 — Create service account user and password in Keycloak in tenant realm

In your Keycloak realm, do the following.

Go to Users menu.
Add user.
Set Username to ‘JIRA-service-account’ and Save.
Go to its Credentials menu and set a password. (Note: For this tutorial, we have used ‘sapassword1’. We highly recommend using a different one for your service account).

Step 3 — Generate Access token and Refresh token

curl --location --request POST 'https://IDHUB_HOSTNAME/auth/realms/TENANT_NAME/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=OAUTH_CLIENT_ID' \
--data-urlencode 'username=SERVICE_ACCOUNT_USER' \
--data-urlencode 'password=SERVICE_ACCOUNT_PASSWORD' \
--data-urlencode 'scope=offline_access' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'request_token_type=urn:ietf:params:oauth:token-type:access_token' \
| jq

Replace the following:

IDHUB_HOSTNAME: The IDHub web hostname. A prerequisite. eg. test.sath.com
TENANT_NAME: Tenant that you created in test.sath.com. A prerequisite. eg. alpha
OAUTH_CLIENT_ID: OAuth Client ID you created in Step 1.
SERVICE_ACCOUNT_USER: Service account username you created in Step 2.
SERVICE_ACCOUNT_PASSWORD: Service account password you created in Step 2.

info

We now have our tokens. Let’s deploy the connector.

Step 4 — Prepare the .env file

Clone the IDHub’s AD Connector repository and edit the .env file.

wget https://storage.googleapis.com/sath-public-binaries/connectors/idhub-jira-connector.zip
unzip idhub-jira-connector.zip
cd idhub-jira
nano .env

ADMIN_EMAIL=ADMIN_EMAIL
BUSINESS_OWNER=BUSINESS_OWNER
CONNECTOR_DEBUG_LEVEL=CONNECTOR_DEBUG_LEVEL
DIRECTORY_API_KEY=DIRECTORY_API_KEY
DIRECTORY_ID=DIRECTORY_ID
SCIM_URL=SCIM_URL
ACCOUNT_SECURITY_API_KEY=ACCOUNT_SECURITY_API_KEY
SITE_URL=SITE_URL
IDHUB_HOSTNAME=IDHUB_HOSTNAME
IT_OWNER=IT_OWNER
KEYCLOAK_ACCESS_TOKEN=KEYCLOAK_ACCESS_TOKEN
KEYCLOAK_CLIENT_ID=KEYCLOAK_CLIENT_ID
KEYCLOAK_REALM=KEYCLOAK_REALM
KEYCLOAK_REFRESH_TOKEN=KEYCLOAK_REFRESH_TOKEN
PORT=PORT
SPLICE_DEBUG_LEVEL=SPLICE_DEBUG_LEVEL

info

Replace the following:

ADMIN_EMAIL: This is the administrator email of your Atlassian or Jira Account
BUSINESS_OWNER: This is the business owner name of the JIRA application
IT_OWNER: This is the IT owner of the JIRA application
IDHUB_HOSTNAME: IDHub web hostname. From prerequisites. eg. test.sath.com
ACCESS_TOKEN: From Step 3 output. Put it WITHOUT the quotes.
REFRESH_TOKEN: From Step 3 output. Put it WITHOUT the quotes.
KEYCLOAK_CLIENT_ID: From Step 1.
KEYCLOAK_REALM: Tenant created in IDHub. From prerequisites. eg. alpha
CONNECTOR_PORT: JIRA connector port which you are planning to run on. The Service URL points to this port.
DIRECTORY_API_KEY: This is the JIRA directory API key
DIRECTORY_ID: This is the JIRA directory id
SCIM_URL: This is the Atlassian SCIM url
ACCOUNT_SECURITY_API_KEY: This is the api key for Atlassian Admin account.
SITE_URL: This is the URL for your jira / atlassian products

Step 5 — Run the container

In the connector directory, run the following command.

docker compose up -d

Jira Software

About JIRA Connector​

Connector Version​

Connector Operations​

Connector Components​

Connector Architecture​

Use cases for the connector​

Connector Features​

Full Reconciliation and Incremental Reconciliation​

Limited Reconciliation​

Support for the Connector Server​

Pre-requisites​

Creating an Application by using the Connector​

Onboard the Application in IDHub​

Configuring the Connector​

Attribute Mappings for the Connector​

Possible Recon Keys and Values​

Connector Application Configuration​

Authentication​

Resource Type​

JIRA Connector Splice configuration​

Connector Splice Design​

Account Schema​

Entitlement Schema​

Deploying the JIRA Connector​

Deploying using IDHub Connector Onboarding Wizard​

Deploy on your own​

Deploy on Cloud​

Deploy on your Server​

Prerequisites​

Step 1 — Creating Connector OAuth Client (ID)​

Step 2 — Create service account user and password in Keycloak in tenant realm​

Step 3 — Generate Access token and Refresh token​

Step 4 — Prepare the .env file​

Step 5 — Run the container​

About JIRA Connector

Connector Version

Connector Operations

Connector Components

Connector Architecture

Use cases for the connector

Connector Features

Full Reconciliation and Incremental Reconciliation

Limited Reconciliation

Support for the Connector Server

Pre-requisites

Creating an Application by using the Connector

Onboard the Application in IDHub

Configuring the Connector

Attribute Mappings for the Connector

Possible Recon Keys and Values

Connector Application Configuration

Authentication

Resource Type

JIRA Connector Splice configuration

Connector Splice Design

Account Schema

Entitlement Schema

Deploying the JIRA Connector

Deploying using IDHub Connector Onboarding Wizard

Deploy on your own

Deploy on Cloud

Deploy on your Server

Prerequisites

Step 1 — Creating Connector OAuth Client (ID)

Step 2 — Create service account user and password in Keycloak in tenant realm

Step 3 — Generate Access token and Refresh token

Step 4 — Prepare the .env file

Step 5 — Run the container