# Jira Workflow

## About The Keeper Security Integration for Jira is an Atlassian Forge application that enables seamless management of Keeper vault operations directly from Jira issues. This integration bridges the gap between project management workflows and secrets management, allowing teams to request, approve, and execute credential operations without leaving their Jira environment. The Jira integration also provides management over Endpoint Privilege Manager (KEPM) approvals. All actions are logged as Jira comments with timestamps and user information. ### Record Management Features | Feature | Description | | ---------------------- | --------------------------------------------------------------------- | | **Create New Records** | Add credentials, secure notes, payment cards, and custom record types | | **Update Records** | Modify existing vault records with new information | | **Share Records** | Manage folder-level access for teams and users | | **Manage Permissions** | Control granular access rights for records in shared folders | | **Share Folders** | Manage folder-level access for teams and users | | **Manage Permissions** | Control granular access rights for records in shared folders | ### **Endpoint Privilege Management Features** | Feature | Description | | --------------------------------- | ---------------------------------------------------------------- | | **Real-Time Approval Workflows** | Review and approve privilege elevation requests from endpoints | | **Live Request Monitoring** | View pending requests with countdown timers and detailed context | | **One-Click Actions** | Approve or deny requests instantly with full audit trail | | **Comprehensive Request Details** | User identity, application, justification, and expiration status | ## Prerequisites To maintain Keeper's strict zero knowledge encryption model, the Jira integration requires that the customer hosts the Commander Service Mode container on a VM and hosts the customized Forge app in their Jira Cloud. | Requirement | Description | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Keeper Commander Service Mode** | A service account running Commander Service Mode with REST API access through **Ngrok** or **Cloudflare Tunnel** for routing requests. | | **Jira Cloud Administrator Access** |

Needs Jira Administrator or Manage apps permission to install and configure the Forge app.

Must access Jira Settings → Apps to set up and manage app connections.

| | **Jira End-User Access** |

Requires Edit Issues and Add Comments permissions to view and use the Keeper panel

Works across all Jira Cloud project types; no extra setup needed. See Jira Project Permissions for details

| | **Keeper Standard Features** |

Requires an active Keeper Business, Enterprise, or PAM subscription with vault access.

Service account with permissions to create, update, and share records.

| | **Endpoint Privilege Manager Features** |

Active KeeperPAM subscription
KEPM module enabled and configured in your Keeper environment
KEPM deployments, agents, and policies configured
For more information, see Endpoint Privilege Manager Overview

| ## **Setup and Configuration** In order to communicate between the Jira service and Keeper, the customer is responsible for hosting a Keeper Commander Service Mode instance with an Ngrok or Cloudflare Tunnel. This can be accomplished many ways depending on your IT requirements. Commander Service Mode can run as a foreground service on any machine, or it can be run in a Docker container locally or remotely on a server. ### **Step 1.** Commander Setup Follow the setup steps documented in the [Commander Service Mode REST API](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api) section to install Keeper Commander and start the service. You need to follow the instructions using either Ngrok or Cloudflare tunnels to properly route requests from the Forge app to your Commander instance. Commander Service Mode can run directly in the CLI, in the background on a local machine, on a remote server as a service, or under a Docker container. Using Docker is the recommended method. **Note the following Important Items:** 1\) The Request Queue System (API v2) must be enabled, e.g. `-q=y` 2\) For Vault Management features, make sure the following commands are in the list: {% code overflow="wrap" %} ``` record-add,list,ls,get,record-type-info,record-update,share-record,share-folder,rti,record-permission,service-status ``` {% endcode %} 3\) For Vault + KEPM features, make sure the following commands are in the list: {% code overflow="wrap" %} ``` record-add,list,ls,get,record-type-info,record-update,share-record,share-folder,rti,record-permission,epm,service-status ``` {% endcode %} 4\) For Ngrok Tunneling, ensure the following parameters are included: ``` -ng -cd ``` 5\) For Cloudflare Tunneling, ensure the following parameters are included: ``` -cf -cfd ``` After service creation, the API key will be displayed in the console output. Make sure to copy and store it securely. If you are using Docker, you can pull the API key from the logs with this command: ``` docker compose logs | grep -i "generated api key" ``` When the Commander service is up and running, you should be able to submit a curl request to the endpoint. For example: ```bash curl -X POST 'https://mytunnel.company.com:8080/api/v2/executecommand-async' \ --header 'Content-Type: application/json' \ --header 'api-key: ' \ --data '{"command": "ls"}' ``` If the tunnel is running and the API key is correct, you should get a response like this: ```json { "success": true, "request_id": "550e8400-e29b-41d4-a716-446655440000", "status": "queued", "message": "Request queued successfully..." } ``` Now that the service is up and running, move to the Jira configuration steps. *** ### Step 2. Install the Keeper Forge App Before configuring the integration, you must install the Keeper Forge app in your Jira Cloud instance. See [Forge App Installation Guide](https://docs.keeper.io/en/keeperpam/secrets-manager/integrations/jira-workflow/forge-app-installation) for detailed instructions. ### Step 3. Jira Configuration Configure the Integration in your Atlassian Jira instance as the Administrator. * In Jira: Go to **Apps → Keeper**. * Enter **API URL** including the /api/v2 path and **API Key**. * Example URLs: * **Ngrok:** `https://your-subdomain.ngrok.io/api/v2` * **Cloudflare:** `https://your-subdomain.trycloudflare.com/api/v2` * **Test Connection** * Click **Test Connection** → verify success. * **Save Settings**

Jira Admin configuration complete. *** ### Step 4. Endpoint Privilege Manager Webhook To manage Keeper EPM approvals and generate tickets in Jira, a webhook notification is sent from Keeper to the Jira platform. The webhook URL is provided on the Keeper Jira integration screen. This webhook must be activated in the Keeper Admin Console following the steps below. * Locate the Web Trigger URL from the Jira Forge app.

* Generate Authentication Token:

* Copy both the URL and the token (token shown only once) * Login to the **Keeper Admin Console** > **Reporting & Alerts** > **Alerts** and click on "**Add Alert**" * Set Alert Name to something like "Jira EPM Alerts" * In Alert Condition, select the below events: * **Agent created approval request** * **Removed approval request** * **Changed approval request status** * Click on "**Add Recipient**" and then click "**Webhook**" * Paste the copied URL and Token from above * Save the recipient and then save the alert

Keeper Admin Console - Webhook Configuration

* Back on the Jira Forge app, Configure which Jira project should receive automatically created tickets from Keeper Security alerts. * Also select the target project and default issue type. The web trigger URL is automatically generated by Jira Forge and serves as the webhook endpoint for Keeper Security alerts. * Save the Forge App configuration

Keeper Forge App Configuration of EPM Webhooks

*** ### User Guide for Jira Workflow * **Navigate to your Jira project (e.g., IT Support, Security Operations)** * Create a new ticket. * **Open a Jira Issue Page** * On the right side panel, look for **Keeper panel** on the right. * The panel will load and display available Keeper actions. * Select action: **Request Access to Record / Request Access to Folder / Request Record Permission Change.** * Fill in form fields (required fields marked \*). * **Submit for Approval** * First submission: Click **Save Request** to submit for admin approval. * Updating existing request: Click **Update Request** to modify your previously saved request. * A confirmation message will appear: **"Request submitted successfully"** or **"Request updated successfully"**.

Action	When to Use
Request Access to Record	Grant or revoke access to individual records; use for time-bound access, temporary access, or team sharing.
Request Access to Folder	Manage folder-level access and permissions for users or teams; useful for temporary project or contractor access.
Request Record Permission Change	Manage granular access to records within shared folders; enforce least-privilege and compliance.
Create New Secret (Admin Only)	Add new records to the Keeper vault; ideal for onboarding and provisioning new credentials.
Update Record (Admin Only)	Modify existing record fields such as passwords, usernames, URLs, or custom fields; for credential updates and password rotation.
Endpoint Privilege Approval (Admin Only)	Review and approve/deny privilege elevation requests from endpoints in real-time

#### **Feature: Request Access to Record** **Description:** Request shared access to specific Keeper records **Capabilities:** * Grant or revoke record access to users by email * Transfer record ownership * Set optional permissions (Allow Sharing, Allow Edit) * Configure access expiration (specific date/time or duration) * Apply permissions recursively to all records in a folder

*** #### **Feature: Request Access to Folder** **Description**: Request access to Keeper shared folders for users or teams. **Capabilities:** * Grant or remove folder access * Assign to individual users or teams * Configure folder permissions: * Can Manage Records * Can Manage Users * Can Share Records * Can Edit Records * Set access expiration

*** #### **Feature: Create New Secret** **Description:** Create new secret records directly in Keeper. **Capabilities:** * Select from available record types (Login, Bank Account, SSH Key, etc.) * Fill in type-specific fields dynamically * Store secrets securely in Keeper vault {% hint style="info" %} **Admin-Only:** Available to Jira Administrators and Project Administrators only {% endhint %}

*** #### **Feature: Update Record** **Description:** Update existing Keeper records. {% hint style="info" %} **Admin-Only:** Available to Jira Administrators and Project Administrators only {% endhint %} **Capabilities:** * Search and select records from the vault * Modify record fields (title, login, password, URL, notes, etc.) * Force update option to override warnings **Note:** You must have "Edit Issues" permission to see and use the Keeper panel.

*** #### **Feature: Manage KEPM Approval Requests** **Description:** Review, approve or deny Keeper Endpoint Privilege Manager (KEPM) requests directly in Jira. **Capabilities:** * Review outstanding requests * Approve elevation or command execution * Deny elevation or command execution

*** ### Troubleshooting #### Debug Mode If the Commander Service Mode REST API is not behaving as expected, enable **debug mode** for detailed logs and troubleshooting. For example: ```ini keeper service-create -p=9009 -c="list,get,record-add" -rm=foreground -q=y --debug ``` Or (Docker): {% code overflow="wrap" %} ``` docker run -d -p 9009:9009 keeper-commander service-create -p 9009 -c "list,get,record-add" -rm foreground -q y --debug ``` {% endcode %} When debug mode is enabled: * Console or Docker logs show detailed request/response traces * Useful for identifying configuration or API communication issues * Should be **disabled in production** to avoid exposing sensitive logs #### Checking Service Status 1. **Check Service Mode Status via CLI** keeper service-status 2. **Verify API Accessibility and Status** * Test API endpoint and check service status: ``` curl -X POST 'http://localhost:8081/api/v2/executecommand-async' \ --header 'Content-Type: application/json' \ --header 'api-key: ' \ --data '{"command": "service-status"}' ``` * Check if server is running and accessible from Jira * Verify firewall rules allow access 3. **Restart Service Mode** **Note**: Tickets will continue to be created using webhook payload data during service outages to ensure no security events are lost. Once service is restored, new tickets will include enriched data from the KEPM approval view command. #### Troubleshooting Problems

Error / Symptom	Cause	Recommended Solution
Connection Failed / Timeout	Service Mode not running or tunnel not reachable	Verify the Service Mode instance is active and accessible. Ensure the Ngrok or Cloudflare tunnel is live and points to the correct port.
401 Unauthorized / 403 Forbidden	Invalid or expired API key	Retrieve the correct API key from Commander Service Mode logs and update it in the Jira configuration screen. Confirm no spaces or extra characters are included.
404 Not Found	Incorrect or incomplete API URL	404 Not Found \| Incorrect or incomplete API URL \| Use the complete API v2 URL including the /api/v2 path (e.g., `https://xxxxx.ngrok.io/api/v2` or `https://xxxxx.mycompany.com/api/v2`). Ensure the tunnel forwards to the same port used by Service Mode.
502 Bad Gateway / 503 Service Unavailable	Service Mode offline or unresponsive	Restart the Service Mode instance and allow it to fully initialize. Review recent logs for configuration or authentication issues.
Actions Fail Despite Successful Connection	Missing commands or insufficient permissions	Confirm all required commands are enabled in Service Mode. Verify Keeper vault access permissions for the account executing the actions.

{% hint style="info" %} Feedback or feature requests? Please [open an issue](https://github.com/Keeper-Security/jira-connector-hub/issues). {% endhint %}