RSS

Confluence Authentication Overview

This post summarizes the different Confluence authentication options that WikiTraccs supports, with a focus on navigating some harder cases.
By Heinrich Ulbricht |

When starting a Confluence to SharePoint migration with WikiTraccs, you need to authenticate with Confluence so that WikiTraccs can access content.

You’ll need a Confluence user account for the migration

You’ll need a Confluence user account to log in with (“migration account”). WikiTraccs’ access to Confluence happens as this user.

WikiTraccs does not support “application permissions” where it would access Confluence as “itself”. WikiTraccs will always access Confluence in the context of a user account.

Anonymous access

There is one exception to the rule that you always need to use a migration account, and that is a Confluence instance with anonymous access enabled.

Anonymous access is good for testing or demo purposes. The quick start tutorial also uses that with a publicly available Confluence instance.

Anonymous access is not recommended for production migrations as certain metadata cannot be retrieved, like information about users (name, email address) and permission configuration.

Interactive login

Interactive Login is the easiest and most compatible authentication type.

WikiTraccs opens a browser window that you’ll use to log in to Confluence with the migration account. WikiTraccs takes over the user session and all requests to Confluence will be made in the context of the migration user account.

Here is more information: Cookie-based authentication / Interactive login.

The session cookies that WikiTraccs uses to take over the user session are:

  • JSESSIONID
  • seraph.confluence
  • tenant.session.token (Confluence Cloud)
  • _shibsession* (Shibboleth identity provider)

In case your identity provider needs additional cookies to identify a logged in user, click the Advanced Settings button and enter those cookie names:

If there are issues with interactive login, like WikiTraccs not being able to start the Chrome browser for interactive login, refer to the troubleshooting article dedicated to getting around those issues: Confluence Authentication Issues.

Personal Token

The Personal Token authentication type uses a special kind of password (“token” or “key”) to log in. This password is created in Confluence in the context of a Confluence user account.

Please refer to this article for configuration details: Personal Access Token.

Confluence Server and Data Center just need the token

Confluence Cloud needs the name as well

The Personal Token is also referred to as Personal Access Token, API Token, or API Key.

Confluence 7.9 started supporting this authentication type.

In Confluence Cloud some transformations may not avilable with this authentication type (Jira Issue List).

The harder cases…

What are hard cases with regard to Confluence authentication?

Here are some hallmarks of a hard case:

  • Interactive Login authentication does not work immediately
  • Personal Token authentication is not available because Confluence is older than version 7.9 or because of multi-factor or other requirements
  • the cookies.txt workaround to provide session cookies manually for Interactive Login does not work

Over time, I encountered the following hard cases:

  • Kerberos prevented WikiTraccs from taking over the session cookies from Interactive Login; only connections made from the Chrome browser were considered valid by the Confluence backend
  • WikiTraccs once could not detect a successful login to Confluence and was thus not able to get the session cookies for Interactive Login; cookies.txt also did not work; reason unknown
  • Confluence could only be connected to using TLS 1.3-secured connections; Windows and the Confluence backend could not negotiate a mutual TLS 1.3 cipher to use; this issue does not affect the Chrome browser as Chrome brings its own cryptographic stack that operates independently of Windows

Note that those cases were the exception and not the rule.

Nevertheless, those cases needed to be handled as some of them were introduced by configuration changes that were made while migrating and thus blockers. So, WikiTraccs got something called the proxy mode.

Proxy Mode

The proxy mode is a workaround for all of the above issues with the Interactive Login authentication type.

Normally, connection and authentication issues tend to be absent when a user logs in to Confluence in the browser, but start appearing once WikiTraccs starts talking to Confluence directly.

If those issues cannot be resolved, there is only one way left: go back to using the browser to connect to Confluence.

That’s what the proxy mode does. WikiTraccs will keep an automated Chrome browser window open and route all requests to Confluence right through that browser.

This comes with some drawbacks as well. Routing everything through the browser is slower. Also, the proxy mode is not perfectly polished, as it is only thought as a workaround. So WikiTraccs might get confused at times with regard to automating the Chrome browser window, which can be resolved by closing and reopening all windows.

But overall the proxy mode is like the silver bullet to authentication issues.

You activate the proxy mode in WikiTraccs Settings -> Misc -> Proxy Confluence API calls through browser:

Summary

When it comes to authenticating with Confluence those are the steps to take:

In WikiTraccs:

  1. Choose the Interactive Login authentication type and test connecting; if that doesn’t work immediately:
  2. Choose the Personal Token authentication type and test connecting; if that isn’t available:
  3. Use the cookies.txt workaround and test connecting using the Interactive Login;
    • if that does work: good; find the missing cookie names and enter them in the Advanced Settings dialog
    • if that doesn’t work:
  4. Use the Proxy Mode in combination with Interactive Login

If your environment blocks connections to certain endpoints, it might also be necessary to provide the Chrome Driver manually. WikiTracccs uses the Chrome Driver to automate the Chrome browser.

General considerations:

  • check if the migration account can be enabled for Personal Token authentication
  • make sure all endpoints can be reached by WikiTraccs, e.g. to download the Chrome driver needed to automate the Chrome browser for Interactive Login
  • make sure the Confluence backend and Windows can work together with regard to supported TLS versions and ciphers

Usually, none of the workarounds are necessary. But now and then they are needed. That’s why they are available.

And if nothing works - get in touch and we’ll have a look.