Single Sign-On (SSO) and OAuth Environments

A percentage of extension users may be trying to operate with a Confluence instance which deploys some sort of single sign-on (SSO) or OAuth capability. How an instance is configured and the means to interact can vary per organization, even per instance. There are no definitive steps for configuring this extension to guarantee a graceful setup. That being said, there should be a means to allow interaction when using this extension. This guide may be useful for users configuring this extension for the first time in a corporate environment.

Confluence Authentication Token

Users be using either an API token (Confluence Cloud) or personal access token (PAT; Confluence Data Center) for authenticating with Confluence. This means that confluence_api_token (along with confluence_server_user) should be used in a Confluence Cloud setting, and confluence_publish_token should be used in a Confluence Data Center setting (e.g. corporate/self-hosted).

Initial Test

Once a token has been configured, it is recommended to perform a connection attempt. This is to help ensure a project configuration and extension is ready to perform interaction with a Confluence instance, as well as to perform a sanity check that additional SSO/OAuth configuration is required.

From the working directory of a project, perform a connection test:

$ python -m sphinxcontrib.confluencebuilder connection-test
Fetching configuration information...
...

Configuring for Identity or Authorization Instance

This extension uses Requests for HTTP requests. Options are available to help allow a user tailor requests. These options can be used to inject additional token/session information in a request required for a front-end of a Confluence instance.

The following options may help:

• confluence_publish_headers: Used to set HTTP headers for requests made to a Confluence instance.

• confluence_server_cookies: Used to provide cookie data for requests made to a Confluence instance.

• confluence_server_auth: Used to provide a custom Requests-capable authentication handler for requests made to a Confluence instance.

Which option and values to use will vary. It is recommended, if available, to refer to any documentation provided by the Confluence instance about what setup is used and what header/cookie data they expect. If no such information is available, it is recommended to either create a ticket with the service desk associated with the Confluence instance or talk with a system administrator for the Confluence instance.

Additional information

• To help debug the network traffic between this extension and a Confluence instance, the confluence_publish_debug option may be used.

• Refer to connection-issused issues reported by users.