feat: add documentation to setup pilots with tokens

docs/source/AdministratorGuide/HowTo/index.rst

@@ -15,3 +15,4 @@ FIXME: These sections describes things
    multiVO
    pitExport
    dedicateddfc
+   pilotsWithTokens

docs/source/AdministratorGuide/HowTo/pilotsWithTokens.rst

@@ -0,0 +1,88 @@
+.. _pilots-with-tokens:
+
+=====================================
+Submitting pilots to CEs using tokens
+=====================================
+
+
+This guide outlines the process of setting up DIRAC to submit pilots using access tokens obtained via a ``client_credentials`` flow from a token provider.
+
+.. warning:: This is currently not multi-VO compatible. For a given CE, either all or none of the VOs using the CE have to use tokens.
+
+Setting up an ``IdProvider``
+----------------------------
+
+- Set up an OAuth2 client in the token provider and obtain a ``client_id`` and a ``client_secret``.
+
+    .. warning:: The client credentials obtained are confidential, store them in a secure place.
+       Any malicious user able to get access to them would be able to generate access tokens on your behalf.
+       To avoid any major issue, we recommend you to only grant essential privileges to the client (``compute`` scopes).
+
+- Add the client credentials in the ``dirac.cfg`` of the relevant server configuration such as:
+
+    .. code-block:: guess
+
+      Resources
+      {
+        IdProviders
+        {
+          <IdProvider name>
+          {
+            client_id = <client_id>
+            client_secret = <client_secret>
+          }
+        }
+      }
+
+- Then in your global configuration, add the following section to set up an ``IdProvider`` interface:
+
+    .. code-block:: guess
+
+      Resources
+      {
+        IdProviders
+        {
+          <IdProvider name>
+          {
+            issuer = <OIDC provider issuer URL>
+          }
+        }
+      }
+
+- Finally, connect the OIDC provider to a specific VO by adding the following option:
+
+  .. code-block:: guess
+
+    Registry
+    {
+      VO
+      {
+        <VO name>
+        {
+          IdProvider = <IdProvider name>
+        }
+      }
+    }
+
+.. note:: Get more details about the DIRAC configuration from the :ref:`Configuration <dirac-configuration>` section.
+
+Launching the ``TokenManagerHandler``
+-------------------------------------
+
+Run the following commands from a DIRAC client to install the ``Framework/TokenManager`` service:
+
+.. code-block:: console
+
+   $ dirac-proxy-init -g dirac_admin
+
+   $ dirac-admin-sysadmin-cli --host <dirac host>
+
+   > install service Framework TokenManager
+
+.. note:: ``Tornado`` and then ``TokenManager`` might need to be restarted.
+.. note:: Get more details about the system administrator interface from the :ref:`System Administrator Interface <system-admin-console>` section.
+
+Marking computing resources as token-ready
+------------------------------------------
+
+In the global configuration, add the ``Tag = Token`` option to concerned CEs, and then restart the ``Site Directors``.