If you’ve looked at my LinkedIn profile, then you already know that I currently work for a start up called Cyral. With that already being a known thing, I figured it wouldn’t hurt to add some Cyral specific things to the blog as well. This first post is specific to Cyral but could help others that are trying to integrate Jira Cloud with other APIs that require a Java Web Token (JWT) to authenticate.
The Integration Problem
Cyral has a super cool technology (Yes, I’m super biased but hey whatever). They also have a nice UI that can perform a number of management tasks for the product too. Despite having a functional UI, users still can require integrations into their existing workflows. My previous post Making the Leap into DevOps, mentions how I’ve begun dabbling in Devops. Integrating into existing workflows fits into the Devops world nicely. Full-featured APIs make integrations much easier.
I was asked to demonstrate how Cyral could be integrated into a customer’s environment. For the purposes of building out this example, we chose Jira Cloud. Obviously, you could use whatever workflow/ticketing management system you wanted but many people are familiar with Jira.
I was asked to create two specific workflows, but covering them both in detail would result in a very large blog post. In order to keep this first post short, I’m going to simplify the problem down to trying to access the Cyral Recommendations API to create Jira Issues for each recommendation.
What are Cyral Recommendations?
In short, recommendations are a combination of a database location (schema.table.column) and a label associated with that column. This concept is quite similar to data classification where you are tagging a particular column in the database with a particular type of data (sensitive, PII, PCI, SSN…etc..). In Cyral, these labels can be used in policies.
How Do Recommendations Get Created?
Cyral has something that can be deployed in customer environments called the Repo Crawler. The Repo Crawler can walk databases attempting to find data and classify it. If it finds known data types, then it will submit these findings as recommendations.
Customers could also choose to use their own solution for finding data and submit it to the recommendations API as well. Feel free to checkout the API guide for some information on that.
Once the recommendations are created, users can manage those recommendations to either accept or dismiss them. Accepting recommendations will cause the recommendations to become labels that can/are used in policies. Dismissing the recommendation will make them fade away and be ignored.
Access the Cyral API
I won’t spend too much time here because there’s a bunch of documentation already available in Cyral’s documentation. The important thing to note here is that a client ID and client Secret are required to generate a JWT. Once a JWT has been generated for the API, that JWT can be used to interact with the API.
This JWT authentication is a common authentication mechanism across APIs. I won’t put a specific link here but feel free to Google
rest api jwt and you’ll get a bunch of results. Also, if you have had to access any REST APIs, you’ll know this is common as well as some other authentication types.
Integrating With Jira Cloud
This is the part you’ve been waiting for! I’ve tried to set up as briefly as possible the specific API that I’m accessing so these next steps make sense. In order to myself focused, I’m going to talk specifically about integrating Cyral with Jira Cloud. The API that you want to integrate with doesn’t matter as you could reuse this example for any JWT authentication REST API.
What Does Jira Cloud Have for Integrating With APIs?
Such a great question! In short, Jira Cloud has a great feature called Jira automation. One of the actions in this feature is called Send web request. This action allows you to customize the request and even handle the results in the response. You can choose to iterate over results from the API and even assign results to variables (hint: we’ll be using both of these).
What Does Jira Cloud NOT Have for Integrating With APIs?
Sadly, one thing that I found lacking is the ability to store sensitive data securely. Jira Server allows admins to create global variables that could be “better” secured. Jira Cloud does not yet have the ability to create global variables. Given this little “problem”, I want to call out this next paragraph in red text…
Your long term API credentials such as the Cyral Client ID and Cyral Client Secret used for the API are stored IN the automation! This means that anyone with access to your automation rules could see the credentials needed to access the API. While this could be “ok” because it should only be Jira Administrators, it is worth calling out this fact.
Another little piece of useful information is that you also have to add these credentials into every rule that you create. You can’t create a single global variable to store the credentials and then reference those variables in the rules.
Setting Up The Integration
Let’s dive into actually integrating Cyral with Jira Cloud by setting up the automation. I’m assuming you already have API credentials for the Cyral CP.
Cyral Control Plane Setup
This integration leverages some variables that are used to interact with the Cyral Control Plane API. The below table covers the variable names that will be used in Jira as well as what these values map to in Cyral. Details regarding generating the Client ID and Secret (aka Cyral API access key credentials) can be found in the Cyral API documentation.
|Jira Variable Name||Cyral Description|
|CyralCPClientID||API access key Client ID|
|CyralCPSecret||API access key Client Secret|
|CyralCPURL||Your Cyral control plane domain|
Jira Project Setup
I created a new project but this could be created in an existing project if you wanted. The project type should not matter. Within the project, the following will need to be created:
- Issue Type
- Custom Fields
This setup uses an Issue Type called
Recommendation. This requires some additional fields that can be hidden when left empty, in addition to the default Issue Type fields.
There is nothing special about the Issue Type itself. Include fields in your Jira that you would like to use.
Hide When Empty Fields
The following fields are required for the Jira automation to work correctly. Jira needs these fields to be able to save details required to interact with the Cyral Control Plane APIs. These details are only Cyral specific unique identifiers. You can also correlate Cyral audit logs with Jira tickets using these fields.
|Field Name||Field Type||Field Description|
|Cyral Repository ID||Short Text||Cyral identifier for repository|
|Cyral Recommendation ID||Short Text||Cyral identifier for recommendation|
This automation will allow Jira to interact with the Cyral Control Plane API to pull recommendations.
This automation will query the Cyral Control Plane API to get a list of recommendations that are not yet Approved or Dismissed. After obtaining this list, the automation checks to see if there are any existing tickets for these recommendations. If no tickets exist for the recommendation, the automation will create tickets for them.
Below is a diagram that explains the flow of the automation.
You can use the GetCyralRecommendations.json file to import this automation into your Jira Cloud for ease of setup.
This article is one way of Integrating Cyral with Jira Cloud. Once Cyral implements this feature, you will receive recommendations in your Jira.
As mentioned previously, you could also choose to reuse this to work with any REST API that uses JWT authentication.