PAT auth issues after recent upgrade to v7.1.2

[cisco-sbg-mgiassa-ai]

Good day,

I have a Confluence-builder project that's been churning away daily for a couple years now. I recently upgraded to v7.1.2 of Sphinx (latest confluence-builder), and cannot authenticate anymore via confluence_publish_token (using a PAT):

Traceback (most recent call last):
  File "/usr/local/lib/python3.8/dist-packages/sphinx/cmd/build.py", line 285, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/local/lib/python3.8/dist-packages/sphinx/application.py", line 268, in __init__
    self._init_builder()
  File "/usr/local/lib/python3.8/dist-packages/sphinx/application.py", line 338, in _init_builder
    self.builder.init()
  File "/usr/local/lib/python3.8/dist-packages/sphinxcontrib/confluencebuilder/builder.py", line 102, in init
    validate_configuration(self)
  File "/usr/local/lib/python3.8/dist-packages/sphinxcontrib/confluencebuilder/config/checks.py", line 754, in validate_configuration
    raise ConfluencePublishMissingUsernameAuthConfigError
sphinxcontrib.confluencebuilder.config.exceptions.ConfluencePublishMissingUsernameAuthConfigError: confluence username not provided

This was never an issue before. An extended error message indicates:

A publishing password has been configured with 'confluence_api_token';
however, no username has been configured. Ensure 'confluence_server_user' is
properly set with the publisher's Confluence username.

However, when I do that, a new error arises:

Traceback (most recent call last):
  File "/usr/local/lib/python3.8/dist-packages/sphinx/cmd/build.py", line 285, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/local/lib/python3.8/dist-packages/sphinx/application.py", line 268, in __init__
    self._init_builder()
  File "/usr/local/lib/python3.8/dist-packages/sphinx/application.py", line 338, in _init_builder
    self.builder.init()
  File "/usr/local/lib/python3.8/dist-packages/sphinxcontrib/confluencebuilder/builder.py", line 102, in init
    validate_configuration(self)
  File "/usr/local/lib/python3.8/dist-packages/sphinxcontrib/confluencebuilder/config/checks.py", line 780, in validate_configuration
    warnings(validator)
  File "/usr/local/lib/python3.8/dist-packages/sphinxcontrib/confluencebuilder/config/notifications.py", line 92, in warnings
    logger.warn('multiple authentication options configured')
  File "/usr/local/lib/python3.8/dist-packages/sphinxcontrib/confluencebuilder/logger.py", line 110, in warn
    ConfluenceLogger.logger.warning(msg, *args, **kwargs)
  File "/usr/lib/python3.8/logging/__init__.py", line 1812, in warning
    self.log(WARNING, msg, *args, **kwargs)
  File "/usr/local/lib/python3.8/dist-packages/sphinx/util/logging.py", line 124, in log
    super().log(level, msg, *args, **kwargs)
  File "/usr/lib/python3.8/logging/__init__.py", line 1844, in log
    self.logger.log(level, msg, *args, **kwargs)
  File "/usr/lib/python3.8/logging/__init__.py", line 1512, in log
    self._log(level, msg, args, **kwargs)
  File "/usr/lib/python3.8/logging/__init__.py", line 1589, in _log
    self.handle(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 1599, in handle
    self.callHandlers(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 1661, in callHandlers
    hdlr.handle(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 950, in handle
    rv = self.filter(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 811, in filter
    result = f.filter(record)
  File "/usr/local/lib/python3.8/dist-packages/sphinx/util/logging.py", line 424, in filter
    raise exc
sphinx.errors.SphinxWarning: multiple authentication options configured

So, chicken-and-egg problem that entirely prevents (at least in this case) PAT-based authentication.

[jdknight]

Thanks for the report. Not yet ruling out an error in the implementation, I do have some questions about the configuration being used. The error:

multiple authentication options configured

Is an indication that there is a mix of configuration authentication types being used. You mention that you are using confluence_publish_token to authenticate with a Confluence Data Center instance. But you are also getting a message about using confluence_api_token which is for Confluence Cloud instances:

A publishing password has been configured with 'confluence_api_token'...

With the new versions of this extension, we have a bit more explicit checks in the configuration that help detect odd configuration cases -- that now it is explicitly stopping a run with the new detection logic.

I'd be curious for a report on what configuration items are set. In theory, we should not be mixing entries like PAT and user/API tokens together. If such a configuration was required to get it to work for you instance, I would be interested to know -- it wouldn't make sense to me to why, but I would take the time to investigate how a requirement was needed (and in turn, make appropriate changes to the extension).

[cisco-sbg-mgiassa-ai]

@jdknight Thanks for the rapid help. I'll get that report ASAP. Cheers!

[cisco-sbg-mgiassa-ai]

@jdknight Here we go:

(system)
 platform: Linux-5.15.0-1066-aws-x86_64-with-glibc2.29
   python: 3.8.10 (default, Jul 29 2024, 17:02:10) [GCC 9.4.0]
   sphinx: 7.1.2
 docutils: 0.20.1
 requests: 2.32.3
  urllib3: 2.2.2
  builder: 2.6.1

(configuration)
confluence_api_token: (set)
confluence_ask_password: False
confluence_cleanup_purge: True
confluence_editor: v1
confluence_footer_file: assets/footer.tpl
confluence_header_file: assets/header.tpl
confluence_include_search: True
confluence_lang_overrides: {'dockerfile': 'Bash', 'makefile': 'Bash', 'shell': 'Bash', 'diff': 'Diff', 'yaml': 'YAML'}
confluence_page_hierarchy: True
confluence_parent_page: (set)
confluence_prev_next_buttons_location: top
confluence_publish: True
confluence_publish_debug: True
confluence_publish_dryrun: False
confluence_publish_prefix: ********
confluence_publish_token: (set)
confluence_server_url: https://(removed)
confluence_space_key: (set; upper)

(confluence instance)
 connected: no

[jdknight]

@cisco-sbg-mgiassa-ai, thanks for the update.

Is there a reason why confluence_api_token and confluence_publish_token is set? In theory, a user should only need to use just confluence_publish_token (data center/server, i.e. on-prem) or confluence_api_token with confluence_server_user (Cloud).

[cisco-sbg-mgiassa-ai]

@jdknight I'm not explicitly setting confluence_api_token. Maybe it's implicitly set, but that keyword is nowhere to be found in my config file.

[jdknight]

Intersting... hmm... by chance is the CONFLUENCE_API_TOKEN environment option set?

[cisco-sbg-mgiassa-ai]

@jdknight I was just about to test that (yes, it's set). I didn't realize these config.py variables also mapped to env vars.

[jdknight]

Fun corner case.

I see room for improvements here:

• Updating the report tool to detail when the environment or CLI options are used for an option (if possible).
• Check for "conflicting" options between fixed, env and CLI and prevent any cases like this (e.g. if a user sets an explicit PAT via configuration, it should not attempt to look for an API token).
• Provide an option to disable the use of environment options.

[cisco-sbg-mgiassa-ai]

Thanks for the (patient) help, by the way.

[jdknight]

Thanks for the (patient) help, by the way.

Any time. Thanks for the report. It's great to have user feedback to try to improve things for all.

[cisco-sbg-mgiassa-ai]

+1 for the above-noted features (as time permits).

[cisco-sbg-mgiassa-ai]

On a side note, it's worth noting I've used this tool at 3 companies so far, and it's been a godsend. Some ansible/J2 templating of the doc repo (and some Mermaid/PlantUML files), and we have an entire dynamically-generated wiki that can be replicated to HTML (GitHub Pages), PDF, and Confluence. Zero vendor lock-in, and the resulting docs look great (and can be auto-republished via a CI job to prevent drift/edits). The textbook definition of "documentation as code" 😄

[cisco-sbg-mgiassa-ai]

Working now. Thanks again!

edit: it was indeed due to the env var triggering both API and publish token to be set.