RFC-35: Custom Domains Support For Confluence

Summary of Project

Similar to the recent RFC for Custom Domains for Jira, Custom Domains support is now also coming to Confluence. This means that customers will be able to choose domains for their Confluence instead of using default atlassian.net domain. While no API changes are planned, it is important for Ecosystem apps to properly use the existing siteUrl (Forge apps) and baseUrl, displayUrl fields (Connect apps) as their values will be distinct when custom domains are enabled. We would like to invite you to validate these changes in testing instances to assess any impact on your apps. Your collaboration and feedback are essential to us as we work together to deliver a seamless experience to our mutual customers.

  • Publish : 9 Feb 2024
  • Discuss : 29 Mar 2024 (updated)
  • Resolve : 12 Apr 2024 (updated)

Problem / Opportunity

Cloud customers have long wanted to access their Atlassian products using their own domain names, e.g. use ***.acme.com, instead of the *.atlassian.net domain they use today. We are excited to announce that with our next Custom Domains milestone, customers can enjoy the flexibility of customizing their domain names for Jira family products to promote their own brands with simple setup steps.

Org admins will have a one-click toggle to activate or deactivate their custom domains. When activated, there is a possibility that your apps may fail to load if you don’t use API properly. See Proposed Solution section for more details.

Proposed Solution

In this post, we will provide important details about this upcoming change and what you need to know as an ecosystem developer.

API URL For Custom Domains

There will be no change for REST API URL when Custom Domains is configured. More specifically, all browser requests should be using custom domain URL, and all API requests will continue to be made via the default *.atlassian.net URL.

Such decision is made to address security concerns. As a rule of thumb, tokens with global scope cannot be used on Custom Domains to limit any impact in case of a security incident.

API Token & OAuth Apps

Considering the rule of thumb above, URL for UI and API used by API Token & OAuth apps will no longer be the same. You may find your app needs to perform extra work to handle conversion between custom domain URL and the default *.atlassian.net URL.

If you encounter difficulties handling URL conversions, please reach out with your use case.

Forge apps

Site domains are mostly abstracted away in Forge so we don’t expect Custom Domains to have an impact on Forge apps. That said, we still encourage you to test your apps in a site with Custom Domains enabled and confirm expected functionality.

The siteURL property on the Custom UI Bridge will automatically return the custom domain URL for sites that have the Custom Domains feature enabled. So if your app uses this property for display or navigation it should continue to work seamlessly.

Connect apps

For Connect apps we expect that most apps will function correctly without any changes. If your app is displaying URLs to the user, be sure to review your usage of the baseUrl and displayUrl returned as part of the lifecycle events sent to connect apps.

If a tenant does not have a custom domain, all of these values will be equal to each other. However, if a tenant does have a custom domain, the displayUrl field will contain the custom domains that should be used when displaying a URL to the user (examples see below).

No Custom Domain
{
  'baseUrl': "url.atlassian.net",
  'displayUrl: "url.atlassian.net"
}
With a Custom Domain
{
  'baseUrl': "url.atlassian.net",
  'displayUrl: "url.custom-domain.com"
}

If, as a developer, you are currently using the baseUrl for displaying URLs to the user, these should be replaced with displayUrl so that the relevant custom domains are always displayed when present for a particular tenant.

Additionally, If you have enabled Content Security Policy for you apps, or declared an X-Frame-Header limiting to app to render in an *.atlassian.net domain, your apps will not render in any tenant that has a custom domain. This should be amended for your apps to be able to function properly across all tenants.

Asks

As we prepare to go live to support Custom Domains for Confluence customers, we seek your collaboration in validating and mitigating any potential impact that these changes may have on your apps. We plan to apply a 3 month deprecation notice period and fully support Custom Domains afterwards.

More specifically, we seek your help in following aspects:

  • Be aware of the upcoming changes and plan to adopt Custom Domains information for your app experience
  • Thoroughly test your apps and report back any impact or issues that you may encounter. To facilitate this process, we will provide means to set up Custom Domains
  • If your apps are impacted by the changes, we are looking forward to working together with you to resolve any issues before releasing Custom Domains to general public.

Please register for the testing with your tenant details and report any issues you run into here

We will enable Custom Domains feature in your tenant within 48 business hours after you register.

1 Like

Hi @JohnHooper ,

This is a breaking change, especially for the security schemes and the required Content Security Policy.

Can you please extend the deprecation period from 3 months to the standard 6 month deprecation period?

(Also you link to the lifecycle events points to Jira documentation. Is there also documentation for Confluence?)

2 Likes

Hi,
I have 2 follow up questions:

Will atlassian-connect-express support custom domains by automatically setting the Content Security Policy?

How do static Connect apps need to handle custom domains? Static Connect apps typically have no backend, and don’t store any lifecycle events.

5 Likes

Help! I’m getting…

david@… doesn’t have access to Jira on earlyaccessprogram.atlassian.net .

…from id.atlassian.com when I try to register for that early access.

:man_shrugging:

5 Likes

Thank you for publishing those detailed RFCs.

  • Did I miss an announcement, or are Custom Domains only for Confluence and Jira Service Desk for the moment, but not Jira Software and not Jira Work?
  • As David said, https://earlyaccessprogram.atlassian.net is not accessible for vendors at this time,
  • Are there any plans to implement the same strange feature as on JSD, which mandated keywords in the URL, such as jira.jira.example.com? Alternatively, do you have plans to get rid of it, and/or to provide a rationale which withstands the peer review to help us accept this constraint?
  • Does this RFC fully and exhaustively highlight the difficulties, for example the CSPs that we have to tune that are not mentioned, which are mandatory for other parts of the Marketplace program?

It overall sounds good but it seems we cannot give approval until we discover the difficulties during the 3-month deprecation period.

5 Likes

Hi @JohnHooper

Thanks for posting this.

  1. Can you please provide specific guidance on what CSP Atlassian prefers Connect apps to use for sites with custom domains enabled? (Setting CSP is currently listed as an Atlassian requirement for Connect apps.)
  2. How will Connect apps be notified of the implementation of a custom domain? Will install lifecycle hooks be sent to all installed apps? If so, what is the expected latency between the customer’s configuration change and delivery of the lifecycle event?
  3. Like David, I also do not have permission to access the enrollment site.
4 Likes

Hi @JohnHooper,

This feature is particularly impactful for purely frontend apps or those that have very limited use of the backend.

For us, it’s absolutely vital to have the information about the currently active domain within the JavaScript API.
This need has already been tracked here: [ACEJS-183] - Ecosystem Jira.
However, it doesn’t seem that there has been any progress on this matter. Could you please review this requirement and reprioritize this ticket?

6 Likes

Hi John, thank you for the update.
Will this help with ranking Confluence Cloud pages in Google search?
As I know only DC pages Google ranks now.

Thanks,
Zoriana

1 Like

Thanks @marc . Could you please share more how the security schemes and required content security policy will be a breaking change for you?

And yes, the lifecycle events documentation now points to Confluence information. Thank you for catching that. (link: https://developer.atlassian.com/cloud/confluence/connect-app-descriptor/#app-descriptor-structure)

1 Like

Hi @david - apologies for that. We’ve updated the settings for the form and the link so you should be able to access it now. Please let us know if you’re still having issues

2 Likes

Hi @aragot

  • JSW and JSM are a bit ahead of Confluence on custom domains. Here is the public roadmap item for their GA (ETA: Q2 2024) if you’d like to follow along

  • Thanks for catching this as well. Updated.

  • The main implementation detail is that /wiki is required, for example if a company called Acme owns acme.com , they would be able to use their Confluence Cloud instance on docs.acme.com/wiki

  • I will bring in a more technical member of our team to answer that Q

1 Like

Thank you @scott.dudley , @alessandrodistefano , and @ZorianaBogutska_Adap . I will relay your questions to our team and we’ll be back with responses to your items soon

Thanks @JohnHooper . I was under the impression that https://developer.atlassian.com/platform/marketplace/security-requirements/#connect-apps mandates that we set a CSP with origins similar to

"default-src": ["'self'", "https://*.atlassian.com", "https://*.atlassian.net", "https://*.atl-paas.net"],

However it seems that might actually not be required. We do this currently for security, and we would need to adopt if the urls differ for custom domains.

Hey @scott.dudley,

Similar to Jira and JSM, a new installation lifecycle hook will be sent as soon as a custom domain either moves from an inactive → active or active → inactive state with the associated details.

1 Like

Hey @alessandrodistefano,

Keen to explore this further. The custom domain would be available at all times from the AP.getLocation method due to redirection to the custom domain; however this would also include the entire relative URL, not just the FQDN.

What type of information / properties would be beneficial to support your frontend app?

1 Like

I think the CSP for origins is only required for lifecycle events eg install.

If you’ve already tested out how your Confluence apps & macros work in Confluence Embedded Pages e.g. in Refined for Confluence Cloud (and enabling embedded pages) you will already see how the macros are failing if your CSP is “too tight”.

1 Like

Hi @JohnHooper ,

Will ACE support the displayUrl as a context variable? At this moment it is not supported, and that means rendering the default templates in ACE with the custom domains does not work as is.

Can we expect Atlassian to support this officially in ACE?

2 Likes

@JohnHooper +1 for displayUrl in Atlassian Connect.

2 Likes

Thanks @marc and @david - would you mind giving us a bit more context into how you would plan to utilize displayUrl so that we can determine if / how we’re able to support?

We use ACE and here are a couple of examples where hostBaseUrl is used today for URL’s in our page templates destined for user viewing. I think most of these would have to be replaced with the displayUrl because hostBaseUrl would send the users to the wrong site?

avatarUrl: `${hostBaseUrl}/wiki/aa-avatar/${u.accountId}`

<a href="{{hostBaseUrl}}/wiki/pages/viewpageattachments.action?pageId={{page.contentId}}">Attachments</a>

<a href="{{hostBaseUrl}}/users/viewmysettings.action">Confluence User Profile</a>


2 Likes