From 09b741de62d955a0b491328e4e28ee0162b283c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20GUICHARD?= Date: Mon, 14 Mar 2022 15:11:19 +0100 Subject: [PATCH] docs: add doc for credentials feature (#60) --- docs/cli_user_guide.rst | 33 ++++++++++++++++++++++++ docs/getting_started_guide/configure.rst | 25 +++++++++++------- docs/getting_started_guide/register.rst | 4 +-- docs/stac_rest.rst | 5 ++-- 4 files changed, 54 insertions(+), 13 deletions(-) diff --git a/docs/cli_user_guide.rst b/docs/cli_user_guide.rst index 40369e6df..1838e459e 100644 --- a/docs/cli_user_guide.rst +++ b/docs/cli_user_guide.rst @@ -22,6 +22,7 @@ Then you can start playing with it: --help Show this message and exit. Commands: + credentials This command can be used to create, read, update, or... deploy-wsgi-app Configure the settings of the HTTP web app (the providers... download Download a list of products from a serialized search... @@ -122,3 +123,35 @@ to the provider. For instance, if you want to add foo=1 and bar=2 to the previou .. code-block:: console eodag list -p sobloo + +* To check if credentials were stored for a provider: + +.. code-block:: console + + eodag credentials sobloo --exists + +* To list the credentials fields of a provider: + +.. code-block:: console + + eodag credentials sobloo --list + +* To create credentials for a provider: + +.. code-block:: console + + eodag credentials sobloo # interactive + # OR + eodag credentials sobloo --set apikey=<..> + +* To read the credentials stored for a provider: + +.. code-block:: console + + eodag credentials sobloo --read + +* To delete the credentials of a provider: + +.. code-block:: console + + eodag credentials sobloo --delete diff --git a/docs/getting_started_guide/configure.rst b/docs/getting_started_guide/configure.rst index d99cc4012..e5e439a65 100644 --- a/docs/getting_started_guide/configure.rst +++ b/docs/getting_started_guide/configure.rst @@ -28,7 +28,7 @@ in a local directory (``~/.config/eodag/eodag.yml`` on Linux). This YAML file contains a template that shows how to complete the configuration of one or more providers. It allows to either **override** an existing setting or **add** a missing -one (e.g. credentials). *PEPS*'s configuration template is shown below: +one. *PEPS*'s configuration template is shown below: .. code-block:: yaml @@ -40,10 +40,6 @@ one (e.g. credentials). *PEPS*'s configuration template is shown below: outputs_prefix: # where to store downloaded products. dl_url_params: # additional parameters to pass over to the download url as an url parameter delete_archive: # whether to delete the downloaded archives (true or false, Default: true). - auth: - credentials: - username: - password: .. raw:: html @@ -173,6 +169,12 @@ Credentials come into play at different stages for a provider. Most do not require any credentials for a search to be made (a few require an API key). Most, if not all of them, require credentials to be set to download products. +For security purposes, credentials be can saved the outside of ``eodag``'s configuration file. +The command ``credentials`` can be used to manage these credentials, because they cannot be edited +by hand as they are encrypted. + +Check the `CLI User Guide <../cli_user_guide.rst>`_ + .. note:: ``eodag`` tries to fail as early as possible if some credentials are missing to authenticate @@ -194,9 +196,6 @@ Edit your configuration file ``$HOME/.config/eodag/eodag.yml`` with the followin download: extract: False outputs_prefix: /home/user/eodagworkspace/ - auth: - credentials: - apikey: my_secret_sobloo_api_key It updates and completes the settings of the provider `sobloo` by: @@ -207,7 +206,15 @@ It updates and completes the settings of the provider `sobloo` by: * The products should be downloaded to the folder ``/home/user/eodagworkspace/``. -* An API key obtained from `sobloo` is saved there, it will be used to authenticate to the provider. +Then, create the credentials: + +.. code-block:: console + + eodag credentials sobloo # interactive mode + # OR + eodag credentials sobloo -y --set apikey=my_secret_sobloo_api_key + +The API key obtained from `sobloo` is used there, it will be used to authenticate to the provider. This file can be used to download products with the API: diff --git a/docs/getting_started_guide/register.rst b/docs/getting_started_guide/register.rst index 047fbbd45..5bb9a9c1f 100644 --- a/docs/getting_started_guide/register.rst +++ b/docs/getting_started_guide/register.rst @@ -38,7 +38,7 @@ to each provider supported by ``eodag``: * In access keys, click on create access key. - * Add these credentials to the user configuration file. + * Add these credentials to eodag. .. note:: @@ -54,7 +54,7 @@ to each provider supported by ``eodag``: * In access keys, click on create access key. - * Add these credentials to the user configuration file. + * Add these credentials to eodag. .. warning:: diff --git a/docs/stac_rest.rst b/docs/stac_rest.rst index f8b69fce7..a66be3c24 100644 --- a/docs/stac_rest.rst +++ b/docs/stac_rest.rst @@ -24,8 +24,9 @@ Below is the content of the help message of this command (`eodag serve-rest --he Start eodag HTTP server Options: - -f, --config PATH File path to the user configuration file with its - credentials, default is ~/.config/eodag/eodag.yml + -f, --config PATH File path to the user configuration file, default is + ~/.config/eodag/eodag.yml + -l, --locs PATH File path to the location shapefiles configuration file -d, --daemon run in daemon mode [default: False] -w, --world run flask using IPv4 0.0.0.0 (all network interfaces), otherwise bind to 127.0.0.1 (localhost). This maybe