> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rad.security/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira Cloud

> Configure Jira Cloud integration with RAD Security for automated security incident management.

# Jira Cloud Integration Setup

This guide walks you through integrating Jira Cloud with RAD Security for automated security incident and ticket management, enabling you to automatically create, update, and track security incidents as Jira issues.

Jira Cloud provides flexible issue tracking and project management capabilities, making it ideal for managing security incidents, vulnerabilities, and remediation workflows.

## Prerequisites

Before you begin, ensure you have:

<Check>
  * Admin access to Jira Cloud
  * Ability to create users and groups in Jira
  * Access to RAD Security workspace with integration permissions
</Check>

<Info>
  **Service User Recommended:** Create a dedicated service user for this integration rather than using a personal account. This ensures the integration continues working when team members leave or change roles.
</Info>

***

## Step 1: Log in to Jira as Admin

<Steps>
  <Step title="Access Jira Admin">
    Log in to your Jira Cloud instance with administrator privileges
  </Step>

  <Step title="Navigate to User Management">
    Click the **gear icon** (⚙️) in the top right corner and select **User Management**
  </Step>
</Steps>

***

## Step 2: Create Group for Integration

<Steps>
  <Step title="Navigate to Groups">
    Click on **Groups** in the left panel
  </Step>

  <Step title="Create New Group">
    1. Click **Create group**
    2. Enter a group name (e.g., "RAD Security Integration")
    3. Add a description (optional)
  </Step>

  <Step title="Assign Product Access">
    In the **Group product access** section at the bottom:

    1. Select the product: **User**
    2. This grants: "Can access the product, with no product admin permissions"
    3. Click **Save**

    <Note>
      This provides a simple, secure setup. Advanced users can configure project-based permissions for more granular control. Refer to [Jira's documentation](https://confluence.atlassian.com/adminjiraserver/user-management-938847014.html) for details.
    </Note>
  </Step>

  <Step title="Configure Project Permissions (If Needed)">
    Depending on your Jira configuration, you may need to grant read and write access to specific projects:

    1. Navigate to **Project settings**
    2. Select the projects the integration should access
    3. Grant appropriate permissions to the group

    <Info>
      This step is only necessary for certain product configurations. Consult Jira documentation for project-specific permission requirements.
    </Info>
  </Step>
</Steps>

***

## Step 3: Create Service User

<Steps>
  <Step title="Navigate to Users">
    Click on **Users** in the left panel
  </Step>

  <Step title="Create New User">
    1. Click **Create user**
    2. Enter user details:
       * **Email address** - Use a service email (e.g., `rad-security@company.com`)
       * **Full name** (e.g., "RAD Security Integration")
       * **Password** - Create a secure password
  </Step>

  <Step title="Assign User to Group">
    In the lower part of the user creation panel:

    1. Find the **Groups** section
    2. Add the user to the group you created in Step 2
    3. Click **Save**
  </Step>
</Steps>

<Warning>
  **Service User Strongly Recommended:** While you can use an existing user account, creating a dedicated service user is strongly recommended. If a personal account is used and that person leaves your organization, the integration will break.
</Warning>

***

## Step 4: Generate API Token

<Steps>
  <Step title="Log Out and Log In as Service User">
    1. Log out of your admin account
    2. Log in using the service user credentials you created in Step 3
  </Step>

  <Step title="Access Personal Settings">
    Click the **gear icon** (⚙️) in the top right corner and select **Personal Settings** (Atlassian account settings)
  </Step>

  <Step title="Navigate to Security">
    In the top menu, click on **Security**
  </Step>

  <Step title="Manage API Tokens">
    Click **Create and manage API tokens**
  </Step>

  <Step title="Create New Token">
    In the API tokens panel:

    1. Click **Create API token**
    2. Enter a label (e.g., "RAD Security Integration")
    3. Click **Create**
  </Step>

  <Step title="Copy Token">
    **Immediately copy the API token** that appears

    <Warning>
      **This is your only chance to view the token!** If you lose it, you'll need to revoke and create a new token. Store it securely in a password manager or secrets vault.
    </Warning>
  </Step>
</Steps>

<Info>
  **Token Rotation Best Practice:** Rotate API tokens every 90 days as a security best practice. See [Atlassian's token management documentation](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) for more details.
</Info>

***

## Step 5: Configure in RAD Security

Navigate to your RAD Security workspace and configure the Jira Cloud integration with the following parameters:

### Required Parameters

| Parameter    | Description                                   | Example                               |
| ------------ | --------------------------------------------- | ------------------------------------- |
| **URL**      | Root URL of your Jira Cloud instance          | `https://your-company.atlassian.net/` |
| **Username** | Email address of the service user from Step 3 | `rad-security@company.com`            |
| **Secret**   | API Token from Step 4                         | `your-api-token-here`                 |

<Note>
  The URL should be your Jira Cloud root URL in the format `https://<tenant>.atlassian.net/` where `<tenant>` is your organization's Jira subdomain.
</Note>

***

## Verify Integration

After completing the setup, verify your integration is working:

1. Navigate to **Data Sources > Integrations > Ticketing** in RAD Security
2. Locate your Jira Cloud integration
3. Check the connection status shows as **Connected**
4. Test by creating a sample issue from RAD Security

<Check>
  Your Jira Cloud integration is now configured! RAD Security can now automatically create and manage security issues in Jira.
</Check>

## What Data is Synced

Once configured, RAD Security will sync the following with Jira Cloud:

<AccordionGroup>
  <Accordion title="Issue Creation" icon="ticket">
    * Automatically create Jira issues for security incidents
    * Include detailed incident context and metadata
    * Attach relevant threat intelligence
    * Add affected assets and resources
    * Include remediation recommendations
  </Accordion>

  <Accordion title="Bi-directional Sync" icon="arrows-rotate">
    * Update issue status in both systems
    * Sync comments and activity
    * Track resolution progress
    * Update priority and severity
    * Maintain audit trail
  </Accordion>

  <Accordion title="Custom Field Mapping" icon="sliders">
    * Map RAD Security fields to Jira fields
    * Configure custom field values
    * Set default issue types
    * Define priority mappings
    * Configure assignment rules
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Automated Ticket Creation" icon="wand-magic-sparkles">
    Automatically create Jira tickets when security incidents, vulnerabilities, or policy violations are detected.
  </Card>

  <Card title="Workflow Integration" icon="diagram-project">
    Integrate security findings into existing development and operations workflows in Jira.
  </Card>

  <Card title="Remediation Tracking" icon="list-check">
    Track security remediation efforts through Jira's project management features.
  </Card>

  <Card title="Centralized Management" icon="building">
    Manage security incidents alongside other operational issues in a centralized platform.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication Failed" icon="triangle-exclamation">
    **Possible causes:**

    * Username (email) is incorrect
    * API token is incorrect or expired
    * User account was disabled or deleted
    * Token was revoked

    **Solution:**

    * Verify the username matches the service user's email exactly
    * Check that the API token is copied correctly (no extra spaces)
    * Confirm the service user account is still active in Jira
    * Try logging in to Jira with the service user credentials
    * Generate a new API token if needed
  </Accordion>

  <Accordion title="Insufficient Permissions" icon="shield-exclamation">
    **Possible causes:**

    * User not assigned to correct group
    * Group lacks product access
    * Missing project-level permissions
    * User removed from group

    **Solution:**

    * Verify the service user is a member of the integration group
    * Check the group has "User" product access
    * Review project-specific permissions if configured
    * Ensure the user hasn't been removed from the group
    * Check that group permissions haven't changed
  </Accordion>

  <Accordion title="Cannot Create Issues" icon="ticket-slash">
    **Possible causes:**

    * Missing project permissions
    * Issue type not available
    * Required fields not mapped
    * Project doesn't exist

    **Solution:**

    * Verify the user has "Create Issues" permission in target projects
    * Check that the issue type exists in the project
    * Ensure all required fields are properly mapped
    * Confirm the target project is active and accessible
    * Review project workflow restrictions
  </Accordion>

  <Accordion title="Wrong Jira Instance URL" icon="globe">
    **Possible causes:**

    * Using Jira Server URL instead of Cloud URL
    * Missing trailing slash
    * Incorrect subdomain
    * Including additional path components

    **Solution:**

    * Ensure you're using the Cloud URL format: `https://<tenant>.atlassian.net/`
    * Include the trailing slash: `https://your-company.atlassian.net/`
    * Verify the subdomain matches your organization
    * Don't include paths like `/jira/` or `/secure/`
  </Accordion>

  <Accordion title="Token Expired or Revoked" icon="key-skeleton">
    **Possible causes:**

    * Token was manually revoked
    * Account password was changed (doesn't affect API tokens)
    * Token reached configured expiration

    **Solution:**

    * Log in as the service user
    * Navigate to Security > API tokens
    * Check if the token still exists and is active
    * Create a new token if the old one was revoked
    * Update the token in RAD Security integration settings
  </Accordion>

  <Accordion title="Service User Account Issues" icon="user-slash">
    **Possible causes:**

    * Service user was deleted
    * Account was suspended or deactivated
    * Email address was changed
    * User lost group membership

    **Solution:**

    * Log in as admin and verify the service user exists
    * Check the account status is Active
    * Verify the email address hasn't changed
    * Confirm group membership is intact
    * Reactivate the account if it was suspended
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use Service Accounts" icon="user-gear">
    Always use a dedicated service account with a service email, never a personal account tied to an individual.
  </Card>

  <Card title="Least Privilege Access" icon="shield-halved">
    Only grant the minimum permissions required. Avoid admin privileges for integration accounts.
  </Card>

  <Card title="Rotate Tokens Regularly" icon="rotate">
    Rotate API tokens every 90 days or according to your security policy.
  </Card>

  <Card title="Secure Token Storage" icon="lock">
    Store API tokens in a secure password manager or secrets vault. Never commit to version control.
  </Card>

  <Card title="Monitor Integration Activity" icon="chart-line">
    Regularly review issues created by the integration to ensure proper operation.
  </Card>

  <Card title="Audit Permissions" icon="clipboard-list">
    Periodically review the service user's group membership and permissions.
  </Card>

  <Card title="Track Token Usage" icon="key">
    Document which tokens are used for which integrations to simplify rotation and troubleshooting.
  </Card>

  <Card title="Service Email Management" icon="envelope">
    Ensure the service email is monitored or forwarded to the appropriate team.
  </Card>
</CardGroup>

## Token Rotation

To rotate your Jira API token:

<Steps>
  <Step title="Create New Token">
    1. Log in as the service user
    2. Go to Personal Settings > Security > API tokens
    3. Create a new API token with a different label
  </Step>

  <Step title="Update Integration">
    Update the token in RAD Security integration settings
  </Step>

  <Step title="Verify Connection">
    Test that the integration still works with the new token
  </Step>

  <Step title="Revoke Old Token">
    Once verified, revoke the old token in Jira
  </Step>
</Steps>

## Additional Resources

<CardGroup cols={2}>
  <Card title="Jira User Management" icon="book" href="https://confluence.atlassian.com/adminjiraserver/user-management-938847014.html">
    Official Atlassian guide to user management in Jira
  </Card>

  <Card title="API Token Management" icon="key" href="https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/">
    Learn how to create and manage API tokens
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Ticketing Overview" icon="ticket" href="/rad-security/integrations/ticketing/overview">
    Learn about ticketing integrations
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/rad-security/platform/workspace">
    Configure custom workflows for incident response
  </Card>

  <Card title="Alerts & Incidents" icon="bell" href="/rad-security/platform/workspace">
    Set up alert rules that trigger Jira ticket creation
  </Card>

  <Card title="Automation Tools" icon="robot" href="/rad-security/integrations/data-sources">
    Explore automation platform integrations
  </Card>
</CardGroup>