Update the CyberArk Provider docs (#3261)

* updates conjur provider doc

Signed-off-by: Ben Skelker <ben.skelker@cyberark.com>

* edits

Signed-off-by: Ben Skelker <ben.skelker@cyberark.com>

* more edits

Signed-off-by: Ben Skelker <ben.skelker@cyberark.com>

* more edits3

Signed-off-by: Ben Skelker <ben.skelker@cyberark.com>

* even more edits

Signed-off-by: Ben Skelker <ben.skelker@cyberark.com>

* Update docs/provider/conjur.md

Signed-off-by: Ben Skelker <54019610+benskelker@users.noreply.github.com>
Signed-off-by: Ben Skelker <ben.skelker@cyberark.com>

* and more edits

Signed-off-by: Ben Skelker <ben.skelker@cyberark.com>

---------

Signed-off-by: Ben Skelker <ben.skelker@cyberark.com>
Signed-off-by: Ben Skelker <54019610+benskelker@users.noreply.github.com>
Co-authored-by: Ben Skelker <ben.skelker@cyberark.com>

docs/provider/conjur.md

@@ -1,42 +1,47 @@
 ## Conjur Provider
 
-The following sections outline what is needed to get your external-secrets Conjur provider setup.
+This section describes how to set up the Conjur provider for External Secrets Operator (ESO). For a working example, see the [Accelerator-K8s-External-Secrets repo](https://github.com/conjurdemos/Accelerator-K8s-External-Secrets).
 
-### Pre-requirements
+### Prerequisites
 
-This section contains the list of the pre-requirements before installing the Conjur Provider.
+Before installing the Conjur provider, you need:
 
-*   Running Conjur Server
-    -   These items will be needed in order to configure the secret-store
-        +   Conjur endpoint - include the scheme but no trailing '/', ex: https://myapi.example.com
-        +   Conjur authentication info (hostid, apikey, jwt service id, etc)
-        +   Conjur must be configured to support your authentication method (`apikey` is supported by default, `jwt` requires additional configuration)
-        +   Certificate for Conjur server is OPTIONAL -- But, **when using a self-signed cert when setting up your Conjur server, it is strongly recommended to populate "caBundle" with self-signed cert in the secret-store definition**
-*   Kubernetes cluster
-    -   External Secrets Operator is installed
+*   A running Conjur Server, with:
+    *   An accessible Conjur endpoint (for example: `https://myapi.example.com`).
+    *   Your configured Conjur authentication info (such as `hostid`, `apikey`, or JWT service ID). For more information on configuring Conjur, see [Policy statement reference](https://docs.cyberark.com/conjur-open-source/Latest/en/Content/Operations/Policy/policy-statement-ref.htm).
+    *   Support for your authentication method (`apikey` is supported by default, `jwt` requires additional configuration).
+    *   **Optional**: Conjur server certificate (see [below](#conjur-server-certificate)).
+*   A Kubernetes cluster with ESO installed.
 
-### Certificate for Conjur server
+### Conjur server certificate
 
-When using a self-signed cert when setting up your Conjur server, it is strongly recommended to populate "caBundle" with self-signed cert in the secret-store definition. The certificate CA must be referenced on the secret-store definition using either a `caBundle` or `caProvider` as below:
+If you set up your Conjur server with a self-signed certificate, we recommend that you populate the `caBundle` field with the Conjur self-signed certificate in the secret-store definition. The certificate CA must be referenced in the secret-store definition using either `caBundle` or `caProvider`:
 
 ```yaml
 {% include 'conjur-ca-bundle.yaml' %}
 ```
 
-### External Secret Store Definition with ApiKey Authentication
-This method uses a combination of the Conjur `hostid` and `apikey` to authenticate to Conjur. This method is the simplest to setup and use as your Conjur instance requires no special setup.
+### External secret store with apiKey authentication
 
-#### Create External Secret Store Definition
-Recommend to save as filename: `conjur-secret-store.yaml`
+This method uses a Conjur `hostid` and `apikey` to authenticate with Conjur. It is the simplest method to set up and use because your Conjur instance requires no additional configuration.
+
+#### Step 1: Create an external secret store
+
+!!! Tip
+    Save as the file as: `conjur-secret-store.yaml`
 
 ```yaml
 {% include 'conjur-secret-store-apikey.yaml' %}
 ```
 
-#### Create Kubernetes Secrets
-In order for the ESO **Conjur** provider to connect to the Conjur server using the `apikey` creds, these creds should be stored as k8s secrets.  Please refer to <https://kubernetes.io/docs/concepts/configuration/secret/#creating-a-secret> for various methods to create secrets.  Here is one way to do it using `kubectl`
+#### Step 2: Create Kubernetes secrets
+
+To connect to the Conjur server, the **ESO Conjur provider** needs to retrieve the `apikey` credentials from K8s secrets.
 
-***NOTE***: "conjur-creds" is the "name" used in "userRef" and "apikeyRef" in the conjur-secret-store definition
+!!! Note
+    For more information about how to create K8s secrets, see [Creating a secret](https://kubernetes.io/docs/concepts/configuration/secret/#creating-a-secret).
+
+Here is an example of how to create K8s secrets using the `kubectl` command:
 
 ```shell
 # This is all one line
@@ -46,57 +51,65 @@ kubectl -n external-secrets create secret generic conjur-creds --from-literal=ho
 # kubectl -n external-secrets create secret generic conjur-creds --from-literal=hostid=host/data/app1/host001 --from-literal=apikey=321blahblah
 ```
 
-### External Secret Store with JWT Authentication
-This method uses JWT tokens to authenticate with Conjur. The following methods for retrieving the JWT token for authentication are supported:
+!!! Note
+    `conjur-creds` is the `name` defined in the `userRef` and `apikeyRef` fields of the `conjur-secret-store.yml` file.
+
+### External secret store with JWT authentication
+
+This method uses JWT tokens to authenticate with Conjur. You can use the following methods to retrieve a JWT token for authentication:
 
--  JWT token from a referenced Kubernetes Service Account
+-  JWT token from a referenced Kubernetes service account
 -  JWT token stored in a Kubernetes secret
 
-#### Create External Secret Store Definition
+#### Step 1: Define an external secret store
 
-When using JWT authentication the following must be specified in the `SecretStore`:
+When you use JWT authentication, the following must be specified in the `SecretStore`:
 
 - `account` -  The name of the Conjur account
-- `serviceId` - The ID of the JWT Authenticator `WebService` configured in Conjur that will be used to authenticate the JWT token
+- `serviceId` - The ID of the JWT Authenticator `WebService` configured in Conjur that is used to authenticate the JWT token
 
-You can then choose to either retrieve the JWT token using a Service Account reference or from a Kubernetes Secret.
+You can retrieve the JWT token from either a referenced service account or a Kubernetes secret.
 
-To use a JWT token from a referenced Kubernetes Service Account, the following secret store definition can be used:
+For example, to retrieve a JWT token from a referenced Kubernetes service account, the following secret store definition can be used:
 
 ```yaml
 {% include 'conjur-secret-store-jwt-service-account-ref.yaml' %}
 ```
 
-This is only supported in Kubernetes 1.22 and above as it uses the [TokenRequest API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) to get the JWT token from the referenced service account. Audiences can be set as required by the [Conjur JWT authenticator](https://docs.conjur.org/Latest/en/Content/Integrations/k8s-ocp/k8s-jwt-authn.htm).
+!!! Important
+    This method is only supported in Kubernetes 1.22 and above as it uses the [TokenRequest API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) to get the JWT token from the referenced service account. Audiences can be defined in the [Conjur JWT authenticator](https://docs.conjur.org/Latest/en/Content/Integrations/k8s-ocp/k8s-jwt-authn.htm).
 
-Alternatively, a secret containing a valid JWT token can be referenced as follows:
+Alternatively, here is an example where a secret containing a valid JWT token is referenced:
 
 ```yaml
 {% include 'conjur-secret-store-jwt-secret-ref.yaml' %}
 ```
 
-This secret must contain a JWT token that identifies your Conjur host. The secret must contain a JWT token consumable by a configured Conjur JWT authenticator and must satisfy all [Conjur JWT guidelines](https://docs.conjur.org/Latest/en/Content/Operations/Services/cjr-authn-jwt-guidelines.htm#Best). This can be a JWT created by an external JWT issuer or the Kubernetes api server itself. Such a with Kubernetes Service Account token can be created using the below command:
+The JWT token must identify your Conjur host, be compatible with your configured Conjur JWT authenticator, and meet all the [Conjur JWT guidelines](https://docs.conjur.org/Latest/en/Content/Operations/Services/cjr-authn-jwt-guidelines.htm#Best).
+
+You can use an external JWT issuer or the Kubernetes API server to create the token. For example, a Kubernetes service account token can be created with this command:
 
 ```shell
 kubectl create token my-service-account --audience='https://conjur.company.com' --duration=3600s
 ```
 
-Save the `SecretStore` definition as filename `conjur-secret-store.yaml` as referenced in later steps.
-
-### Create External Secret Definition
+Save the secret store file as `conjur-secret-store.yaml` (the filename used in subsequent steps).
 
-Important note: **Creds must live in the same namespace as a SecretStore  - the secret store may only reference secrets from the same namespace.**  When using a ClusterSecretStore this limitation is lifted and the creds can live in any namespace.
+#### Step 2: Define an external secret
 
-Recommend to save as filename: `conjur-external-secret.yaml`
+Save the external secret file as: `conjur-external-secret.yaml`
 
 ```yaml
 {% include 'conjur-external-secret.yaml' %}
 ```
 
-### Create the External Secrets Store
+!!!Important
+    Unless you are using a [ClusterSecretStore](../api/clustersecretstore.md), credentials must reside in the same namespace as the SecretStore.
+
+#### Step 3: Create the external secrets store
 
 ```shell
-# WARNING: this will create the store configuration in the "external-secrets" namespace, adjust this to your own situation
+# WARNING: creates the store in the "external-secrets" namespace, update the value as needed
 #
 kubectl apply -n external-secrets -f conjur-secret-store.yaml
 
@@ -106,10 +119,10 @@ kubectl apply -n external-secrets -f conjur-secret-store.yaml
 # kubectl delete secretstore -n external-secrets conjur
 ```
 
-### Create the External Secret
+#### Step 4: Create the external secret
 
 ```shell
-# WARNING: this will create the external-secret configuration in the "external-secrets" namespace, adjust this to your own situation
+# WARNING: creates the external-secret in the "external-secrets" namespace, update the value as needed
 #
 kubectl apply -n external-secrets -f conjur-external-secret.yaml
 
@@ -119,10 +132,10 @@ kubectl apply -n external-secrets -f conjur-external-secret.yaml
 # kubectl delete externalsecret -n external-secrets conjur
 ```
 
-### Getting the K8S Secret
+#### Step 5: Get the K8s secret
 
-* Login to your Conjur server and verify that your secret exists
-* Review the value of your Kubernetes secret to see that it contains the same value from Conjur
+* Log in to your Conjur server and verify that your secret exists
+* Review the value of your Kubernetes secret to verify that it contains the same value as the Conjur server
 
 ```shell
 # WARNING: this command will reveal the stored secret in plain text
@@ -131,7 +144,13 @@ kubectl apply -n external-secrets -f conjur-external-secret.yaml
 kubectl get secret -n external-secrets conjur -o jsonpath="{.data.secret00}"  | base64 --decode && echo
 ```
 
-### Support
+### See also
+
+* [Accelerator-K8s-External-Secrets repo](https://github.com/conjurdemos/Accelerator-K8s-External-Secrets)
+* [Configure Conjur JWT authentication](https://docs.cyberark.com/conjur-open-source/Latest/en/Content/Operations/Services/cjr-authn-jwt-guidelines.htm)
+
+
+### License
 
 Copyright (c) 2023 CyberArk Software Ltd. All rights reserved.
 

docs/snippets/conjur-ca-bundle.yaml

@@ -9,12 +9,13 @@ spec:
       caBundle: "<base64 encoded cabundle>"
 
       # [OPTIONAL] caProvider:
-      # Instead of caBundle you can also specify a caProvider
-      # this will retrieve the cert from a Secret or ConfigMap
+      # Instead of caBundle you can also specify a caProvider,
+      # which retrieves the cert from a Secret or ConfigMap
       caProvider:
         type: "Secret" # Can be Secret or ConfigMap
         name: "<name of secret or configmap>"
         key: "<key inside secret or configmap>"
-        # namespace is mandatory for ClusterSecretStore and not relevant for SecretStore
+        # namespace is required for ClusterSecretStore
+        # but not relevant for SecretStore
         namespace: "my-cert-secret-namespace"
   ....

docs/snippets/conjur-secret-store-jwt-secret-ref.yaml

@@ -13,7 +13,9 @@ spec:
         jwt:
           # conjur account
           account: conjur
-          serviceID: my-jwt-auth-service # The authn-jwt service ID
-          secretRef: # Secret containing a valid JWT token
+          # The authn-jwt service ID
+          serviceID: my-jwt-auth-service
+          # Secret containing a valid JWT token
+          secretRef:
             name: my-jwt-secret
             key: token

docs/snippets/conjur-secret-store-jwt-service-account-ref.yaml

@@ -13,9 +13,12 @@ spec:
         jwt:
           # conjur account
           account: conjur
-          serviceID: my-jwt-auth-service # The authn-jwt service ID
-          serviceAccountRef: # Service account to retrieve JWT token for
+          # The authn-jwt service ID
+          serviceID: my-jwt-auth-service
+          # Service account to retrieve JWT token for
+          serviceAccountRef:
             name: my-service-account
-            audiences:  # [OPTIONAL] audiences to include in JWT token
+            # [OPTIONAL] audiences to include in JWT token
+            audiences:
               - https://conjur.company.com