doc(dev,auth): add initial feature flags documentation to the guides I…

…QSS#9229 IQSS#9223

doc/sphinx-guides/source/developers/configuration.rst

@@ -109,3 +109,17 @@ always like ``dataverse.<scope/....>.newname...=old.property.name``. Note this d
 aliases.
 
 Details can be found in ``edu.harvard.iq.dataverse.settings.source.AliasConfigSource``
+
+Adding a Feature Flag
+^^^^^^^^^^^^^^^^^^^^^
+
+Some parts of our codebase might be opt-in only. Experimental or optional features can be switched on using our
+usual configuration mechanism, a JVM setting.
+
+Feature flags are implemented in the enumeration ``edu.harvard.iq.dataverse.settings.FeatureFlags``, which allows for
+convenient usage of it anywhere in the codebase. When adding a flag, please add a setting in ``JvmSettings`` (see above,
+also mind to use the appropriate scope ``dataverse.feature``), think of a default status, add some Javadocs about the
+flagged feature and add a ``@since`` tag to make it easier to identify when a flag has been introduced.
+
+We want to maintain a list of all :ref:`feature flags <feature-flags>` in the :ref:`configuration guide <feature-flags>`,
+please add yours to the list.

doc/sphinx-guides/source/installation/config.rst

@@ -1769,6 +1769,34 @@ production context! Rely on password alias, secrets directory or cloud based sou
 
 
 
+.. _feature-flags:
+
+Feature Flags
+-------------
+
+Certain features might be deactivated because they are experimental and/or opt-in. If you want to enable these, please
+find all known feature flags below. Any of these flags can be activated using a boolean value
+(case-insensitive, one of "true", "1", "YES", "Y", "ON") for the setting.
+
+.. list-table::
+    :widths: 35 50 15
+    :header-rows: 1
+    :align: left
+
+    * - Flag Name
+      - Description
+      - Default status
+    * - ``dataverse.feature.api-oidc-access``
+      - When using an :doc:`OIDC authentication provider <oidc>`, also enable using access tokens from it for API
+        authentication. Useful to integrate services or SPAs with the API when using cross-service logins.
+        Not usable for users from other authentication providers!
+      - Disabled
+
+**Note:** Can be set via any `supported MicroProfile Config API source`_, e.g. the environment variable
+``DATAVERSE_FEATURE_API_OIDC_ACCESS``.
+
+
+
 .. _:ApplicationServerSettings:
 
 Application Server Settings

doc/sphinx-guides/source/installation/oidc.rst

@@ -87,3 +87,9 @@ configuration option. For details, see :doc:`config`.
    In contrast to our :doc:`oauth2`, you can use multiple providers by creating distinct configurations enabled by
    the same technology and without modifying the Dataverse Software code base (standards for the win!).
 
+Limitations
+-----------
+
+Before Dataverse release 5.13, there was no option to use an Open ID Connect authentication provider with
+the "Authentication Code Flow" to access the API. As of this version, there is builtin experimental support for this.
+Please see the corresponding :ref:`feature flag <feature-flags>` to enable it.