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.