Adding documentation for the new auth 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,47 @@
+.. _reference_extensions_authorization_plugin:
+
+Authorization plugins
+---------------------
+
+Regarding authorization, we have two plugins: one focused on remote Conan servers 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 two optional parameters: ``user`` and
+``password``. The output should be a tuple of the username and password 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, password=None)``.
+
+Here we can see an example of a plugin implementation.
+
+.. code-block:: python
+
+    def auth_remote_plugin(remote, user=None, password=None):
+        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)``.
+
+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'}
+
+