From b4ef406836bf66aa551fa5d7bb7863f8a13f2275 Mon Sep 17 00:00:00 2001
From: Jarek Potiuk <jarek@potiuk.com>
Date: Sun, 28 Nov 2021 11:30:21 +0100
Subject: [PATCH 1/2] Add a short chapter focusing on adapting secret format
 for connections

As a result of discussion in #19857, I propose to add this short
chapter to respond to anticipated need of organisations to keep the
connections in format that is not Airflow-exclusive. I think it would
be good to explicitly state what is the Airflow approach in this case
(i.e. either using existing capabilities of secret backends when
they are there  - for example in AWS - or rolling your own backend,
possibly by extending the community provided ones if the flexibility
is not implemented by the community provided backend.
---
 .../security/secrets/secrets-backend/index.rst   | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/docs/apache-airflow/security/secrets/secrets-backend/index.rst b/docs/apache-airflow/security/secrets/secrets-backend/index.rst
index befa84bbce24d..7e8a20879928a 100644
--- a/docs/apache-airflow/security/secrets/secrets-backend/index.rst
+++ b/docs/apache-airflow/security/secrets/secrets-backend/index.rst
@@ -111,3 +111,19 @@ See :ref:`Configuration <secrets_backend_configuration>` for more details, and :
 
     If you are rolling your own secrets backend, you don't strictly need to use airflow's URI format. But
     doing so makes it easier to switch between environment variables, the metastore, and your secrets backend.
+
+Adapt to non-Airflow compatible secret formats for connections
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The default implementation of Secret backend requires to use Airflow-specific format of storing
+secrets for connections. Currently most community provided implementations require the connections to
+be stored as URIs (with the possibility of adding more friendly formats in the future)
+:doc:`apache-airflow-providers:core-extensions/secrets-backends`. However in some cases it might be
+better solution for your organization to keep the credentials (passwords/tokens etc) in other formats -
+for example when you want the same credentials to be used across multiple clients or when you want to
+use built-in mechanism of rotating the credentials that do not work well with the Airflow-specific format.
+Some of the secret backends provided by the community (for example
+:py:class:`~airflow.providers.amazon.aws.secrets.systems_manager.SystemsManagerParameterStoreBackend` have
+mechanism where you can configure the retrieval in a flexible way, but others might not provide that much of
+flexibility. In this case you should simply roll your own secret backend as described in the previous chapter,
+possibly extending existing secret backend and adapt it to the scheme used by your organization.

From f6bedc1c612f7100187931967b0e842e9e37c752 Mon Sep 17 00:00:00 2001
From: Jarek Potiuk <potiuk@apache.org>
Date: Mon, 29 Nov 2021 19:46:20 +0100
Subject: [PATCH 2/2] Update
 docs/apache-airflow/security/secrets/secrets-backend/index.rst

Co-authored-by: Daniel Standish <15932138+dstandish@users.noreply.github.com>
---
 .../security/secrets/secrets-backend/index.rst      | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/docs/apache-airflow/security/secrets/secrets-backend/index.rst b/docs/apache-airflow/security/secrets/secrets-backend/index.rst
index 7e8a20879928a..7fe2cf779b8cc 100644
--- a/docs/apache-airflow/security/secrets/secrets-backend/index.rst
+++ b/docs/apache-airflow/security/secrets/secrets-backend/index.rst
@@ -115,15 +115,12 @@ See :ref:`Configuration <secrets_backend_configuration>` for more details, and :
 Adapt to non-Airflow compatible secret formats for connections
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The default implementation of Secret backend requires to use Airflow-specific format of storing
+The default implementation of Secret backend requires use of an Airflow-specific format of storing
 secrets for connections. Currently most community provided implementations require the connections to
 be stored as URIs (with the possibility of adding more friendly formats in the future)
-:doc:`apache-airflow-providers:core-extensions/secrets-backends`. However in some cases it might be
-better solution for your organization to keep the credentials (passwords/tokens etc) in other formats -
-for example when you want the same credentials to be used across multiple clients or when you want to
+:doc:`apache-airflow-providers:core-extensions/secrets-backends`. However some organizations may prefer
+to keep the credentials (passwords/tokens etc) in other formats --
+for example when you want the same credentials to be used across multiple clients, or when you want to
 use built-in mechanism of rotating the credentials that do not work well with the Airflow-specific format.
-Some of the secret backends provided by the community (for example
-:py:class:`~airflow.providers.amazon.aws.secrets.systems_manager.SystemsManagerParameterStoreBackend` have
-mechanism where you can configure the retrieval in a flexible way, but others might not provide that much of
-flexibility. In this case you should simply roll your own secret backend as described in the previous chapter,
+In this case you will need to roll your own secret backend as described in the previous chapter,
 possibly extending existing secret backend and adapt it to the scheme used by your organization.
