> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/secrets-manager/integrations/jira-workflow.md).

# Jira Workflow

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FP6in8Pz0FT0AS6fxMb31%2FJira%20Workflow.png?alt=media&#x26;token=a03b004a-313d-499d-9063-b86a73e1ac66" alt=""><figcaption></figcaption></figure>

## 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 and SSO Device Admin approvals via tickets created by the companion ITSM app. The vault supports both NSF (Nested Shared Subfolder) and Classic modes. 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                        |

The vault defaults to **NSF** mode. Check **"Use classic permission model"** to switch to Classic mode. Records and folders display NSF/Classic badges in picker dropdown. NSF mode uses role-based permissions, while Classic mode uses individual permission checkboxes — see Vault Modes and Permission Models for the full role list and flag reference.

### **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**     | <p>Needs <strong>Jira Administrator</strong> or <strong>Manage apps</strong> permission to install and configure the Forge app.<br><br>Must access <strong>Jira Settings → Apps</strong> to set up and manage app connections.</p>                                                                                                                                                              |
| **Jira End-User Access**                | <p>Requires <strong>Edit Issues</strong> and <strong>Add Comments</strong> permissions to view and use the Keeper panel<br><br>Works across all Jira Cloud project types; no extra setup needed. See <a href="https://support.atlassian.com/jira-cloud-administration/docs/manage-project-permissions/">Jira Project Permissions</a> for details</p>                                            |
| **Keeper Standard Features**            | <p>Requires an active <a href="https://keepersecurity.com">Keeper Business, Enterprise, or PAM</a> subscription with vault access.</p><p><br>Service account with permissions to create, update, and share records.</p>                                                                                                                                                                         |
| **Endpoint Privilege Manager Features** | <ul><li>Active KeeperPAM subscription</li><li>KEPM module enabled and configured in your Keeper environment</li><li>KEPM deployments, agents, and policies configured</li><li>For more information, see <a href="https://github.com/Keeper-Security/gitbook-secrets-manager/blob/master/endpoint-privilege-manager/overview/README.md">Endpoint Privilege Manager Overview</a></li></ul><p></p> |
| **Keeper Security ITSM App**            | Required for EPM and SSO device admin approval workflows. The ITSM app owns webhook handling and Jira ticket creation, then adds ITSM\_ labels that the Connector Hub detects to render approval panels.                                                                                                                                                                                        |

## **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](/keeperpam/commander-cli/service-mode-rest-api.md) 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 + SSO Device Approval + KEPM features, make sure the following commands are in the list:

{% code overflow="wrap" %}

```
record-add,list,list-sf,ls,get,search,record-type-info,record-update,share-record,share-folder,rti,record-permission,nsf-list,nsf-get,nsf-record-add,nsf-record-update,nsf-share-record,nsf-share-folder,nsf-record-permission,epm,device-approve,service-status
```

{% endcode %}

Command notes:

* `list-sf` — required for Rotate-on-Expiration folder eligibility checks.
* `nsf-*` — required for NSF (Nested Shared Subfolder) mode; omit them only for Classic-only deployments.
* `epm` — required for KEPM approval panel actions and status checks.
* `device-approve` — required for SSO device admin approval actions and pending checks.

4\) For Ngrok Tunneling, ensure the following parameters are included:

```
-ng <ngrok-auth-token> -cd <custom-domain>
```

5\) For Cloudflare Tunneling, ensure the following parameters are included:

```
-cf <cloudflare-tunnel-token> -cfd <cloudflare-custom-domain>
```

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: <your-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 <a href="#step-1-install-the-module" id="step-1-install-the-module"></a>

Before configuring the integration, you must install the Keeper Forge app in your Jira Cloud instance.

See [Forge App Installation Guide](/keeperpam/secrets-manager/integrations/jira-workflow/forge-app-installation.md) for detailed instructions.

### Step 3. Jira Configuration <a href="#step-1-install-the-module" id="step-1-install-the-module"></a>

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**

<figure><img src="/files/82GsXrOUBaK7qUugO1SG" alt=""><figcaption></figcaption></figure>

Jira Admin configuration complete.

***

### Step 4. ITSM Ticket Creation for EPM and Device Approvals

EPM and SSO device approval tickets are now created by the companion **Keeper Security ITSM** app. The Connector Hub no longer handles EPM webhook events or creates EPM tickets. The previous EPM webhook (web trigger) and ticket creation flow have been **removed** from the Forge app.

Configure the ITSM-driven approval flow:

1. Install and configure the Keeper Security ITSM Integration in the same Jira instance
2. In the ITSM app, configure the webhook URL and authentication token
3. In the **Keeper Admin Console** > **Reporting & Alerts** > **Alerts**, configure alerts for:
   * **Agent created approval request** (EPM)
   * **Changed approval request status** (EPM)
   * **Device admin approval requested** (SSO device approval)
4. Add the ITSM app's webhook URL and token as a recipient for these alerts

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FHgvR92oiSiRz2mSVvMN9%2FScreenshot%202026-02-07%20at%207.08.52%E2%80%AFPM.png?alt=media&#x26;token=93d5a37d-6747-4691-b291-65f6b78043a9" alt=""><figcaption><p>Keeper Admin Console - Webhook Configuration</p></figcaption></figure>

5. The ITSM app creates tickets with these labels:

* `ITSM_approval_request_created` — EPM privilege elevation requests
* `ITSM_device_admin_approval_requested` — SSO device approval requests

6. The Connector Hub detects these labels on ITSM-created tickets and renders the appropriate admin panel

{% hint style="warning" %}
**Removed:** The Connector Hub Forge app no longer provides a Web Trigger URL, EPM webhook configuration screen, or EPM ticket creation flow. If you previously configured EPM webhooks directly in the Connector Hub, migrate webhook and ticket creation to the Jira ITSM app.
{% endhint %}

***

### User Guide for Jira Workflow <a href="#step-2-configure-hiera" id="step-2-configure-hiera"></a>

* **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 \*).
* **Vault Mode**
  * The panel defaults to **NSF** mode. Check **"Use classic permission model"** to switch to Classic mode. NSF uses a **Role** dropdown; Classic uses permission **checkboxes** — see Vault Modes and Permission Models.
* **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"**.

<table><thead><tr><th width="176.109375">Action</th><th width="571.59765625">When to Use</th></tr></thead><tbody><tr><td><a href="https://github.com/Keeper-Security/gitbook-secrets-manager/blob/master/commander-cli/command-reference/sharing-commands/README.md#share-record-command"><strong>Request Access to Record</strong></a></td><td>Grant or revoke access to individual records; use for time-bound access, temporary access, or team sharing.</td></tr><tr><td><a href="https://github.com/Keeper-Security/gitbook-secrets-manager/blob/master/commander-cli/command-reference/sharing-commands/README.md#share-folder-command"><strong>Request Access to Folder</strong></a></td><td>Manage folder-level access and permissions for users or teams; useful for temporary project or contractor access.</td></tr><tr><td><a href="https://github.com/Keeper-Security/gitbook-secrets-manager/blob/master/commander-cli/command-reference/sharing-commands/README.md#record-permission-command"><strong>Request Record Permission Change</strong></a></td><td>Manage granular access to records within shared folders; enforce least-privilege and compliance.</td></tr><tr><td><a href="/pages/-McB8Ys3vRnDF6Uz7Bf1#record-add-and-record-update-commands"><strong>Create New Secret</strong></a><br><strong>(Admin Only)</strong></td><td>Add new records to the Keeper vault; ideal for onboarding and provisioning new credentials.</td></tr><tr><td><a href="/pages/-McB8Ys3vRnDF6Uz7Bf1#record-add-and-record-update-commands"><strong>Update Record</strong></a><br><strong>(Admin Only)</strong></td><td>Modify existing record fields such as passwords, usernames, URLs, or custom fields; for credential updates and password rotation.</td></tr><tr><td><a href="https://github.com/Keeper-Security/gitbook-secrets-manager/blob/master/commander-cli/command-reference/endpoint-privilege-manager-commands/README.md#action"><strong>Endpoint Privilege Approval</strong></a><br><strong>(Admin Only)</strong></td><td>Review and approve/deny privilege elevation requests from endpoints. Tickets are created by the ITSM app with <code>ITSM_approval_request_created</code> label.</td></tr><tr><td><strong>Device Admin Approval</strong><br><strong>(Admin Only)</strong></td><td>Review and approve/deny SSO login device approval requests. Tickets are created by the ITSM app with <code>ITSM_device_admin_approval_requested</code> label.</td></tr></tbody></table>

### **Vault Modes and Permission Models**

Sharing and permission actions support two vault modes. The panel defaults to **NSF (Nested Shared Subfolder)** mode; check **"Use classic permission model"** to switch to **Classic** mode. Records and folders display an **NSF** or **Classic** badge in the picker dropdown so you always know which model applies.The two modes express permissions differently:

* **NSF mode** uses a single **Role** dropdown that bundles a set of permissions.
* **Classic mode** uses individual permission **checkboxes**.

**NSF roles**

| Role                          | Grants the user the ability to                                |
| ----------------------------- | ------------------------------------------------------------- |
| **Viewer**                    | View content and participants                                 |
| **Share Manager**             | Manage share permissions, invite others, and approve requests |
| **Content Manager**           | Manage content                                                |
| **Content and Share Manager** | Manage content and manage share permissions                   |
| **Full Manager**              | Edit, share, and manage ownership                             |

**Role rules:** A **Role** is required when the action is **grant**. For **revoke**, the role is optional and acts as a filter. The role is ignored for folder **remove** actions and record **owner** (ownership transfer) actions.**Classic permissions**In Classic mode, each action exposes its own permission checkboxes instead of a role:

* **Request Access to Record:** Allow Sharing, Allow Writing
* **Request Access to Folder:** Can Manage Records, Can Manage Users, Can Share Records, Can Edit Records
* **Update Record Permissions in Folder:** Can Share Records, Can Edit Records, Apply Recursively

***

#### **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 permissions based on vault mode:
  * **NSF:** select a **Role** (Viewer, Share Manager, Content Manager, Content and Share Manager, or Full Manager) — required when granting access
  * **Classic:** check **Allow Sharing** and/or **Allow Writing**
* Configure access expiration (specific date/time or duration)
* Apply permissions recursively to all records in a folder
* Supports both NSF and Classic vault modes (see Vault Modes and Permission Models)

<figure><img src="/files/RAkrzLEi46K32oCrapPs" alt=""><figcaption><p>Request Access to Record</p></figcaption></figure>

***

#### **Feature: Request Access to Folder**

**Description**: Request access to Keeper shared folders for users or teams.

**Capabilities:**

* Grant or remove folder access (actions: grant / remove)
* Assign to individual users or teams
* Configure folder permissions based on vault mode:
  * **NSF:** select a **Role** (Viewer, Share Manager, Content Manager, Content and Share Manager, or Full Manager) — required when granting access
  * **Classic:** check any of **Can Manage Records**, **Can Manage Users**, **Can Share Records**, **Can Edit Records**
* Set access expiration
* Supports both NSF and Classic vault modes (see Vault Modes and Permission Models)

<figure><img src="/files/QqQw8mmOMkcsdcLuReom" alt=""><figcaption><p>Request Access to Folder</p></figcaption></figure>

***

#### **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
* Supports both NSF and Classic vault modes

{% hint style="info" %}
**Admin-Only:** Available to Jira Administrators and Project Administrators only
{% endhint %}

<figure><img src="/files/fx0uNw8AZUFytZmRfPHM" alt=""><figcaption><p>Create New Secret - Login type record</p></figcaption></figure>

***

#### **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
* Supports both NSF and Classic vault modes

**Note:** You must have "Edit Issues" permission to see and use the Keeper panel.

<figure><img src="/files/23ZgJ2AjhG05cGV8V0dh" alt=""><figcaption><p>Update Record</p></figcaption></figure>

***

#### **Feature: Manage KEPM Approval Requests**

**Description:** Review, approve or deny Keeper Endpoint Privilege Manager (KEPM) requests directly in Jira.

EPM tickets are now created by the companion Jira ITSM app with the `ITSM_approval_request_created` label. The Connector Hub only detects this label and renders the EPM Approval Panel. The previous EPM webhook (web trigger) and ticket creation flow have been removed from the Forge app.

**Capabilities:**

* Review outstanding requests with requester details, application name, and justification
* Live countdown timer showing remaining time before request auto-expires (30-minute window)
* Approve or deny elevation/command execution
* Automatic detection if request was already processed outside Jira

<figure><img src="/files/QpHvAaGDBPCcS3hekDEK" alt=""><figcaption><p>KEPM Approval Request</p></figcaption></figure>

***

#### **Feature: Manage Device Admin Approval Requests**  <a href="#troubleshooting" id="troubleshooting"></a>

**Description:** Review, approve or deny SSO login device approval requests directly in Jira.

When a user logs in via SSO on a new device, the ITSM app creates a Jira ticket with the `ITSM_device_admin_approval_requested` label. The Connector Hub detects this label and renders the Device Approval Panel.

**Capabilities:**

* View pending SSO device approval requests with requester email, device name, machine name, IP address, and client version
* Approve or deny device registration via `device-approve --approve` / `--deny` commands
* Automatic detection if request was already processed outside Jira (e.g., via Keeper Admin Console)
* Device approvals do not auto-expire (unlike EPM requests)

<figure><img src="/files/q0ro4gTTu7022c3LYvGE" alt=""><figcaption><p>SSO Device Approval</p></figcaption></figure>

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

#### Debug Mode <a href="#debug-mode" id="debug-mode"></a>

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: <your-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**: EPM and SSO device approval tickets are created by the Jira ITSM app using webhook payload data, regardless of Commander Service Mode status. The Connector Hub does not create these tickets. Once Service Mode is available, the approval panels enrich ticket data with live status from the KEPM approval view and device-approve commands.

#### Troubleshooting Problems <a href="#common-issues" id="common-issues"></a>

<table><thead><tr><th width="197.94140625">Error / Symptom</th><th width="178.16796875">Cause</th><th>Recommended Solution</th></tr></thead><tbody><tr><td><strong>Connection Failed / Timeout</strong></td><td>Service Mode not running or tunnel not reachable</td><td>Verify the Service Mode instance is active and accessible. Ensure the Ngrok or Cloudflare tunnel is live and points to the correct port.</td></tr><tr><td><strong>401 Unauthorized / 403 Forbidden</strong></td><td>Invalid or expired API key</td><td>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.</td></tr><tr><td><strong>404 Not Found</strong></td><td>Incorrect or incomplete API URL</td><td>404 Not Found | Incorrect or incomplete API URL | Use the complete API v2 URL including the /api/v2 path (e.g., <code>https://xxxxx.ngrok.io/api/v2</code> or <code>https://xxxxx.mycompany.com/api/v2</code>). Ensure the tunnel forwards to the same port used by Service Mode.</td></tr><tr><td><strong>502 Bad Gateway / 503 Service Unavailable</strong></td><td>Service Mode offline or unresponsive</td><td>Restart the Service Mode instance and allow it to fully initialize. Review recent logs for configuration or authentication issues.</td></tr><tr><td><strong>Actions Fail Despite Successful Connection</strong></td><td>Missing commands or insufficient permissions</td><td>Confirm all required commands are enabled in Service Mode. Verify Keeper vault access permissions for the account executing the actions.</td></tr></tbody></table>

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.keeper.io/keeperpam/secrets-manager/integrations/jira-workflow.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.