/
TFS4JIRA: Authentication and permissions troubleshooting

TFS4JIRA: Authentication and permissions troubleshooting

Overview

This article provides steps to resolve connectivity issues with the TFS4JIRA synchronizer. For example:

  • Empty project list — probably not authenticated

  • You cannot create issues in this project

  • You are not authorized to perform this operation. Please log in.

These errors typically stem from the Jira credentials used by the synchronizer rather than from the app version.

In a recent case, the issue was resolved by generating the correct Jira API token for the intended synchronization user and using that user’s credentials in the synchronizer configuration. No app upgrade was required.

Common Symptoms

  • Synchronizer displays the following message:

    • Empty project list — probably not authenticated.

  • Jira REST calls in logs return:

    • You cannot create issues in this project.

  • Jira REST calls in logs return:

    • You are not authorized to perform this operation. Please log in.

Root Causes at a Glance

  • The API token or basic auth credentials belong to a different Jira user than the one intended for synchronization.

  • The API token was created under the wrong account (even if both accounts are site admins).

  • The Token expired or was created with restrictive scopes that block required Jira REST operations.

  • The sync user lacks project permissions, including Browse Projects and Create Issues.

Quick Resolution Checklist

Identify the intended sync user account for TFS4JIRA, for example, a dedicated integration user.
Log in to Jira as that same sync user and generate a new unscoped API token from Atlassian account security.
Update the synchronizer configuration to use the sync user’s email and the new token as the password.
Test the connection and verify the Jira project list loads as expected.
Validate that the sync user can manually create an issue in the target Jira project.

Step-by-step troubleshooting

1) Verify which Jira user the synchronizer uses

Open your TFS4JIRA synchronizer profile and confirm the configured Jira username and email. Then, determine which account is the official sync user. This should be the same account used to generate the token.

Do not mix accounts. A token from User A will not authenticate if the synchronizer logs in as User B.

2) Generate a fresh API token for the intended sync user

While signed in as the sync user, go to your Atlassian account security page and create a new API token. Use an unscoped or broadly permitted token compatible with Jira Cloud REST access.

  • Copy the token immediately after creation.

  • It’s preferable to use a dedicated integration account to avoid confusion about ownership or rotation.

3) Update the synchronizer credentials

In the synchronizer:

  • Set Username/Email to the sync user’s Jira email address.

  • Set Password to the newly created API token.

  • Ensure the Jira Cloud mode checkbox is enabled if you use Jira Cloud.

If the credentials are correct and permissions are sufficient, the Jira project list should populate immediately upon testing or refreshing.

4) Confirm permissions by manual test

Still seeing authorization errors? Validate permissions directly in Jira:

  • Sign into Jira as the sync user.

  • Attempt to create an issue in each target project used by the synchronizer.

  • If creation fails or the project is missing from the Create dialog, check the project’s permission scheme and roles.

Required Jira permissions for the sync user

  • Browse Projects

  • Create Issues

  • Edit Issues (typically required for updates)

For Jira Service Management projects, ensure the sync user has the correct agent or project role that grants create access in the project (not only portal or customer access).

Decision guide: credentials vs permissions

If the project list is empty or API calls read:

  • Not authenticated

Fix the credentials, including the email and token generated for that same user.

If the project list loads but issue creation fails with permission errors, fix the project permissions and roles for the sync user.

Best practices to avoid recurrence

  • Use a dedicated, named integration account as the sync user.

  • Store when and where the token was generated and by whom.

    • Rotate on a predictable schedule.

  • Keep the synchronizer and app up to date, but treat authorization and permissions as the first checks before upgrading.

Example Resolution Pattern

A common pattern that resolves permission errors:

  1. Determine the intended sync user or integration account.

  2. Create a new API token while logged in as that sync user.

  3. Update synchronizer credentials to that user’s email and use the new token.

  4. Confirm the user has Browse Projects, Create Issues, and Edit Issues in the target projects.

Even if two accounts are site admins, tokens are user-specific. A token created under Account A will not authenticate requests made as Account B.

Troubleshooting Reference

Recreate the token while explicitly logged in as the sync user. Ensure you paste the token exactly as provided and that Jira Cloud mode is set in the synchronizer. Check for corporate proxies or SSL interception issues that may block authentication requests.

That usually indicates a permission or role issue. Validate permission schemes, project roles. For JSM projects, ensure the user is assigned an agent role that allows them to create issues internally.

Upgrades are generally beneficial, but they won’t correct mismatched users or insufficient permissions. Prioritize credential alignment and permissions first.

Change Log

  • Document refined to emphasize resolution via correct user credentials and permissions rather than app updates.

References