doc: adding guide on sso/oauth usage

Signed-off-by: James Knight <[email protected]>

Author: jdknight

doc/configuration.rst

@@ -1496,6 +1496,8 @@ Advanced publishing configuration
 
     See also :lref:`confluence_publish_denylist`.
 
+.. _confluence_publish_debug:
+
 .. confval:: confluence_publish_debug
 
     .. versionadded:: 1.8
@@ -1623,6 +1625,8 @@ Advanced publishing configuration
 
         confluence_publish_force = True
 
+.. _confluence_publish_headers:
+
 .. confval:: confluence_publish_headers
 
     .. versionadded:: 1.5
@@ -1759,6 +1763,8 @@ Advanced publishing configuration
 
         confluence_request_session_override = my_request_session_override
 
+.. _confluence_server_auth:
+
 .. confval:: confluence_server_auth
 
     An authentication handler which can be directly provided to a REST API
@@ -1787,6 +1793,8 @@ Advanced publishing configuration
             resource_owner_key=resource_owner_key,
             resource_owner_secret=resource_owner_secret)
 
+.. _confluence_server_cookies:
+
 .. confval:: confluence_server_cookies
 
     .. versionadded:: 1.2

doc/guide-sso.rst

@@ -0,0 +1,74 @@
+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 :lref:`confluence_api_token` (along with
+:lref:`confluence_server_user`) should be used in a Confluence Cloud
+setting, and :lref:`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
+:ref:`connection test <confluence_connection_troubleshooting>`:
+
+.. code-block:: shell-session
+
+    $ 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:
+
+- :lref:`confluence_publish_headers`: Used to set HTTP headers for
+  requests made to a Confluence instance.
+- :lref:`confluence_server_cookies`: Used to provide cookie data for
+  requests made to a Confluence instance.
+- :lref:`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 :lref:`confluence_publish_debug` option may be used.
+- Refer to `connection-issused issues`_ reported by users.
+
+.. references ------------------------------------------------------------------
+
+.. _Requests: https://requests.readthedocs.io/
+.. _connection-issused issues: https://github.com/sphinx-contrib/confluencebuilder/issues?q=label%3Aconnection-issues

doc/guides.rst

@@ -13,3 +13,4 @@ the Confluence Builder extension in a Sphinx-enabled environment.
     guide-math
     guide-strike
     guide-ci
+    guide-sso

doc/tips.rst

@@ -76,6 +76,8 @@ By default, this extension does not define any timeouts for a publish event. It
 is recommended to provide a timeout value based on the environment being used
 (see :lref:`confluence_timeout`).
 
+.. _confluence_connection_troubleshooting:
+
 Connection troubleshooting
 --------------------------