How to fix 401 unauthorized error loading Jira Roadmap macro in Confluence Data Center

Platform Notice: Data Center Only - This article only applies to Atlassian apps on the Data Center platform.

Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Summary

This article helps you resolve a 401 unauthorized error when loading the Jira Roadmap macro in Confluence Data Center connected to Jira Data Center, especially when using custom SSO solutions.

Diagnosis

Environment

  • Confluence Data Center 9.x

  • Jira Data Center 10.x

  • Application link with OAuth (impersonation)

The Jira advanced roadmap macro doesn't load in Confluence and returns with a 401 unauthorized message.

'Authentication failed: request lacks valid credentials for the target resource (HTTP 401 – Unauthorized)'

Cause

This issue can occur when custom SSO solutions, such as Waffle, interfere with the OAuth authentication flow between Jira and Confluence.

Additional environment variables or customizations in Jira's seraph-config.xml may prevent proper authentication, resulting in a 401 unauthorized error when loading the Jira Roadmap macro in Confluence. Missing allowlist entries for application URLs can also contribute to this problem.

Solution

Follow these steps to resolve the 401 unauthorized error when loading the Jira Roadmap macro in Confluence.

  1. Check application link connectivity:

    • Verify that the application link between Jira and Confluence is configured with OAuth (impersonation) and shows as connected in both applications.

    • Test other application link features to confirm connectivity.

  2. Review allowlist settings:

    • Ensure that the Jira server URL is added to the Confluence allowlist and vice versa.

    • In Confluence, go to Administration > General Configuration > Allowlist and add the Jira base URL if it is not already present.

    • Repeat the process in Jira for the Confluence base URL.

  3. Check for custom SSO interference:

    • If you are using a custom SSO solution (such as Waffle), it may interfere with OAuth authentication between Jira and Confluence

    • Consider migrating to Jira Data Center's native SSO app, which supports authentication fallback for troubleshooting.

  4. Review and modify Jira's seraph-config.xml parameters:

    • Custom environment variables in Jira's seraph-config.xml can cause authentication failures.

    • Remove or comment out the following environment variables if present:

      SERAPH_AUTHENTICATOR=com.sig.jira.plugins.RemoteUserJiraAuth SERAPH_INVALIDATE_SESSION_EXCLUDE_LIST="ASESSIONID,jira.websudo.timestamp,jira.user.project.admin" SERAPH_INVALIDATE_SESSION_ON_LOGIN="false"

    • After making changes, restart Jira for the changes to take effect.

  5. Test the Jira Roadmap macro in Confluence:

    • After applying the changes above, reload the Confluence page containing the Jira Roadmap macro.

    • The macro should now load without returning a 401 unauthorized error.

    Additional troubleshooting steps

    • If the issue persists, enable DEBUG logging for com.atlassian.applinks in both Jira and Confluence to gather more information.

    • Check the atlassian-jira.log and atlassian-confluence.log files for authentication errors or denied gadget requests.

    • Review any 403 errors in the logs, which may indicate missing allowlist entries.

Related KB: Jira Chart Macro not able to display image and getting 401 error

Updated on June 5, 2026
Platform
Data Center only
App
Jira Software Data Center (9.0 and later)
On this pageSummaryDiagnosisCauseSolution

Still need help?

The Atlassian Community is here for you.
Ask the Community