HPCC-25660 Document LDAP Admin externalization

Signed-off-by: g-pan <[email protected]>
hpcc-systems · Mar 22, 2024 · e123707 · e123707
1 parent 1b38646
commit e123707
Show file tree

Hide file tree

Showing 2 changed files with 171 additions and 7 deletions.
diff --git a/docs/EN_US/ContainerizedHPCC/ContainerizedMods/CustomConfig.xml b/docs/EN_US/ContainerizedHPCC/ContainerizedMods/CustomConfig.xml
@@ -7,12 +7,11 @@
   <sect1 id="CustTechniques" role="nobrk">
     <title>Customization Techniques</title>
 
-    <para>In this section, we will walk through creating a custom
-    configuration YAML file and deploying an HPCC
-    Systems<superscript>®</superscript> platform using the default
-    configuration plus the customizations. Once you understand the concepts in
-    this chapter, you can refer to the next chapter for a reference to all
-    configuration value settings.</para>
+    <para>This section walks through creating a customized configuration YAML
+    file and deploying an HPCC Systems<superscript>®</superscript> platform
+    using the default configuration plus the customizations. Once you
+    understand the concepts in this chapter, you can refer to the next chapter
+    for a reference to all configuration value settings.</para>
 
     <para>There are several ways to customize a platform deployment. We
     recommend using methods that allow you to best take advantage of the
@@ -992,4 +991,169 @@ eclagent:
       </sect3>
     </sect2>
   </sect1>
+
+  <sect1 id="LDAPSecurity_forConatiners">
+    <title>LDAP Security for Containers</title>
+
+    <para>Containerized LDAP support for HPCC Systems is accomplished by
+    externalizing the LDAP Active Directory Security Manager administrators
+    account credentials using Kubernetes or Hashicorp Vault secrets. As a
+    prerequisite to use these externalized credentials, you should be familiar
+    with setting up Kubernetes and/or Hashicorp Vault secrets.</para>
+
+    <para>The HPCC Administrator does not have Active Directory administrator
+    rights. Instead, it must have administrator rights to all of the Base DNs
+    used by the HPCC Systems platform. The credentials for that HPCC Systems
+    administrators account therefore must be secured either using Kubernetes
+    secrets or the Hashicorp Vault. </para>
+
+    <sect2 id="Configuring_For_KubernetesSecrets">
+      <title>Securing Credentials in Kubernetes</title>
+
+      <para>To create a secret in Kubernetes for the HPCC Administrators user
+      account from a command line interface to Kubernetes, execute a command
+      similar to the following example. Note the secret name, is
+      "admincredssecretname" in this example. The HPCC Administrators user
+      account "username" and "password" key/values are required, and
+      additional properties are ignored.</para>
+
+      <programlisting lang="bash">kubectl create secret generic admincredssecretname --from-literal=username=hpcc_admin \
+  --from-literal=password=t0pS3cr3tP@ssw0rd
+</programlisting>
+
+      <para>This sets the values for the Administrator's username and password
+      in Kubernetes and sets them as secrets. At this point you can verify the
+      secret you just created by executing the following command on the
+      Kubernetes command line interface.</para>
+
+      <programlisting lang="bash">kubectl get secret admincredssecretname</programlisting>
+
+      <para>For more information about Kubernetes see the appropriate
+      Kubernetes documentation for your implementation.</para>
+
+      <sect3 id="Deploying_TheKubernetesSecret">
+        <title>Deploying the Kubernetes Secret</title>
+
+        <para>To deploy the Kubernetes secrets override the "secrets:" section
+        in HPCC-Platform/helm/hpcc/values.yaml, or deploy with your own
+        customized chart. For more information about customizing your HPCC
+        Systems containerized deployment see the above sections on
+        customization techniques.</para>
+
+        <para>In your chart, create a unique key name used to reference the
+        secret, and set it to the secret value that you created in the
+        previous step. In the above example it was
+        "admincredssecretname".</para>
+
+        <para>You can optionally define an additional alternate name, such as,
+        "admincredsaltmountname" which can be used with another Active
+        Directory server. The alternate name is illustrated in the example
+        below and should be added to your chart if necessary.</para>
+
+        <para>The "admincredsmountname" key/value pair already exists by
+        default in the HPCC Systems delivered values.yaml file. The key is
+        referenced in the component's ldap.yaml file. You may override these
+        and add additional key/values as needed.</para>
+
+        <programlisting lang="bash">  secrets:
+     authn:
+       admincredsmountname: "admincredssecretname"       #exernalize HPCC Admin creds
+       admincredsaltmountname: "admincredsaltsecretname" #exernalize alternate HPCC Admin creds
+</programlisting>
+      </sect3>
+
+      <sect3 id="ENABLE_k8S_LDAP">
+        <title>Enable LDAP Authentication</title>
+
+        <para>In the delivered
+        HPCC-Platform/esp/applications/common/ldap/ldap.yaml file, the
+        "ldapAdminSecretKey" is already set to the key mount name illustrated
+        in the example above. To enable LDAP authentication and to modify this
+        value, override the ESP/ECLWatch helm component located in values.yaml
+        as illustrated in the following example:</para>
+
+        <programlisting lang="YAML">esp:
+- name: eclwatch
+  application: eclwatch
+  auth: ldap
+  ldap:
+    ldapAddress: "myldapserver"
+    ldapAdminSecretKey: "admincredsaltmountname"   # use alternate secrets creds
+</programlisting>
+
+        <para> </para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="Configuring_For_HashoCorpVault">
+      <title>Configuring LDAP in HashiCorp Vault</title>
+
+      <para>To create and store secrets in the HashiCorp Vault, from the
+      command command line interface, execute the following Vault commands.
+      The secret name used in the example below is "myvaultadmincreds" and
+      must be prefixed with "secret/authn/" as illustrated. The HPCC Systems
+      administrator "username" and "password" key/values are required; and
+      additional properties are ignored.</para>
+
+      <programlisting>vault kv put secret/authn/myvaultadmincreds username=hpcc_admin password=t0pS3cr3tP@ssw0rd </programlisting>
+
+      <para>This stores the values for the HPCC Systems administrator username
+      and password into the HashiCorp Vault.</para>
+
+      <para>To verify and confirm the secret values, execute the following
+      command:</para>
+
+      <programlisting lang="bash">vault kv get secret/authn/myvaultadmincreds</programlisting>
+
+      <para>For more information about creating secrets for HashiCorp Vault
+      see the appropriate HashiCorp documentation for your
+      implementation.</para>
+
+      <sect3 id="Deploying_HashiCorpVault">
+        <title id="DeployingTheHashiCorpVault">Deploying the HashiCorp
+        Vault</title>
+
+        <para>You can deploy the HashiCorp Vault secrets when you override the
+        "secrets:" section in HPCC-Platform/helm/hpcc/values.yaml, or in your
+        customized configuration chart. For more information about customizing
+        your HPCC Systems containerized deployment see the above sections on
+        customization techniques.</para>
+
+        <para>The Vault name value is defined for this example in the
+        values-secrets.yaml configuration chart. You can find an example of
+        this chart in the HPCC-Platform repository under
+        /helm/examples/secrets/values-secrets.yaml.</para>
+
+        <programlisting lang="YAML">  vaults:
+  authn:
+    - name: my-authn-vault
+      #The data node in the URL is there for use by the REST API 
+      #The path inside the vault starts after /data
+      url: http://${env.VAULT_SERVICE_HOST}:${env.VAULT_SERVICE_PORT}/v1/secret/data/authn/${secret}
+      kind: kv-v2
+</programlisting>
+      </sect3>
+
+      <sect3 id="REF_HASHICORPVault_LDAP">
+        <title>Referencing Vault Stored Authentication</title>
+
+        <para>The key names "ldapAdminSecretKey" and "ldapAdminVaultId" are
+        used by the HPCC Systems security manager to resolve the secrets, and
+        must match exactly when using the Vault name set up in the previous
+        steps.</para>
+
+        <programlisting lang="YAML">esp:
+- name: eclwatch
+  application: eclwatch
+  auth: ldap
+  ldap:
+    ldapAddress: "myldapserver"
+    ldapAdminSecretKey: "myvaultadmincreds"
+    ldapAdminVaultId: "my-authn-vault"
+</programlisting>
+
+        <para> </para>
+      </sect3>
+    </sect2>
+  </sect1>
 </chapter>
diff --git a/vcpkg b/vcpkg