Changes for several issues related to SFTP and LDAP (#1252)

djwfyi · web-flow · commit 529e67dc7e34 · 2024-07-15T14:30:19.000-04:00
- Adds info the docs about recent changes to LDAP and SFTP authentication - Adds new config/envvar parameter - Adds new sftp option for server - Adds new example for forcing ldap or sa auth to SFTP - Adds new example for using certificate authority for auth to SFTP Closes #1240 Closes #1229 Closes #1226 Closes #1208
diff --git a/source/includes/common-minio-ad-ldap-params.rst b/source/includes/common-minio-ad-ldap-params.rst
@@ -34,6 +34,13 @@
 
    This parameter corresponds with the :envvar:`MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD` environment variable.
 
+.. mc-cmd:: user_dn_attributes
+   :optional:
+
+   .. include:: /includes/common-minio-external-auth.rst
+      :start-after: start-minio-ad-ldap-user-dn-attributes
+      :end-before: end-minio-ad-ldap-user-dn-attributes
+
 .. mc-cmd:: user_dn_search_base_dn
    :required:
 
diff --git a/source/includes/common-minio-external-auth.rst b/source/includes/common-minio-external-auth.rst
@@ -211,6 +211,24 @@ Specify the password for the :ref:`Lookup-Bind
 
 .. end-minio-ad-ldap-lookup-bind-password
 
+.. start-minio-ad-ldap-user-dn-attributes
+
+.. versionadded:: RELEASE.2024-06-06T09-36-42Z
+
+Comma-separated list of user DN attributes.
+
+Some valid values include, ``uid,cn,mail,sshPublicKey``.
+
+To enable public authentication for LDAP users, pass ``sshPublicKey`` as a DN attribute.
+The user can then use the passed SSH Public Key to log in to SFTP servers.
+
+.. code-block:: text
+   :class: copyable
+
+   mc idp ldap update ALIAS user_dn_attributes=sshPublicKey
+
+.. end-minio-ad-ldap-user-dn-attributes
+
 .. start-minio-ad-ldap-user-dn-search-base-dn
 
 Specify the base Distinguished Name (DN) MinIO uses when querying for 
diff --git a/source/includes/k8s/file-transfer-protocol-k8s.rst b/source/includes/k8s/file-transfer-protocol-k8s.rst
@@ -53,6 +53,7 @@ MinIO supports the following authentication providers:
 - :ref:`MinIO IDP <minio-internal-idp>` users and their service accounts
 - :ref:`Active Directory/LDAP <minio-external-identity-management-ad-ldap>` users and their service accounts
 - :ref:`OpenID/OIDC <minio-external-identity-management-openid>` service accounts
+- :ref:`Certificate Key File <minio-certificate-key-file-sftp-k8s>`
 
 :ref:`STS <minio-security-token-service>` credentials **cannot** access buckets or objects over SFTP.
 
@@ -165,3 +166,73 @@ If SFTP is enabled, the output resembles the following:
 
    enableSFTP: true
 
+.. _minio-certificate-key-file-sftp-k8s
+
+Connect to MinIO Using SFTP with a Certificate Key File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: RELEASE.2024-05-07T06-41-25Z
+
+
+MinIO supports mutual TLS (mTLS) certificate-based authentication on SFTP, where both the server and the client verify the authenticity of each other.
+
+This type of authentication requires the following:
+
+1. Public key file for the trusted certificate authority
+2. Public key file for the MinIO Server minted and signed by the trusted certificate authority
+3. Public key file for the user minted and signed by the trusted certificate authority for the client connecting by SFTP and located in the user's ``.ssh`` folder (or equivalent for the operating system)
+
+The keys must include a `principals list <https://man.openbsd.org/ssh-keygen#CERTIFICATES>`__ of the user(s) that can authenticate with the key:
+
+.. code-block:: console
+   :class: copyable
+
+   ssh-keygen -s ~/.ssh/ca_user_key -I miniouser -n miniouser -V +1h -z 1 miniouser1.pub
+
+-  ``-s`` specifies the path to the certificate authority public key to use for generating this key.
+   The specified public key must have a ``principals`` list that includes this user.
+- ``-I`` specifies the key identity for the public key.
+- ``-n`` creates the ``user principals`` list for which this key is valid. 
+  You must include the user for which this key is valid, and the user must match the username in MinIO.
+- ``-V`` limits the duration for which the generated key is valid. 
+  In this example, the key is valid for one hour.
+  Adjust the duration for your requirements.
+- ``-z`` adds a serial number to the key to distinguish this generated public key from other keys signed by the same certificate authority public key.
+
+MinIO requires specifying the Certificate Authority used to sign the certificates for SFTP access.
+Start or restart the MinIO Server and specify the path to the trusted certificate authority's public key using an ``--sftp="trusted-user-ca-key=PATH"`` flag:
+
+  .. code-block:: console
+     :class: copyable 
+
+     minio server {path-to-server} --sftp="trusted-user-ca-key=/path/to/.ssh/ca_user_key.pub" {...other flags}
+
+When connecting to the MinIO Server with SFTP, the client verifies the MinIO Server's certificate.
+The client then passes its own certificate to the MinIO Server.
+The MinIO Server verifies the key created above by comparing its value to the the known public key from the certificate authority provided at server startup.
+
+Once the MinIO Server verifies the client's certificate, the user can connect to the MinIO server over SFTP:
+
+.. code-block:: bash
+   :class: copyable:
+   
+   sftp -P <SFTP port> <server IP>
+
+Require service account or LDAP for authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To force authentication to SFTP using LDAP or service account credentials, append a suffix to the username.
+Valid suffixes are either ``=ldap`` or ``=svc``.
+
+.. code-block:: console
+
+   > sftp -P 8022 my-ldap-user=ldap@[minio@localhost]:/bucket
+
+
+.. code-block:: console
+
+   > sftp -P 8022 my-ldap-user=svc@[minio@localhost]:/bucket
+
+
+- Replace ``my-ldap-user`` with the username to use.
+- Replace ``[minio@localhost]`` with the address of the MinIO server.
diff --git a/source/includes/linux/file-transfer-protocol-not-k8s.rst b/source/includes/linux/file-transfer-protocol-not-k8s.rst
@@ -3,7 +3,7 @@
 Overview
 --------
 
-Starting with :minio-release:`MinIO Server RELEASE.2023-04-20T17-56-55Z <RELEASE.2023-04-20T17-56-55Z>`, you can use the File Transfer Protocol (FTP) to interact with the objects on a MinIO deployment.
+Starting with :minio-release:`MinIO Server RELEASE.2023-04-20T17-56-55Z <RELEASE.2023-04-20T17-56-55Z>`, you can use the File Transfer Protocol (FTP) or SSH File Transfer Protocol (SFTP) to interact with the objects on a MinIO deployment.
 
 You must specifically enable FTP or SFTP when starting the server.
 Enabling either server type does not affect other MinIO features.
@@ -67,7 +67,7 @@ Specifically:
 
 - For read operations, MinIO only returns the latest version of the requested object(s) to the FTP client.
 - For write operations, MinIO applies normal versioning behavior and creates a new object version at the specified namespace.
-  ``rm`` and ``rmdir`` operations create ``DeleteMarker`` objects.
+  ``delete`` and ``rmdir`` operations create ``DeleteMarker`` objects.
 
 
 Authentication and Access
@@ -223,3 +223,71 @@ The following example connects to an SFTP server, lists the contents of a bucket
    Fetching /runner/chunkdocs/metadata to metadata
    metadata                               100%  226    16.6KB/s   00:00
 
+Connect to MinIO Using SFTP with a Certificate Key File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: RELEASE.2024-05-07T06-41-25Z
+
+
+MinIO supports mutual TLS (mTLS) certificate-based authentication on SFTP, where both the server and the client verify the authenticity of each other.
+
+This type of authentication requires the following:
+
+1. Public key file for the trusted certificate authority
+2. Public key file for the MinIO Server minted and signed by the trusted certificate authority
+3. Public key file for the user minted and signed by the trusted certificate authority for the client connecting by SFTP and located in the user's ``.ssh`` folder (or equivalent for the operating system)
+   
+The keys must include a `principals list <https://man.openbsd.org/ssh-keygen#CERTIFICATES>`__ of the user(s) that can authenticate with the key:
+
+.. code-block:: console
+   :class: copyable
+
+   ssh-keygen -s ~/.ssh/ca_user_key -I miniouser -n miniouser -V +1h -z 1 miniouser1.pub
+
+-  ``-s`` specifies the path to the certificate authority public key to use for generating this key.
+   The specified public key must have a ``principals`` list that includes this user.
+- ``-I`` specifies the key identity for the public key.
+- ``-n`` creates the ``user principals`` list for which this key is valid. 
+  You must include the user for which this key is valid, and the user must match the username in MinIO.
+- ``-V`` limits the duration for which the generated key is valid. 
+  In this example, the key is valid for one hour.
+  Adjust the duration for your requirements.
+- ``-z`` adds a serial number to the key to distinguish this generated public key from other keys signed by the same certificate authority public key.
+
+MinIO requires specifying the Certificate Authority used to sign the certificates for SFTP access.
+Start or restart the MinIO Server and specify the path to the trusted certificate authority's public key using an ``--sftp="trusted-user-ca-key=PATH"`` flag:
+
+  .. code-block:: console
+     :class: copyable 
+
+     minio server {path-to-server} --sftp="trusted-user-ca-key=/path/to/.ssh/ca_user_key.pub" {...other flags}
+
+When connecting to the MinIO Server with SFTP, the client verifies the MinIO Server's certificate.
+The client then passes its own certificate to the MinIO Server.
+The MinIO Server verifies the key created above by comparing its value to the the known public key from the certificate authority provided at server startup.
+
+Once the MinIO Server verifies the client's certificate, the user can connect to the MinIO server over SFTP:
+
+.. code-block:: bash
+   :class: copyable:
+   
+   sftp -P <SFTP port> <server IP>
+
+Require service account or LDAP for authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To force authentication to SFTP using LDAP or service account credentials, append a suffix to the username.
+Valid suffixes are either ``=ldap`` or ``=svc``.
+
+.. code-block:: console
+
+   > sftp -P 8022 my-ldap-user=ldap@[minio@localhost]:/bucket
+
+
+.. code-block:: console
+
+   > sftp -P 8022 my-ldap-user=svc@[minio@localhost]:/bucket
+
+
+- Replace ``my-ldap-user`` with the username to use.
+- Replace ``[minio@localhost]`` with the address of the MinIO server.
diff --git a/source/reference/minio-mc-admin/mc-admin-group.rst b/source/reference/minio-mc-admin/mc-admin-group.rst
@@ -224,6 +224,8 @@ Syntax
       already exist. Use :mc-cmd:`mc admin group ls` to review the existing
       groups on a deployment.
 
+      A group name cannot contain the characters ``=`` (equal sign) or ``,`` (comma).
+
    .. mc-cmd:: MEMBERS
 
       The name of the user to add to the group.
diff --git a/source/reference/minio-mc/mc-idp-ldap-accesskey-create.rst b/source/reference/minio-mc/mc-idp-ldap-accesskey-create.rst
@@ -77,6 +77,7 @@ Parameters
    :optional:
 
    An access key to use for the account.
+   The access key cannot contain the characters ``=`` (equal sign) or ``,`` (comma).
 
    Requires :mc-cmd:`~mc idp ldap accesskey create --secret-key`
 
diff --git a/source/reference/minio-server/minio-server.rst b/source/reference/minio-server/minio-server.rst
@@ -192,6 +192,11 @@ The command accepts the following arguments:
         - Path to the user's private key file.
         - Absolute path or relative path from current location to the key file to use.
  
+      * - ``trusted-user-ca-key``
+        - Specifies a file containing public key of a certificate authority that is trusted to sign user certificates for authentication.
+          The file must contain a `user principals list <https://man.openbsd.org/ssh-keygen#CERTIFICATES>`__, and the list must include the user(s) that can authenticate with the key. 
+        - Absolute path or relative path from current location to the user's trusted certificate authority public key file.
+
       * - ``pub-key-algos``
         - Comma-separated list of the public key algorithms to support.
         - 
@@ -253,6 +258,9 @@ The command accepts the following arguments:
              hmac-sha1
              hmac-sha1-96
 
+      * - ``disable-password-auth``
+        - Disable password authentication.
+        - ``true``
 
    For example:
 
diff --git a/source/reference/minio-server/settings/iam/ldap.rst b/source/reference/minio-server/settings/iam/ldap.rst
@@ -198,6 +198,28 @@ User DN Search Filter
    :start-after: start-minio-ad-ldap-user-dn-search-filter
    :end-before: end-minio-ad-ldap-user-dn-search-filter
          
+User DN Attributes
+~~~~~~~~~~~~~~~~~~
+
+*Optional*
+
+.. tab-set::
+
+   .. tab-item:: Environment Variable
+      :sync: envvar
+
+      .. envvar:: MINIO_IDENTITY_LDAP_USER_DN_ATTRIBUTES
+
+   .. tab-item:: Configuration Setting
+      :sync: config
+
+      .. mc-conf:: identity_ldap user_dn_attributes
+         :delimiter: " "
+
+.. include:: /includes/common-minio-external-auth.rst
+   :start-after: start-minio-ad-ldap-user-dn-attributes
+   :end-before: end-minio-ad-ldap-user-dn-attributes
+
 Enabled
 ~~~~~~~
 
