From b8899084a736476b0f933c10caca78f2519c9c62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20L=C3=A9obal?= Date: Thu, 17 Aug 2023 12:29:07 +0200 Subject: [PATCH] docs: add a note arguing you should generate tokens (#336) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Olivier Léobal Co-authored-by: Sarah Diot-Girard --- .../using-substra/api_tokens_generation.rst | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/source/how-to/using-substra/api_tokens_generation.rst b/docs/source/how-to/using-substra/api_tokens_generation.rst index 3bd99d96..58236c30 100644 --- a/docs/source/how-to/using-substra/api_tokens_generation.rst +++ b/docs/source/how-to/using-substra/api_tokens_generation.rst @@ -3,7 +3,24 @@ How-to use new API tokens for login This short guide explains how to manage API tokens in the web application, and use them in the Substra SDK. -.. note:: +.. admonition:: Why generate API tokens? + + The Substra SDK provides a way to log in using username and password (see `substra.Client `_). + + It is safe, but should be used with caution: + + * It doesn't allow for a precise lifetime or separating concerns by creating one token per purpose. + + * It may surprise or limit you through its underlying automated session management. + + * It can encourage using cleartext passwords, which can end up shared in version control. + + For these reasons, it is possible for Substra node administrators (via `chart options `_) to disable "implicit login" and force users to generate tokens in the web app. + + Whatever the situation, you should use a mechanism to ensure credentials are kept out of view, for instance by reading secret files or environment variables at runtime (see :ref:`client configuration howto`). + + +.. warning:: API tokens are node-specific: if your script connects to multiple nodes, generate a token for each of them. Generating new API tokens