Adding documentation for the new auth plugin (#3846)

* add atuh plugin docu

* Update reference/extensions/authorization_plugins.rst

Co-authored-by: Abril Rincón Blanco <git@rinconblanco.es>

* Update reference/extensions/authorization_plugins.rst

Co-authored-by: Abril Rincón Blanco <git@rinconblanco.es>

* Update reference/extensions/authorization_plugins.rst

Co-authored-by: Abril Rincón Blanco <git@rinconblanco.es>

* Update reference/extensions/authorization_plugins.rst

Co-authored-by: Abril Rincón Blanco <git@rinconblanco.es>

* Update reference/extensions/authorization_plugins.rst

Co-authored-by: Abril Rincón Blanco <git@rinconblanco.es>

* Update reference/extensions/authorization_plugins.rst

Co-authored-by: Abril Rincón Blanco <git@rinconblanco.es>

* Update reference/extensions/authorization_plugins.rst

Co-authored-by: Abril Rincón Blanco <git@rinconblanco.es>

* Update reference/extensions/authorization_plugins.rst

Co-authored-by: Abril Rincón Blanco <git@rinconblanco.es>

* remove password and add order credentials sources

* adding links to the auth plugin page

* add **kwargs, note for "sensible data" , change on credentials.rst

* experimental warning

---------

Co-authored-by: Abril Rincón Blanco <git@rinconblanco.es>

reference/config_files/credentials.rst

@@ -12,6 +12,7 @@ Conan can authenticate against its Conan remote servers with the following:
 - With the ``conan remote login`` command, authentication can be done with argument passing, or interactively.
 - With the environment variables ``CONAN_LOGIN_USERNAME`` for all remotes (``CONAN_LOGIN_USERNAME_{REMOTE}`` for an individual remote) and ``CONAN_PASSWORD`` (``CONAN_PASSWORD_{REMOTE}`` for an individual remote), Conan will not request interactively in the command line when necessary, but will take the values from the environment variables as if they were provided by the user.
 - With a ``credentials.json`` file put in the Conan cache.
+- With a custom :ref:`auth plugin <reference_extensions_authorization_plugin>`.
 
 This section describes the usage of ``credentials.json`` file.
 
@@ -64,3 +65,7 @@ For example it could do something like the following to get the credentials from
             }
         ]
     }
+
+.. seealso::
+
+    - :ref:`How to use your own secrets manager for Conan remotes logins <reference_extensions_authorization_plugin>`.

reference/config_files/remotes.rst

@@ -37,3 +37,4 @@ The fields for each remote are:
 
     - :ref:`How to manage SSL (TLS) certificates <reference_config_files_global_conf_ssl_certificates>`
     - :ref:`How to manage remotes.json through CLI: conan remotes <reference_commands_remote>`.
+    - :ref:`How to use your own secrets manager for Conan remotes logins <reference_extensions_authorization_plugin>`.

reference/config_files/source_credentials.rst

@@ -25,8 +25,12 @@ has the following format, in which every ``credentials`` entry should have a ``u
 URL that should match the recipe one. If the recipe URL starts with the given one in the credentials files,
 then the credentials will be injected. If the file provides multiple credentials for multiple URLs, they
 will be evaluated in order until the first match happens. If no match is found, no credentials will be injected.
+A custom :ref:`auth plugin <reference_extensions_authorization_plugin>` can also be used to retrieve credentials
+directly from your own secrets manager.
 
-It has to be noted that the ``source_credentials`` applies only to files downloaded with the ``tools.files`` ``download()`` and ``get()`` helpers, but it won't be used in other cases. To provide credentials for Conan repos, the ``credentials.json`` file should be used instead, see :ref:`reference_config_files_credentials`.
+It has to be noted that the ``source_credentials`` applies only to files downloaded with the ``tools.files``
+``download()`` and ``get()`` helpers, but it won't be used in other cases. To provide credentials for Conan repos,
+the ``credentials.json`` file should be used instead, see :ref:`reference_config_files_credentials`.
 
 .. code-block:: json
 
@@ -81,3 +85,7 @@ level:
     - Avoid using URLs that encode tokens or user/password authentication in the ``conanfile.py`` recipes. These URLs can easily leak into logs, and 
       can be more difficult to fix in case of credentials changes (this is also valid for Git repositories URLs and clones,
       better use other Git auth mechanisms like ssh-keys) 
+
+.. seealso::
+
+    - :ref:`How to use your own secrets manager for your source server logins <reference_extensions_authorization_plugin>`.

reference/extensions.rst

@@ -48,6 +48,7 @@ Contents:
    extensions/hooks
    extensions/binary_compatibility
    extensions/profile_plugin
+   extensions/authorization_plugins
    extensions/command_wrapper
    extensions/package_signing
 

reference/extensions/authorization_plugins.rst

@@ -0,0 +1,68 @@
+.. _reference_extensions_authorization_plugin:
+
+Authorization plugins
+=====================
+
+.. include:: ../../common/experimental_warning.inc
+
+Regarding authorization, we have two plugins: one focused on remote  :ref:`Conan servers <setting_up_conan_remotes>`
+authorization, ``auth_remote.py``, and another focused on authorization for source file servers, ``auth_source.py``.
+
+The idea behind these plugins is to create custom integrations with each user's secrets managers.
+
+Auth remote plugin
++++++++++++++++++++
+This first plugin is a Python script that receives a ``remote`` object and an optional parameter: ``user``. If the user
+is provided, the expected output is the credentials that use that username. The output should be a tuple of the
+username that we want to use for that remote, or ``None`` if no credentials are specified for that remote and we want
+Conan to follow the normal login flow.
+
+This plugin is located at the path ``<CONAN_HOME>/extensions/plugins/auth_remote.py`` and must be manually created with
+the name ``auth_remote.py``, containing a function named ``auth_remote_plugin(remote, user=None, **kwargs)``.
+
+The order for retrieving credentials is as follows:
+
+* First, an attempt is made to obtain the credentials from the ``auth_remote_plugin``.
+* If it doesn't exist or returns ``None``, the next step is to check ``credentials.json``.
+* After that, the environment variables are searched.
+* Finally, the credentials are obtained through an interactive prompt.
+
+Here we can see an example of a plugin implementation.
+
+.. code-block:: python
+
+    def auth_remote_plugin(remote, user=None, **kwargs):
+        if remote.url.startswith("https://artifactory.my-org/"):
+            return "admin", "password"
+
+
+Auth source plugin
++++++++++++++++++++
+This one is a Python script that receives an ``url`` as a parameter and outputs a dictionary with the credentials or
+access token. It can also return ``None`` to indicate that Conan should proceed with its normal login flow.
+
+This plugin is located at the path ``<CONAN_HOME>/extensions/plugins/auth_source.py`` and must be manually created with the name
+``auth_source.py``, containing a function named ``auth_source_plugin(url)``.
+
+The order for retrieving the credentials is as follows:
+
+* First, an attempt is made to obtain the credentials from the ``auth_source_plugin``.
+* If it doesn't exist or returns ``None``, an attempt is made to retrieve them from ``source_credentials.json``.
+
+Here we can see an example of a plugin implementation.
+
+.. code-block:: python
+
+    def auth_source_plugin(url):
+        if url.startswith("https://my-sources-user-password.my-org/"):
+            return {'user': 'my-user', 'password': 'my-password'}
+        elif url.startswith("https://my-private-token-sources.my-org/"):
+            return {'token': 'my-secure-token'}
+
+
+.. note::
+
+    These plugins can be shared and installed using ``conan config install`` or ``conan config install-pkg``
+
+    **Important:** Ensure that your plugins and configurations do **not** contain hardcoded secrets or sensitive data.
+    Instead, passwords should be retrieved using your implementation with a secret manager.