docs: update configuration doc with otp

CS-SI · Jul 13, 2023 · 9ce8870 · 9ce8870
1 parent 9d22ef9
commit 9ce8870
Show file tree

Hide file tree

Showing 4 changed files with 104 additions and 2,088 deletions.
diff --git a/docs/cli_user_guide.rst b/docs/cli_user_guide.rst
@@ -112,6 +112,21 @@ string search sent to the provider. For instance, if you want to add foo=1 and b
 
         eodag download --conf my_conf.yml --search-results my_search.geojson
 
+* To download a product on a provider that needs a `One Time Password <https://eodag.readthedocs.io/en/stable/notebooks/api_user_guide/3_configuration.html#Authenticate-using-an-OTP-/-One-Time-Password-(Two-Factor-authentication)>`_,
+  e.g. ``creodias``, first search on this provider (increase the provider priotity to make eodag search on it):
+
+.. code-block:: console
+
+        EODAG__CREODIAS__PRIORITY=2 eodag search -b 1 43 2 44 -s 2018-01-01 -e 2018-01-31 -p S2_MSI_L1C --items 1
+
+Then download using the OTP (``creodias`` needs it as ``totp`` parameter):
+
+.. code-block:: console
+
+        EODAG__CREODIAS__AUTH__CREDENTIALS__TOTP=PLEASE_CHANGE_ME eodag download --search-results search_results.geojson
+
+If needed, check in the documentation how to `use environment variables to configure EODAG <https://eodag.readthedocs.io/en/stable/getting_started_guide/configure.html#environment-variable-configuration>`_.
+
 * To list all available product types and supported providers:
 
 .. code-block:: console

diff --git a/docs/getting_started_guide/register.rst b/docs/getting_started_guide/register.rst
@@ -15,7 +15,12 @@ to each provider supported by ``eodag``:
 
 * ``peps``: create an account `here <https://peps.cnes.fr/rocket/#/register>`__, then use your email as `username` in eodag credentials.
 
-* ``creodias``: create an account `here <https://portal.creodias.eu/register.php>`__
+* ``creodias``: create an account `here <https://portal.creodias.eu/register.php>`__, then use your `username`, `password` in eodag credentials. You will also
+  need `totp` in credentials, a temporary 6-digits OTP (One Time Password, see
+  `Creodias documentation <https://creodias.docs.cloudferro.com/en/latest/gettingstarted/Two-Factor-Authentication-for-Creodias-Site.html>`__)
+  to be able to authenticate and download. Check
+  `Authenticate using an OTP <https://eodag.readthedocs.io/en/stable/notebooks/api_user_guide/3_configuration.html#Authenticate-using-an-OTP-/-One-Time-Password-(Two-Factor-authentication)>`__
+  to see how to proceed.
 
 * ``onda``: create an account `here: <https://www.onda-dias.eu/cms/>`__
 

diff --git a/docs/notebooks/api_user_guide/3_configuration.ipynb b/docs/notebooks/api_user_guide/3_configuration.ipynb
@@ -198,15 +198,15 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2023-04-14 14:49:24,033 eodag.config                     [INFO    ] (config           ) Loading user configuration from: /home/sylvain/.config/eodag/eodag.yml\n",
-      "2023-04-14 14:49:24,237 eodag.core                       [DEBUG   ] (core             ) Opening product types index in /home/sylvain/.config/eodag/.index\n",
-      "2023-04-14 14:49:24,245 eodag.core                       [INFO    ] (core             ) Locations configuration loaded from /home/sylvain/.config/eodag/locations.yml\n"
+      "2023-07-13 16:37:48,667 eodag.config                     [INFO    ] (config           ) Loading user configuration from: /home/sylvain/.config/eodag/eodag.yml\n",
+      "2023-07-13 16:37:48,773 eodag.core                       [DEBUG   ] (core             ) Opening product types index in /home/sylvain/.config/eodag/.index\n",
+      "2023-07-13 16:37:48,776 eodag.core                       [INFO    ] (core             ) Locations configuration loaded from /home/sylvain/.config/eodag/locations.yml\n"
      ]
     },
     {
      "data": {
       "text/plain": [
-       "<eodag.api.core.EODataAccessGateway at 0x7f37e28b19d0>"
+       "<eodag.api.core.EODataAccessGateway at 0x7f20188cfdc0>"
       ]
      },
      "execution_count": 7,
@@ -217,6 +217,83 @@
    "source": [
     "EODataAccessGateway()"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Authenticate using an OTP / One Time Password (Two-Factor authentication)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`creodias` needs a temporary 6-digits code to authenticate in addition of the `username` and `password`. Check [Creodias documentation](https://creodias.docs.cloudferro.com/en/latest/gettingstarted/Two-Factor-Authentication-for-Creodias-Site.html) to see how to get this code once you are registered. This OTP code will only be valid for a few seconds, so you will better use it dynamically in your code instead of storing it statically in your user configuration file."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Set the OTP by updating `creodias` credentials for `totp`, using one the two following configuration update commands:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dag.providers_config[\"creodias\"].auth.credentials[\"totp\"] = \"PLEASE_CHANGE_ME\"\n",
+    "\n",
+    "# OR\n",
+    "\n",
+    "dag.update_providers_config(\n",
+    "    \"\"\"\n",
+    "    creodias:\n",
+    "        auth:\n",
+    "            credentials:\n",
+    "                totp: PLEASE_CHANGE_ME\n",
+    "    \"\"\"\n",
+    ")"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then quickly authenticate as this OTP has a few seconds only lifetime. First authentication will retrieve a token that will be stored and used if further authentication tries fail:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<eodag.plugins.authentication.openid_connect.CodeAuthorizedAuth at 0x7f2018682880>"
+      ]
+     },
+     "execution_count": 10,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "dag._plugins_manager.get_auth_plugin(\"creodias\").authenticate()"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Please note that authentication mechanism is already included in [download methods](https://eodag.readthedocs.io/en/stable/notebooks/api_user_guide/7_download.html), so you could also directly execute a download to retrieve the token while the OTP is still valid."
+   ]
   }
  ],
  "metadata": {
@@ -237,9 +314,6 @@
    "pygments_lexer": "ipython3",
    "version": "3.8.10"
   },
-  "nbsphinx": {
-   "execute": "always"
-  },
   "widgets": {
    "application/vnd.jupyter.widget-state+json": {
     "state": {},